Skip to main content

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.

Required scope: purchase-orders:write

Grant 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, default supplier) - supplier for an expense bill, or purchase_order, warehouse_transfer, inbound_shipment for a landed cost bill.
  • invoice_date (optional, date, nullable).
  • posting_date (optional, date, nullable) - the intended posting day; defaults to invoice_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 - expense or landed_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 shows needs_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_moved is true when the date falls inside a locked period: the bill keeps its invoice date and posts on the first open day after lock_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_label and a plain-language message.
  • 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 as currency_rate), current (the currency's rate today) or base (no conversion). rate_as_of - the local day a current rate 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​

OK

Response Headers
    Content-Type