Preview Bill Posting
POST/api/bills/preview-posting
Preview what saving a bill would do to the books: the journal lines it would post, the day it would post on, and whether it would be sent to the connected accounting system. Writes nothing.
purchase-orders:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Validation is lenient so a bill can be previewed while it is still incomplete: blank descriptions, accounts and amounts are accepted and shown as such.
Body (same shape as Create Bill):
supplier_id(required, integer) - an existing supplier.link_type(optional, defaultsupplier) -supplierfor an expense bill, orpurchase_order,warehouse_transfer,inbound_shipmentfor a landed cost bill.invoice_date(optional, date, nullable).posting_date(optional, date, nullable) - the intended posting day; defaults toinvoice_date.currency_id(optional, integer, nullable),currency_rate(optional, number > 0, nullable) - amounts are converted to the tenant currency at this rate, else the currency's current rate.bill_id(optional, integer, nullable) - a saved bill being previewed: its own stored rate and posting date are used unless the request changes them, so the preview shows what the bill posts rather than today's rate.lines(required key, array, max 500):lines.*.description(optional, string, nullable)lines.*.quantity(optional, number, default 1)lines.*.amount(optional, number, default 0) - unit amount.lines.*.nominal_code_id(optional, integer, nullable)lines.*.tax_rate_id(optional, integer, nullable)lines.*.cost_category_id(optional, integer, nullable)
Response fields:
kind-expenseorlanded_cost.lines[]- journal lines in the tenant currency, grouped by account:account_id,account_label,debit,credit,document_debit,document_credit(the same amounts in the bill's own currency),needs_account. Each line debits its own account, else its cost category's default account; a landed cost line without either debits the purchase clearing account, and an expense line without either showsneeds_account: true("Needs an account"). Tax debits the purchase tax account and Accounts Payable is credited with the total.posting_date- the day the bill would post on.posting_date_movedis true when the date falls inside a locked period: the bill keeps its invoice date and posts on the first open day afterlock_date.sync-mode(send: SKU.io creates the bill in the provider on save;provider_owned: this supplier's bills are entered in the provider, so SKU.io does not send it;sku_only: stays in SKU.io;none: no accounting system connected),provider_labeland a plain-languagemessage.inventory_message- whether the cost goes into inventory cost (landed cost) or is expensed.needs_account- true when any line has no account; such a bill does not post until one is picked.posting_currency_code- the currency the journal amounts are in (the tenant's base currency).document_currency_code- the bill's own currency.currency_rate- bill currency x rate = posting currency.rate_source-bill(the rate saved on the bill),entered(sent ascurrency_rate),current(the currency's rate today) orbase(no conversion).rate_as_of- the local day acurrentrate was read, else null.refused_message- set on an expense bill when a line's account is one saving refuses (inventory, accrued purchases, goods received not invoiced, accounts payable or an Inventory-type account); null otherwise. Saving that bill returns 422 with the same message.
Authentication: Requires Bearer token. Permission: create bills (bills.create, or purchase_orders.create). Scope: purchase-orders (read/write).
Request
Responses
- 200
- 401
- 403
- 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.
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.