Update Bill Lines
PATCH/api/bills/:bill/lines
Batch updates the lines of a bill. Replaces existing lines with the provided collection.
purchase-orders:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Authentication: Requires Bearer token. Permission: edit bills (bills.update, or purchase_orders.update). Scope: purchase-orders (read/write).
Refused with 422 when:
- the bill is booked in Xero / QuickBooks Online and brought in from there (on
bill): change it in the provider. - an expense bill's line would be left without an expense account, or would debit an inventory account (on
lines.{index}.nominal_code_id); the same account rules as Create Bill apply. - a line would be removed, or lowered below, while that much of it is tracked as cost entries or order cost lines (on
lines.{index}/lines.{index}.amount).
Body:
- lines (required): Array of bill line objects
- lines.*.id (optional): Existing line ID (omit for new lines)
- lines.*.description: Line description
- lines.*.quantity: Quantity
- lines.*.amount: Unit amount
- lines.*.nominal_code_id (optional, nullable): The line's debit (expense/clearing) account. Send an explicit null to CLEAR the nominal code on the line (it persists as null). OMIT the field entirely to leave an existing line's code untouched. No inventory_control default is frozen onto the line — when the line carries no code, the GL debit is resolved at posting time from the bill's link_type (landed-cost bills linked to a purchase order / warehouse transfer / inbound shipment capitalize to the configured inventory_control account).
- lines.*.tax_rate_id: Tax rate ID (optional)
- lines.*.cost_category_id (optional, nullable): Cost category ID
- lines.*.delete (optional, boolean): true removes the existing line
- lines.*.proration_strategy_override (optional, nullable): the line's Allocate by on a
category_defaultbill — one ofcost_based,volume_based,weight_based,quantity_based,specific_line,duty_estimate_based,customs_entry_based; null = its cost category's (manualis refused with 422). Omit it to leave the line's override unchanged.
customs_entry_based ("By customs entry") splits by the actual duty and fees filed on the customs entries linked to the bill (or, when the bill has none, to its purchase order or inbound shipment): each purchase order line's share of its matched entry lines' duty, plus its share of the entries' fees by value. The share on entry value no purchase order line covers is split by cost_based (allocation_warnings code customs_entry_partial_match, naming the entry lines in lines), and with no linked or matched entry the whole amount is (customs_entry_not_linked). It works as the bill's method, as a line's proration_strategy_override and as the duty category's Allocate by; on a category_default bill the duty category's lines split this way on their own once a fully matched entry is linked, unless its Allocate by is set. Linking, unlinking or re-matching an entry re-splits the bills that split by it.
Line sales channel: each line accepts an optional channel_integration_instance_id (integer, nullable): the id of a sales-channel integration instance the line's cost belongs to (for example a 3PL's order-level charges split by the channel of the orders they cover). It must name a sales-channel integration; any other integration instance (accounting, shipping, 3PL) or an unknown id is rejected with 422 on lines.{index}.channel_integration_instance_id. When the bill posts to Xero or QuickBooks Online, a line with a channel carries that channel's tracking option / class (from the Tracking Categories mapping); lines without one stay untagged.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.