API / Concepts
Document lifecycle
The statuses every document moves through, which endpoints move them, and what can still change after posting.
All ten document types share one status machine. Where a type has extra states of its own (a sales invoice's payment-side state, a bill's processing state), they sit on top of this one and are described on the resource's pages.
The statuses
| Status | Meaning | Ledger effect |
|---|---|---|
DRAFT |
Editable. No document number yet. | None |
APPROVAL_PENDING |
Submitted to an approval workflow and waiting. Light dry-runs the posting first, so a document that could not post is never sent for approval. | None |
APPROVED |
Approved, not yet posted. | None |
POSTED |
Ledger lines exist. Accounting data is frozen. | Yes |
PARTIALLY_CLEARED |
Posted, and part of the open balance has been settled by a payment or credit. | Yes |
CLEARED |
Posted and fully settled. | Yes |
ARCHIVED |
Finished. A draft that was archived, or a posted document that was reversed and not reopened. | Reversed |
There is no REVERSED status. Reversing a posted document either returns it to DRAFT (to edit and post again) or archives it, and it keeps its document number either way. Sales invoices additionally expose a Reversed state in their own state machine for the reverse-and-reissue flow.
Status changes are verbs, not fields
You cannot set status on any document. Each transition is an action endpoint that runs the checks for that transition. The pattern across resources:
| Transition | Endpoint pattern |
|---|---|
| Draft into approval, or straight to posted | …/submit-for-approval, …/post. Journal entries post at creation with shouldPost: true. |
| Approval pending to approved or declined | …/approve, …/decline |
| Sales invoice issued to the customer | …/open, then …/send-email |
| Posted to settled | Payments and credits: …/mark-as-paid, …/payments, or linking a credit note or customer credit |
| Anything to archived | …/archive. A posted journal entry is reversed and archived in one step. |
| Back to draft | …/reset, where the resource offers it |
The reference lists the exact set for each resource. If an endpoint is missing for a transition you need (there is no call to post an existing draft journal entry, for example), the transition is not available through the API, and the page says so.
What you can change, and when
- Draft: everything. Header, lines, currency, dates, tax settings, rate overrides.
- Posted: nothing that touches the ledger. Amounts, accounts, dates and tax are frozen. Metadata still moves: custom properties, and type-specific fields such as a purchase-order reference on a sales invoice. These edits are allowed even in a closed period, because they change no ledger line.
- To change a posted amount: reverse (which returns the document to draft), edit, post again. In the product this is one operation; through the API it is the sequence of endpoints the resource exposes. The document number is kept, and the ledger shows the original lines, the reversing lines and the new lines.
Two kinds of number
documentSequenceId(AP/001/000000042): assigned at first posting, per entity and document type, never reused, never reset. Drafts have none. Gaps are possible.documentNumberon a sales invoice (for exampleINV-2026-00042, the entity's template decides): assigned when the invoice is opened, gap-free, and the number the customer sees. A bill'sinvoiceNumberis the vendor's number, copied from their invoice.
Reading a document back
A document's own endpoint returns its header and lines as entered. Its ledger lines, including the tax, balancing and rounding lines Light added, are on List ledger transaction lines filtered by accDocId. Journal entries are the special case: the API has no read endpoint for them, so read the header from List accounting documents and the lines from the ledger once posted.
Next: Periods and locks.