---
url: /reference/SALES_USE_CASES.md
---
# Sales Use Cases

Sales (`src/modules/sales/`) takes one kind of order: a counter sale of items
with stock, closed in one call. Derived from the controller, the use case,
`0110_sales.sql` and the tests cited by
[`SALES_CASE_MATRIX.md`](SALES_CASE_MATRIX.md). OpenAPI wins for the shape of a
route, the code for behavior. The flow as a diagram:
[`SYSTEM_FLOWS.md`](SYSTEM_FLOWS.md) section 7.

## 1. What is built

Both routes need a bearer session and `X-Organization-Id`.

| Route                                     | Use case          | Permission at the outlet |
| ----------------------------------------- | ----------------- | ------------------------ |
| `POST /outlets/{outletId}/sales`          | SL1 take an order | `sales.orders.take`      |
| `GET /outlets/{outletId}/sales/{orderId}` | SL2 read an order | `sales.orders.read`      |

Both are held by `organization_owner`, `manager`, `cashier`, `waiter`, `bar`
and `sales_associate` (`0110_sales.sql`). A permission counts only at the
outlets its role assignment covers, so a cashier of one outlet cannot sell or
read at another.

Not built: payments and cash movements, till and cash shifts, credit,
discounts and promotions, tax (a sale is tax exclusive and carries none),
modifier and combo choices on a line, cancellation, returns, tables, kitchen
tickets, choosing a sales channel, offline replay, order lists and search. The
`sales.*` tables for some of them exist and have no route.

## 2. SL1 Take an order

Actor: a member who holds `sales.orders.take` at the outlet.

Request: `Idempotency-Key` header (a UUID) and a body of one to 100 lines, each
`{ "variantId", "quantity", "options"?: [{ "optionId", "itemModifierGroupId"? }],
"bundleChoices"?: ["bundleGroupItemId"] }`, plus the order-level `channelId?`,
`serviceMode?`, `menuId?` and `overrides?: [{ "poolId", "approvalId" }]`.
`quantity` is a positive decimal string with at most six decimals; an option or
combo component chosen twice is listed twice. The body is closed: an unknown
field, including any price, is `400 foundation.validation_failed`.

The server, in order:

1. Replays the stored order when the key was already used by an identical
   request, before admitting anything again (SL3).
2. Resolves the outlet and the business unit that operates it today. An outlet
   that is unknown, outside the member scope or of another organization answers
   the same `403 sales.action_forbidden` as a member without the permission.
3. Resolves the regional profile of the outlet (`organization.outlet_regional_profile`):
   the sale is made in the currency of the outlet, not in a currency the client
   names. The request has no currency field.
4. Asks Catalog to admit the lines for that business unit and outlet
   (`CatalogSellableContract.admit`). A line that is not sellable there is
   `422 sales.lines_not_sellable` with one entry per refused line in `detail`.
5. When a line chooses combo components, asks `pricing.resolve_cart` which
   bundle group each belongs to, so Catalog can admit the combo; the chosen
   options go to Catalog as selections.
6. Calls `sales.take_order` in one transaction: it re-checks the permission and
   the currency of the outlet; prices the whole cart once with
   `pricing.resolve_cart` for the outlet, channel, menu and service mode now
   ([`PRICING_USE_CASES.md`](PRICING_USE_CASES.md)); freezes the list and
   resolved amounts, price book entry, price rule and source of every line, the
   chosen options and combo components with their charges, and requires a
   tax-exclusive book; draws the quota pools once (`operations.take_capacity`)
   after its own lock; dates and numbers the order; supplies the stock; closes
   the order. The client never sends a price. A variant nobody prices is refused
   with `422 sales.price_unresolvable` and nothing is written; a variant with an
   explicit price of `0` sells at zero with source `price_book`.
7. Writes one tenant audit record `sales.order.taken` (none on a replay).

Answer `201` with `data`: `orderId`, `orderNumber`, `businessDate`, `status`
(`closed`), `currency`, `total`, `replayed`, `serviceMode` (the mode of the request, stored on the order and immutable, `null` when none was sent), and `lines[]` of `lineId`,
`lineNumber`, `variantId`, `quantity`, `supplyOutcome`, `listAmount`,
`resolvedAmount`, `priceSource` (`price_book`, `price_rule`),
`optionsAmount`, `bundleAmount`, `lineAmount`, `options[]` (`optionId`,
`itemModifierGroupId`, `name`, `quantity`, `unitCharge`) and `bundleChoices[]`
(`bundleGroupId`, `bundleGroupItemId`, `groupName`, `name`, `quantity`,
`unitAdjustment`) as frozen on the line, and `warnings[]` of
`{ code: "oversold", poolId }` for each warning quota that was exceeded. Money is
a six-decimal string: each line is `round(quantity x (resolved price + options +
combo adjustments), 6)` and the total is the exact sum, with no rounding to the minor unit of the currency. An exact replay
answers `200` with `replayed: true`, the same order, and the `Idempotent-Replayed`
header.

