Skip to main content

Get Purchase Invoice

GET 
/api/purchase-invoices/:purchase_invoice

Get a single purchase invoice with full detail including lines, financial lines, payments, and accounting transaction.

Required scope: purchase-orders:read

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token.

The purchase_order object includes total_invoiced — the discount-netted amount billed across every invoice on the purchase order (not just this one). Subtract it from purchase_order.total for the amount still to be invoiced on the order.

is_provisional is true for committed-spend bills auto-created at PO submission; these are managed automatically and cannot be edited, paid, archived, or deleted.

installment_schedule appears only when the bill's payment term settles its remainder in more than one final-goods-invoice tranche (e.g. 40% at each shipment's dispatch, 40% net 30 on its receipt). Each entry carries the tranche's own due date, amount, settled and outstanding figures; the bill's due_date tracks the earliest tranche still owed and advances automatically as payments settle earlier tranches.

due_date_source is derived (calculated from the payment term), manual (typed, imported or read from the supplier's document) or none. due_date_basis explains where the date came from:

  • kind — manual; shipment (a linked shipment's event on a per-shipment payment-term line); order (an order-level event or estimate); bill_date (the invoice's own date on a Bill Date line); term (the payment term's own calculation); held (the stored date differs from what the basis resolves to today — a settled bill keeps its deadline, and a derived date is never degraded); or none
  • label — the explanation in words
  • shipment_id, shipment_number — the shipment the date is taken from, when kind is shipment
  • basis_field — which date was used, e.g. dispatched, planned_etd, received_at, invoice_date, or a projection source such as shipment_etd / po_etd
  • basis_date — that date (YYYY-MM-DD)
  • is_forecast — true when the basis date is still an estimate (for example a planned dispatch), so the due date will move once the real date is known
  • offset_days — days added to the basis date
  • needs_shipment_link — see below

needs_shipment_link (also repeated at the top level of the invoice) is true when the payment term dates invoices per shipment but no shipment is linked to this invoice yet: the due date shown is the order-level fallback and will move once a shipment is linked — see Link Inbound Shipment to Invoice and Auto-Link Inbound Shipments.

Each entry in financial_lines is a cost line (freight, packaging, duties, ...) billed on this invoice. amount is the unit amount and quantity the units billed; extended_amount is the stored line value (quantity × amount × (1 − discount_rate), before tax) and is what the invoice total sums. tax_allocation carries the line's tax separately.

Approval policy: The response adds approval — the approval-policy summary for this bill's payment: policy_enabled (false when no policy governs bill payments; the other fields are then null/empty), request_id, status, reason, tier_name of the latest approval request, waiting_on (names of users who can act now), can_approve_directly (whether you can approve it now; on a document with no request yet, whether its amount falls within your limit) and blocked_reason. Full timeline: GET /api/approval-requests/for/bill_payment/{id}. Bills add approved_amount / approved_amount_base (the amount a completed payment approval authorized, in bill and base currency) and, on single-bill responses, approved_remaining (how much of it payments have not yet used; null on list rows). This is the payment approval, separate from the bill's own approval_status.

Tax: each bill line carries its own tax_rate_id and tax_allocation (the tax the supplier charged on that line, defaulting to the purchase order line's tax for the quantity billed). tax_total adds the line tax on top of the lines unless purchase_order.is_tax_included is true (prices already include tax), plus any tax on additional cost lines. purchase_order.total_invoiced is the total billed across every bill on the purchase order, tax included.

Request​

Responses​

OK