Payable ( payable )
Calculated projection of what the merchant still owes a supplier: open invoices minus credit notes and allocations from actually executed disbursements, with separate views of overdue and disputed amounts.
Role
payable is the Accounts Payable counterpart of the receivable on the customer side. It is not a standalone business resource with its own ID: it is functionally identified by supplier and merchant and recalculated from current documents and payment allocations.
Payable answers “how much do we still owe this supplier?”. A supplier_payment answers “which disbursement did we request or execute?”. The two concepts are linked through allocations but are not interchangeable.
How payable is calculated
Payable aggregates non-canceled, non-fully-settled supplier documents, subtracts credit notes and allocations attached to executed `supplier_payment` objects, then exposes the current projection and its events.
The calculation includes:
- supplier invoices that are not canceled and not fully settled;
- supplier credit notes as negative amounts in the balance;
payment_allocationallocations whose source is asupplier_paymentwith statusexecuted;- document due date and dispute state to calculate overdue and disputed sub-balances.
Only allocations from actually executed executed disbursements reduce projected debt. A pending or scheduled instruction is not yet a realized cash movement.
Available balances
| Field | Question |
|---|---|
balance_excluding_tax / balance_including_tax | What total balance remains owed to the supplier? |
balance_due_* | How much of that balance is already overdue at calculation time? |
balance_disputed_* | How much of the total balance belongs to disputed documents? |
balance_due_disputed_* | How much is both overdue and disputed? |
balance_due_undisputed_* | How much overdue debt can be handled outside dispute? |
oldest_due_date / latest_due_date | What is the time range of documents still open? |
computed_at | At what time was this projection calculated? |
Amounts use common.amount : integers in the currency's minor unit.
Supplier credit notes
A supplier_invoice with type=credit_note reduces payable. When it references a source invoice, the calculation reuses that invoice's due date and dispute state to correctly determine overdue and disputed sub-balances.
This lets a credit note correct the debt without creating a false supplier payment. The accounting document and cash movement remain separate facts.
Disbursements and allocations
An executed supplier_payment does not by itself indicate which invoices it settles. The accounting link is carried by a payment_allocation whose source_type=supplier_payment and whose targets may be a supplier invoice, supplier credit note, purchase order, or unallocated portion. The allocation whose targets may be a supplier invoice, supplier credit note, purchase order, or unallocated portion.
Payable subtracts amounts actually allocated to the relevant invoices and credit notes. This separation supports one disbursement covering several documents, a partial payment, or an allocation corrected later.
Due dates and disputes
A document is considered overdue when its due date is before calculation time and a residual balance remains. Disputed amounts stay included in total debt but are isolated in the balance_disputed_* fields so your process can distinguish normal supplier-payment handling from dispute handling.
The projection refuses to mix multiple currencies in one supplier payable: when open documents use different currencies, calculation fails rather than summing incomparable amounts.
Events
payable.updated— the total projection balance changes.payable.overdue— the supplier has a positive overdue balance for a new eligibility episode.payable.zero— the total balance transitions from a positive value to zero.
Time events are rearmed when the condition stops being true: a supplier that becomes current again may therefore produce a new payable.overdue episode if overdue debt appears later.
Use
The projection is available from the supplier through GET /v1/companies/:id/payable. It is especially useful for payment planning, internal reminders, dispute control, and Accounts Payable reconciliation.
- Use
balance_due_undisputed_*to prioritize overdue, undisputed debt. - Use
oldest_due_dateto order suppliers by age of debt. - Keep the supplier invoice as the source of document detail; payable is a summary.
- Create and execute distinct
supplier_paymentobjects when moving from projection to disbursement action.