Order confirmations
An order confirmation confirms an agreed order. Like a
quote it is a pre-sales document — it produces
no journal entry and is never booked — but it sits one step further along the
chain and converts only into an invoice. Reads require the
order-confirmations-read scope and writes order-confirmations-write. The
shared line model, reads, and email delivery are in
Billing documents.
Lifecycle
Code
The stored status covers draft / sent; displayStatus adds the
server-derived converted state (the status list filter accepts draft,
sent, converted). A converted order confirmation is read-only. The invoice it
produces is the booked document.
Create a draft
POST /v1/order-confirmations requires customerId, date, and lines — the
same shape as a quote draft,
minus validUntil (which is quote-only). PATCH /v1/order-confirmations/{id}
replaces the editable fields and line items wholesale. The documentNumber stays
null until the document is sent.
Status values
Order confirmation status is one of draft, sent, converted.
Send
POST /v1/order-confirmations/{id}/send allocates the number, renders the PDF,
and marks it sent — Manual (default) or Email, with the recipient resolving
from recipientEmail, else the customer contact, else the customer email. Sproom
does not apply. Preview with GET /v1/order-confirmations/{id}/pdf?draft=true.
This matches the quote send.
Convert
An order confirmation converts only with target: "invoice" (a quote can also
target an order confirmation; this is the last pre-sales step). It must be sent
first — converting a draft returns 400 SALES_DOCUMENT_CONVERT_REQUIRES_SENT.
Code
The source's fields and line items are copied verbatim unless you supply a
document payload to adjust the target. A document converts only once — the
source becomes read-only and its convertedToInvoiceId points at the booked
invoice. The conversion error codes match those for quotes (see
Quotes → Errors).
Webhooks
See Webhooks for endpoint setup, the signed envelope, and signature verification.
| Topic | Fires when |
|---|---|
order_confirmation.sent | Fired when an order confirmation is sent to the customer. |
order_confirmation.converted | Fired when an order confirmation is converted into an invoice. |