Skip to main content

Update Bill

PUT 

/api/bills/:bill

Update a bill's header data and, for a landed cost bill, its allocations. Lines are changed with Update Bill Lines.

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).

Fields:

  • invoice_number (required): Updated invoice number; must not be used by another bill.
  • invoice_date (required): Updated invoice date (YYYY-MM-DD)
  • posting_date (optional, nullable): The date the bill posts to the general ledger (YYYY-MM-DD). Null means it posts on its invoice date. Leave it out to keep the current value; send null to clear it.
  • supplier_id (required): Supplier ID. Must be a service-type supplier when it changes. An expense bill's link follows its supplier.
  • currency_id (optional): Currency ID; leave it out to keep the bill's currency. currency_rate (optional): Exchange rate
  • payment_term_id (optional, nullable): Payment term ID
  • proration_strategy (optional): The landed cost bill's split; see the allowed values below
  • allocations (optional): Updated allocations array (replaces existing). Refused with 422 on an expense bill.
  • link_type, link_id (optional): accepted only when they keep the bill's kind. An expense bill can't become a landed cost bill or the other way round (422 on link_type: delete the bill and enter it on the purchase document).
  • duplicate_acknowledged (optional, boolean, default false): on an expense bill, changing the supplier or invoice number to one the supplier already has is refused with 422 on invoice_number unless this is true.

A bill booked in Xero / QuickBooks Online and brought in from there (is_booked_in_provider) is read-only: updating it returns 422 on bill. Change it in the provider.

Allowed proration_strategy values: cost_based, quantity_based, weight_based, volume_based, specific_line, revenue_based, manual, duty_estimate_based, customs_entry_based, category_default. duty_estimate_based ("By estimated duty") splits the bill across purchase order lines in proportion to each line's estimated customs duty — the duty frozen at receipt, or the shipment-stage estimate for units not yet received. If every covered line's estimated duty is zero it falls back to cost_based and the bill response carries an allocation_warnings entry with code duty_estimates_zero_fallback. 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.

This endpoint sets the bill-level strategy only. To give individual lines their own Allocate by (proration_strategy_override, for example customs_entry_based on the duty line of a category_default bill), use Update Bill Lines.

due_date (optional, Y-m-d): set the due date by hand. On update, leaving it out keeps the current date and sending null goes back to the date the payment term gives.

Once costs are tracked from the bill (cost entries or order cost lines), currency_id and currency_rate can't change, including clearing them; the response is 422.

Request​

Responses​

OK

Response Headers
    Content-Type