Quotes and sales orders

A quote offers a customer lines at a price; an accepted quote becomes a sales order, and the order is invoiced in full or in parts by ordinary customer invoices. Nothing here posts: the books change only when an invoice of the order is posted. The decisions are in ADR-0053; every operation is in the generated reference (tag "sales"), and the web UI (Sales > Quotes, Sales > Sales orders, and New quote on a customer's card) calls the same operations.

A quote

On the quote and order forms each field says what goes in it; a quote's valid-until day is one click away (1, 2 or 3 months after its date), and declining, withdrawing, cancelling and closing the rest offer the common reasons.

Step	What happens
Create	`POST /v1/entities/{entity}/quotes`: a draft numbered `QT-YYYY-NNNNNN` at once. The currency and payment terms default to the customer's, the valid-until day to 30 days on. Each line is priced as an invoice of that day would be: the product's price and VAT, the VAT determined for the customer. `opportunity_id` names the deal it is for: one of the same customer, not lost; it never changes, the quote keeps its customer, and its order is for the same deal (ADR-0095).
Change	`PATCH /v1/sales-documents/{id}` while it is a draft or sent; a sent quote that is changed (Revise on its card) is a draft again, as its next version. A new date moves the valid-until day with it.
Hand over	`POST .../send` e-mails the PDF in the customer's language with a link to answer it online (never from a test copy, only by a person); `POST .../mark-sent` records a hand-over another way. The quote is then `sent`.
Accept	`POST .../accept` (the day, at the latest today, and the customer's reference), or the customer on the quote's link: the quote is `accepted` and its sales order is made, `open`, with the same lines and terms.
Decline or withdraw	`POST .../decline` or `.../cancel` with a reason. Final.

Past its valid-until day a quote reads expired: it is neither sent nor accepted until its day is changed.

Versions and online acceptance

A quote starts at version 1. Changing it once it was sent begins the next version; what the customer got stays as it was. The first time each version is handed over its PDF is kept, and the quote's Online and versions tab lists every version with its PDF (GET .../revisions/{n}/pdf). From version 2 the PDF says which version it is. The decisions are in ADR-0088.

Every quote e-mailed by this server carries a link (/app/quote/...), and Make a link to share on the tab makes one to pass on yourself (POST .../links; it is shown once). On the link the customer sees the current version without signing in, in their language (they can switch it), downloads the PDF, and accepts it with their name (and their order number, if they like) or declines it. The answer names the version they read: a quote changed, expired or answered since takes none, and while it is being revised the page says a new version follows. The tab shows who each link was given to, when it was last opened, the customer's answer (name, time, internet address, browser and the fingerprint of the PDF they accepted), and Turn off for a link.

An accepted quote makes its order as a person's acceptance does. Above the customer's credit limit the customer's acceptance still stands, and the order waits as a draft for a person to confirm.

A sales order

An order comes from an accepted quote, or is entered directly (POST /v1/entities/{entity}/sales-orders, numbered SO-YYYY-NNNNNN) and confirmed (POST .../confirm).

Status	Meaning
`draft`	Entered directly, not yet confirmed; it can be changed.
`open`	Confirmed; to be invoiced.
`partially_invoiced` / `invoiced`	Shown, not stored: what its invoices (drafts and invoices waiting for approval included, void and rejected ones not) add up to per line.
`closed`	Closed for the rest (`POST .../close` with a reason): what was invoiced stays, the rest of each line is no longer invoiced.
`cancelled`	Withdrawn while nothing was invoiced.

POST /v1/sales-documents/{id}/invoice drafts a customer invoice of everything left, or of the quantities given per line. Each invoice line names its order line; the order's customer reference (or its number) is the invoice's order reference, and the due date follows the order's payment terms. The draft is checked, approved, posted and sent like any invoice. No invoice, by this operation or by hand, ever invoices more of a line than was ordered: the check runs when the lines are written and again when the invoice posts.

Discounts

Each line takes a Discount, a percent or an amount (the button at the end of the field switches), and the document a Document discount on the lines after their own discounts. VAT is charged on the discounted net; a document discount is split over the lines by what each is worth, so each VAT rate carries its share. The order keeps the quote's discounts, and each invoice of the order takes them: a percent as it is, an amount by the part invoiced, the last invoice taking what is left. See ADR-0055.

The PDF

GET /v1/sales-documents/{id}/pdf is the invoice's layout in the customer's language (or ?language=), titled Offerte / Offre / Offerta / Quote or Auftragsbestätigung / Confirmation de commande / Conferma d'ordine / Order confirmation, with the lines, VAT and totals and the payment terms the invoice will carry; a quote also says until when it is valid. It has no payment part.

Controls

Nothing is deleted: a quote or an order is declined, cancelled or closed, keeping its number.
Once handed over or decided, a document's lines and amounts no longer change (database triggers).
Agents may read and draft quotes and orders; only a person sends one to a customer, makes a link to it or records the customer's answer.
An order that would take the customer above its credit limit is not confirmed, nor a quote accepted into one: the refusal names what the customer would owe and its limit (credit limits). What is left to invoice on open orders counts towards the customer's credit exposure.
Every change, hand-over, decision and invoice is in the document's history (GET .../history).