Skip to content

Pricing Use Cases ​

Pricing (src/modules/pricing/) exposes the price list of an organization, one list per currency, and one in-process contract Sales uses to price a sale. Derived from the controller, the use cases, 0090_pricing.sql and the tests cited by PRICING_CASE_MATRIX.md. Diagram: SYSTEM_FLOWS.md section 8.

1. What is built ​

All routes need a bearer session and X-Organization-Id, and the permission organization-wide.

RouteUse casePermission
GET /price-listPR1 list the price listpricing.prices.view
PUT /price-listPR2 replace the price listpricing.prices.manage
PriceResolutionContract.currentPrices (in-process)PR3 price a salenone; called by Sales
PATCH /price-listPR4 edit prices as a deltapricing.prices.manage
GET /price-list/items/{itemId}PR5 price now and next of an itempricing.prices.view
GET /price-list/variants/{variantId}/historyPR6 history of a variantpricing.prices.view

manage is held by organization_owner and manager; view by those two and by cashier, waiter, bar and sales_associate.

Not built: price lists beyond the default one per currency, price list names, customer or channel lists, modifier price deltas, combo prices, discounts and promotions, tax-inclusive selling (Sales refuses it), exchange rates. Price dimensions are in progress.

2. PR1 List the price list ​

Query: currency (ISO 4217, three letters; default is the currency of the organization), variantId, limit (1 to 100, default 50), after, before. The cursor is signed and bound to the organization and the filters; replaying it with another variantId is 400 collection.cursor_incompatible. Entries are ordered by variant. Each entry: entryId, variantId, price (a decimal string without trailing zeros, tax exclusive). entryId is the id a sale records when it resolves the price. The answer is never cached.

3. PR2 Replace the price list ​

Body: { "currency"?, "entries": [{ "variantId", "price" }] }, at most 5000 entries. price is a decimal string with up to 13 digits before the point and six after it, no sign, no exponent. The body is the whole list for one currency:

  • a variant with the same price keeps its entryId;
  • a variant with another price gets a new entryId and the old price stays as closed history;
  • a variant left out loses its price; an empty list clears the list;
  • the lists of the other currencies are never touched;
  • replaying the same body changes nothing;
  • the answer counts what changed (added, repriced, removed, entries, currency).

Every variant must belong to the default catalog of the organization; one that does not (or does not exist) is 422 pricing.price_list_refused and nothing is written. A currency that is not in the reference data is also refused with 422. A malformed body (unknown field, a sign, an exponent, more than six decimals, a repeated variant, more than 5000 entries) is 400 foundation.validation_failed. A member without the permission is 403 pricing.action_forbidden. One audit record pricing.price_list.replaced with the counts is written per replacement.

The list is stored as the single default tax-exclusive price book of the organization for that currency, in the default catalog; a price book is unique per catalog, currency and code (migration 0153).

4. PR3 Price a sale ​

currentPrices(variantIds, currency) answers, for each variant, the entry in effect now in the active default book of that currency: priceBookEntryId and amount. An inactive book is ignored. An entry stays visible until its closing instant, so a sale that began before a replacement is still priced at the entry in effect when it began. A variant with no current entry is not in the answer and Sales refuses it with 422 sales.price_unresolvable. A price scheduled for the future is not used, and a replacement leaves it untouched.

5. PR4 Edit prices as a delta ​

Body: { "currency"?, "set": [{ "variantId", "price", "validFrom"? }], "remove": [variantId] }, up to 500 changes. Variants not named keep their price. An equal price changes nothing and keeps its entryId; a different one closes the current entry (kept as history) and opens a new one. With validFrom (a future UTC instant) the price is scheduled: the current one stays until it starts. Replaying the same schedule changes nothing; another schedule for a variant that already has one is 409 pricing.price_schedule_conflict. A start in the past, or a variant outside the organization, is 422 pricing.price_list_refused. Editing and replacing never run at once for one currency. One audit record pricing.price_list.edited with the counts.

6. PR5 Price now and next of an item ​

One read: for each non-archived variant of the item, the price in effect and the next scheduled one, in the currency asked (default: the organization's). A variant without a price answers null so the front can flag it. An unknown item, one of another organization and a member without the permission all get 403 pricing.action_forbidden.

7. PR6 History of a variant ​

Every version of the price, newest start first, keyset paging. Scheduled versions are included; the current one has no validUntil unless a later one is scheduled. Each version says who wrote it and when, shown only to members who manage prices. An unknown, foreign or never priced variant answers an empty list. The cursor is bound to organization, variant and currency.

8. Errors ​

StatusCodeWhen
400foundation.validation_failed, collection.cursor_*Malformed query or body, tampered, expired or incompatible cursor
401identity.session_requiredNo live session
403pricing.action_forbidden, tenant.context_rejectedNo organization-wide permission, or tenant rejected
409pricing.price_schedule_conflictA second schedule for a variant that has one
422pricing.price_list_refusedA variant outside the default catalog, an unknown currency, or a start in the past

Application Foundation in progress. Tracked in issue #13.