Get Bill
GET/api/bills/:bill
Get a bill with its supplier, lines, allocations, ledger entries and related purchase document data.
purchase-orders:readGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Bill kinds. A bill is either an expense bill (no purchase document: link_type supplier, linked to its own supplier) or a landed_cost bill (linked to a purchase order, warehouse transfer or inbound shipment, its cost added to the inventory cost of that document's items). An expense bill is never allocated to purchase lines.
Authentication: Requires Bearer token. Permission: view bill details (bills.show, or purchase_orders.index). Scope: purchase-orders (read/write).
Kind, origin and accounting:
kind-expenseorlanded_cost.origin-manual,ocr,import,api(created with a Personal Access Token) orprovider.is_booked_in_provider,booked_in_provider_at,booked_provider_label- a bill booked in Xero / QuickBooks Online and brought in from there. SKU.io keeps a read-only copy: updating it, its lines or its payments returns 422 onbill.accounting_state-inbound,voided(booked in the provider and since voided or deleted there),needs_action,posted,duplicate,kept,pendingornone(see List Bills);accounting_provider-Xero,QuickBooksor null.accounting_attention- set only whileaccounting_stateisneeds_action, else null:title,message(the provider's own message, e.g. a locked period or an archived account),operation_id,entry_id,entry_url(the ledger entry's app path) andneeds_attention_url(the app path of Ledger → Needs Attention, scoped to the entry's month).needs_account- true for an expense bill with a line that has no account; it does not post until one is picked.
Cost tracking and delete: cost_tracked_amount is what is tracked from the bill as cost entries or order cost lines, in the bill's currency. A bill with anything tracked cannot be deleted: can_delete is then false and delete_blocked_reason says why.
Lines: each line carries nominal_code_id and nominal_code (id, code, name, type): the account the line debits, or null when it has none of its own.
Payment approval: payment_approval_status (not_requested, pending_approval, approved, rejected) and the approval summary describe the bill's payment request under the tenant's bill payment approval policy. approval.policy_enabled is false when no policy is on; every amount may then be paid. Under the policy, approval.payable_now is the most a new payment may put on the bill right now (the approved amount less payments recorded since it was approved), approval.waiting_on names who a pending request waits on, and approval.approved_amount is what the last completed approval authorized.
foreign_currency_posting says what this document puts into the books. treatment is document (posts in the supplier's currency, so the accounting provider books realised FX on payment) or base (posts in the base currency). provider is the connected accounting provider, or null with none connected. setting_enabled is the current state of "Send supplier bills in their own currency". The value is null for a base-currency document, when the ledger is off, and for documents that stay out of the accounts.
Request
Responses
- 200
- 401
- 403
- 404
- 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
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.