# Order confirmations

An order confirmation confirms an agreed order. Like a
[quote](/guides/billing-documents/quotes) 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](/guides/billing-documents/overview).

## Lifecycle

```text
draft → sent → convert → invoice
```

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](/guides/billing-documents/quotes#create-a-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](/guides/billing-documents/quotes#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`.

```bash
curl -X POST 'https://api.ledgerbee.com/api/v1/order-confirmations/0197a943-2325-7829-b835-b6c71a293066/convert' \
  -H 'x-api-key: <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{ "target": "invoice" }'
```

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](/guides/billing-documents/quotes#errors)).

## Webhooks

See [Webhooks](/guides/webhooks) for endpoint setup, the signed envelope, and
signature verification.

{/* @codegen webhook-topics-order-confirmation — generated by `pnpm docs:generate`; do not edit by hand */}

| 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. |

{/* @codegen-end webhook-topics-order-confirmation */}