| `supplyOutcome`      | Meaning                                                |
| -------------------- | ------------------------------------------------------ |
| `reserved`           | Stock deducted                                         |
| `untracked`          | Item does not track stock; nothing deducted            |
| `unrouted`           | Tracks stock but has no supply route; nothing deducted |
| `recipe_not_handled` | Item has a recipe; ingredients are not consumed        |

| Status | Code                                                | When                                                                                                                                                                                                                                                             |
| ------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `foundation.validation_failed`                      | Missing or non-UUID `Idempotency-Key`, non-UUID outlet id, an unknown field, an empty body or more than 100 lines                                                                                                                                                |
| 401    | `identity.session_required`                         | No live session                                                                                                                                                                                                                                                  |
| 403    | `sales.action_forbidden`                            | No `sales.orders.take` at this outlet, outlet outside the scope, unknown or foreign outlet                                                                                                                                                                       |
| 403    | `sales.approval_required`, `sales.approval_invalid` | An override approval of an exhausted quota is missing or does not fit the pool, the sale or the member                                                                                                                                                           |
| 403    | `tenant.context_rejected`                           | The caller does not belong to the organization named by `X-Organization-Id`                                                                                                                                                                                      |
| 409    | `sales.insufficient_stock`                          | Not enough stock; the whole sale aborts and nothing is sold                                                                                                                                                                                                      |
| 409    | `sales.capacity_exceeded`                           | A blocking quota pool of the sale is exhausted and no valid override was sent; nothing is sold and the detail names no pool                                                                                                                                      |
| 409    | `sales.currency_mismatch`                           | The currency of the sale is not the currency of the outlet, or the price books that apply mix currencies or tax inclusions or differ from the currency of the outlet                                                                                             |
| 409    | `sales.item_unavailable`                            | A variant, option or combo component of the sale is blocked at the outlet (manual 86); nothing is sold                                                                                                                                                           |
| 409    | `idempotency.key_reused`                            | The key was used with another request, including another `serviceMode`, channel, menu, option group or override set                                                                                                                                              |
| 422    | `sales.lines_not_sellable`                          | Catalog refuses a line for this outlet                                                                                                                                                                                                                           |
| 422    | `sales.price_unresolvable`                          | A variant, option, combo component, channel, menu or service mode is unknown or belongs to another organization, or a variant has no price in the price books that apply                                                                                                                                                  |
| 422    | `sales.order_refused`                               | A quantity with more than six decimals or not above zero, an outlet with no business unit or legal entity today, an organization with no default currency, a line priced from a tax-inclusive book, or an option or combo choice that does not fit the item sold, including a combo whose required group is left without a choice (its default components do not fill it) |

### Business date

`businessDate` is the site-local date minus the cutoff
(`organization.site_business_date`). The cutoff is the setting
`operations.business_day.cutoff_minutes` (0 to 1439), resolved outlet, outlet
group, business unit, organization, and set over REST with
`PUT /settings/{code}/assignment`. At 01:30 with a 02:00 cutoff the order
belongs to the previous day, with that day's number, business unit and legal
entity.

## 3. SL2 Read an order

Answer `200`: the order as the sale answered it, without `replayed`; never
re-priced. `Cache-Control` is private. An unknown order and one the member
cannot see are the same `404 sales.order_not_found`; no permission at the
outlet is `403 sales.action_forbidden`. A member who may take but not read can
still replay their own sale (SL3).

## 4. Boundaries

| Concern                                            | Owner                                    | Note                                                                  |
| -------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------- |
| Is the line sellable here                          | Catalog (`CatalogSellableContract`)      | Same rule as the till read                                            |
| Prices, options and combo charges                  | Pricing (`pricing.resolve_cart`)         | Books by outlet, channel, menu and mode; rules and schedules          |
| Quotas                                             | Operations (`operations.take_capacity`)  | Drawn once per sale; release on cancel belongs to the cancel use case |
| Currency, country, time zone, locale of the outlet | Organization (`outlet_regional_profile`) | [`CURRENCY_AND_LANGUAGE.md`](CURRENCY_AND_LANGUAGE.md)                |
| Business-day cutoff                                | Settings (`resolve_setting`)             | SQL only                                                              |
| Stock deduction                                    | Inventory (reservations, ledger)         | Inside `sales.take_order`                                             |
| Audit record                                       | Audit (`TenantAuditContract`)            | `sales.order.taken`                                                   |
