---
url: /reference/PRICING_USE_CASES.md
---
# 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`](PRICING_CASE_MATRIX.md). Diagram:
[`SYSTEM_FLOWS.md`](SYSTEM_FLOWS.md) section 8.

## 1. What is built

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

| Route                                                | Use case                          | Permission              |
| ---------------------------------------------------- | --------------------------------- | ----------------------- |
| `GET /price-list`                                    | PR1 list the price list           | `pricing.prices.view`   |
| `PUT /price-list`                                    | PR2 replace the price list        | `pricing.prices.manage` |
| `PriceResolutionContract.currentPrices` (in-process) | PR3 price a sale                  | none; called by Sales   |
| `PATCH /price-list`                                  | PR4 edit prices as a delta        | `pricing.prices.manage` |
| `GET /price-list/items/{itemId}`                     | PR5 price now and next of an item | `pricing.prices.view`   |
| `GET /price-list/variants/{variantId}/history`       | PR6 history of a variant          | `pricing.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

| Status | Code                                                  | When                                                                               |
| ------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------- |
| 400    | `foundation.validation_failed`, `collection.cursor_*` | Malformed query or body, tampered, expired or incompatible cursor                  |
| 401    | `identity.session_required`                           | No live session                                                                    |
| 403    | `pricing.action_forbidden`, `tenant.context_rejected` | No organization-wide permission, or tenant rejected                                |
| 409    | `pricing.price_schedule_conflict`                     | A second schedule for a variant that has one                                       |
| 422    | `pricing.price_list_refused`                          | A variant outside the default catalog, an unknown currency, or a start in the past |
