Appearance
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. OpenAPI wins for the shape of a route, the code for behavior. The flow as a diagram: 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:
- Replays the stored order when the key was already used by an identical request, before admitting anything again (SL3).
- 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_forbiddenas a member without the permission. - 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. - Asks Catalog to admit the lines for that business unit and outlet (
CatalogSellableContract.admit). A line that is not sellable there is422 sales.lines_not_sellablewith one entry per refused line indetail. - When a line chooses combo components, asks
pricing.resolve_cartwhich bundle group each belongs to, so Catalog can admit the combo; the chosen options go to Catalog as selections. - Calls
sales.take_orderin one transaction: it re-checks the permission and the currency of the outlet; prices the whole cart once withpricing.resolve_cartfor the outlet, channel, menu and service mode now (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 with422 sales.price_unresolvableand nothing is written; a variant with an explicit price of0sells at zero with sourceprice_book. - 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 |
| Business-day cutoff | Settings (resolve_setting) | SQL only |
| Stock deduction | Inventory (reservations, ledger) | Inside sales.take_order |
| Audit record | Audit (TenantAuditContract) | sales.order.taken |