Skip to main content

Update Bill Lines

PATCH 

/api/bills/:bill/lines

Batch updates the lines of a bill. Replaces existing lines with the provided collection.

Required scope: purchase-orders:write

Grant 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_default bill — one of cost_based, volume_based, weight_based, quantity_based, specific_line, duty_estimate_based, customs_entry_based; null = its cost category's (manual is 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​

OK

Response Headers
    Content-Type