Promotions, combo sets, coupons and promo codes

Резюме по-русски. Скидка в Vizen — это ПРАВИЛО магазина («условие → эффект»), а не поле товара. Видов правил пять: четыре считают скидку, пятый (issue_key) ничего не считает, а выдаёт купон за покупку. У каждого есть класс — ступень, на которой оно срабатывает: построчная, заказная и «за ключом» (промокод/купон). Промокод и купон — одна сущность, различаются владельцем. Комбо-набор — это отдельный ТОВАР с составом, а не скидка. Пустой /promotions означает «у этого магазина нет правил», а не «платформа такого не умеет» — см. §5. Общую картину скидок (что действует само, что ждёт промокод, лучшие предложения) отдаёт один запрос /promotions/landscape, и ранжирует её сервер, а не клиент — §3.7. Цену товара ВНУТРИ набора карточка отдаёт готовыми полями in_combos[].item_*: в подстановках своей вёрстки нет выражений, поэтому «в наборе вдвое дешевле» иначе посчитать нечем — §3.8.

Status: current · Verified: 2026-08-22, full integration suite against 18 isolated PostgreSQL databases (46 integration files) · Owner: promo line (Track: promo) Serves: GET /docs/promotions (live: 200 text/markdown) · Machine reference: promotions.BuildPromoReference() — kinds, the kind × class matrix, the ladder, reject reasons, rounding, contract field sets and limits all come from the same constants, validator and engine the server runs on.

Every enumerable list below sits between <!-- gate:… --> markers, and reference_test.go compares the set in the document against the reference — so a list here cannot go stale in silence. What the gates check is the fact, not the wording: the set of codes, the set of fields, the order of the steps. Prose between the markers is yours to rewrite.

1. What you can do here

Read which rules a shop has, create and edit them, attach promo codes to a rule, cap several rules with one campaign budget, have the shop grant a personal coupon for a purchase or hand one to a named buyer yourself, apply a code to the buyer's cart, and read the resulting prices.

The server owns every price: a client never sends money amounts for the cart or the order, and a discount you compute yourself will not survive checkout. This is worth internalising before writing anything here — most mistakes in this area come from trying to reproduce the arithmetic on the client.

The same reasoning gives you two ready-made answers instead of a calculation: the shop's whole discount picture with its offers already ranked (§3.7), and the price of a product inside a combo set on its card (§3.8).

2. Decide first (forks)

The last row is the fork that cost a whole rebuild once. Read own-markup.md before you decide to hand-render prices.

3. Objects and where they live

3.1 The rule — /promotions

GET    /promotions            list of this shop's rules      → promotions:read
GET    /promotions/{id}       one rule (foreign → 404)       → promotions:read
POST   /promotions            body {"item": {...}}           → promotions:write
PUT    /promotions/{id}       body {"id":…, "item": {...}}   → promotions:write
DELETE /promotions/{id}       body {}                        → promotions:write

A rule has two independent axes. Getting them confused is the most common mistake in this area:

• `kind` — *what* it does: product_discount, order_discount, bundle, gift, and issue_key — which is not a discount at all, see the table below.
• `class` — *when* it fires: item (per line) → order (whole order) → key (only when a code is applied). Empty class means "the class this kind had before classes existed": order_discount → order, everything else → item.

Within one class only the single best rule applies. Classes stack in the order above. class: "key" currently requires kind: "order_discount" — the key step reads an order-shaped condition, and other combinations are rejected on write.

The three classes are the first three steps of a five-step ladder. The other two are not rules and have no class, which is exactly why they get forgotten:

<!-- gate:ladder -->

<!-- /gate -->

⚠️ `condition` and `effect` are `bytes` on the wire — base64 of raw JSON, not objects. This is the single most common 400 in this area. The shape depends on kind; unknown keys are rejected, not ignored:

<!-- gate:kinds -->

<!-- /gate -->

A bundle or gift set with product_ids: [] and category_ids: [] is refused on write, not stored and quietly matched against nothing. The class column is the whole matrix: any other combination is a 400 — the machine reference carries it as Kinds[].Classes, and a gate test replays every pair through the real validator, so this column cannot become a wish.

Compatibility flags on the rule: stack_with_key (default true; false means promo codes do not apply while this rule fires), exclude_combo (default false; skip combo products), applies_to_discounted (class key only, default false: the code is computed only from lines without a per-line discount).

audience_id is an optional reference to the shop's reusable buyer audience. Omitted on create means public. Omitted on edit preserves the current binding, so an older client cannot publish a private promotion by renaming it; explicit 0 makes it public. A foreign/deleted audience is rejected with PROMOTION_AUDIENCE_INVALID. Audience filtering happens in the repository before rules reach the pricing engine and is repeated for cards, lists, marketplace/wishlist projections, guest quote, signed-in cart, promo-code lookup, coupon issue and checkout. The owner-only list and landscape still show all rules for management. The staged customer_audiences_enabled shop flag is fail-closed: while off, only public promotions apply.

None of those three flags reaches a gift, and that is structural rather than an oversight. A gift is not a discount: the engine materialises it as a virtual line *after* the key step, so its value is in no subtotal, in no threshold, in no applied[], and in neither base a promo code can be computed from — with applies_to_discounted on or off. stack_with_key: false on a gift rule therefore changes nothing (§5). The ladder order is what keeps this safe: computing gifts one step earlier would make every gift kill every promo code in the shop, because a gift line carries no stack_with_key of its own.

Money guard: a class: "key" rule with {amount} must carry condition.min_subtotal strictly greater than that amount, otherwise the write is rejected. A coupon worth 10 000 with no threshold hands over goods for free.

3.2 The key — /promo-keys

A key does not define a discount; it unlocks a rule. Promo code and coupon are one object: a key without an owner is a shared promo code, a key with an owner is a personal coupon. Coupons appear two ways, and both end in the same row of the same table: the platform grants one for a completed purchase (§4.6), or the seller hands one to a named buyer (§4.10).

GET    /promo-keys?promotion_id=&with_coupons=   → promotions:read
POST   /promo-keys      body {"item": {...}}     → promotions:write
PUT    /promo-keys/{id} body {"id":…,"item":{…}} → promotions:write
DELETE /promo-keys/{id} body {}                  → promotions:write

PromoKey — the whole field set: id, promotion_id (a class: "key" rule, immutable after creation), code, owner_user_id, expires_at, usage_limit (0 = unlimited), per_customer_limit, active, and read-only used, created_at, issued_by_order_id. id and promotion_id arrive as strings (int64 on the wire).

owner_user_id is the entire difference between the two kinds of key: 0 (or omitted) creates a shared promo code, a real account id creates a personal coupon for that account. It is checked on creation — an id that belongs to nobody is refused rather than stored, because a coupon nobody can redeem still occupies its code in the shop — and immutable afterwards: send it back unchanged on PUT, and to move a coupon to another person delete it and issue a new one. A coupon created without limits gets usage_limit: 1 and per_customer_limit: 1; a shared code gets neither.

Codes are matched case- and whitespace-insensitively (upper(trim())), and are unique per shop.

3.3 The campaign — /promo-campaigns

A campaign is a spending cap over several rules: "we issued a million worth of coupons". When the budget is out, its rules stop applying by themselves.

GET    /promo-campaigns          → promotions:read
POST   /promo-campaigns          → promotions:write
PUT    /promo-campaigns/{id}     → promotions:write
DELETE /promo-campaigns/{id}     → promotions:write

PromoCampaign: name, budget_kind (none | spend | count), budget_limit (0 for none), active, starts_at?, ends_at?, and read-only budget_used, budget_warned (true from 80% — you want to know before it stops, not after) and promotions_count.

Attach a rule by setting Promotion.campaign_id. Deleting a campaign does not disable its rules — it removes the cap.

Two things worth knowing before you rely on it:

• the budget grows from every applied rule of the campaign, not only from promo codes;
• only the promo-code step can be cancelled outright, so only it refuses an order when the budget is short (CAMPAIGN_BUDGET_SPENT). For an ordinary promotion the order still goes through — the buyer has already seen that price — so the budget may overshoot by at most one sale, and the next orders no longer see the rule.

3.4 The buyer's coupons — /my-coupons

GET /my-coupons?company_id=&include_used=   → the buyer's own coupons only

MyCoupon — the whole field set: id, code, name and description (taken from the rule the coupon unlocks — the buyer reads the same wording they will see in the cart), expires_at?, used, expired, issued_by_order_id. Someone else's coupon is neither listed nor findable. issued_by_order_id: 0 means the coupon was not granted by a purchase — a seller handed it over (§4.10); do not render "for order #0".

3.5 The buyer side — /cart/promo, and /cart/quote before login

POST   /cart/promo    {"company_id":…, "code":"SUMMER25"}   → the whole cart
DELETE /cart/promo    {"company_id":…}                      → the whole cart
POST   /cart/quote    {"company_id":…, "items":[…], "promo_code":"SUMMER25"}
                                                            → the whole cart, no token

Both return the same body as GET /cart/items. Two fields matter: result.promo_code (applied code, empty if none) and result.promo_rejected — a stable reason code, not a message:

<!-- gate:reject-reasons -->

NOT_FOUND · EXPIRED · EXHAUSTED · PER_CUSTOMER · RULE_INACTIVE · BELOW_THRESHOLD · NO_ELIGIBLE · NOT_STACKABLE · NO_EFFECT · BUDGET_SPENT

<!-- /gate -->

The authoritative list is generated — promotions.BuildPromoReference().RejectReasons — and a gate test fails if the server sends a code this document does not know, or if the document promises a code the server never sends. That check exists because both mistakes already happened here.

The first four and the last six are different kinds of refusal, and the interface should say so (RejectReasons[].stage): NOT_FOUND, EXPIRED, EXHAUSTED and PER_CUSTOMER are verdicts on the code itself — the cart cannot fix them. The other six come from the engine and are verdicts on this cart: "add 1 500 more" is honest advice, "the code is invalid" is not.

A rejection is not an HTTP error: the cart is always returned, so the buyer keeps seeing their items. A foreign personal coupon answers NOT_FOUND on purpose — a distinct reason would confirm that the code exists.

A guest hears the same answers. POST /cart/quote (orders.md §4.4) takes a promo_code with no token and fills the same promo_code / promo_rejected pair from the same code path, so the verdict on a code does not change at login — that is the point of the endpoint: a visitor should not have to sign in to find out whether the code from the newsletter works. Two consequences to design for:

• the code is shown, never spent. A quote moves neither promo_keys.used nor promo_redemptions, however many times it is called; redemption happens inside the checkout transaction and nowhere else. A "code applied" screen is therefore not a reservation — the last use can still be taken by somebody else, and expected_total at checkout is what protects the buyer from finding out silently (§3.6);
• a personal coupon (§3.4) answers NOT_FOUND to a guest. There is no buyer to match owner_user_id against, and the mask is the same one a foreign coupon gets. Word it as "sign in to use this code", not "invalid code" — the visitor holding a coupon addressed to them is the one person for whom the mask is misleading.

3.6 Checkout

POST /cart/confirm accepts expected_total — the sum the buyer saw. If the recomputed order differs (a promotion ended, the last use of a code was taken by someone else), the call fails with PRICE_CHANGED instead of quietly creating an order at a different price. Send 0 or omit it to keep the old behaviour. Two more refusals can arrive here, both FailedPrecondition: PROMO_CODE_EXHAUSTED (the code was taken between the cart and the order) and CAMPAIGN_BUDGET_SPENT (the campaign budget ran out in the same window).

The order that comes back does not spread order-level discounts over its lines. Read §3.9 before you sum anything on it.

3.7 The whole picture in one call — GET /promotions/landscape

GET /promotions/landscape?limit=24     → promotions:read

Answers "what is on sale in this shop right now" without you matching rules to products. The shop is the one behind the token — there is no `company_id` parameter and no public variant: this is a cabinet/agent endpoint, and a token without a company gets PermissionDenied.

result:

PromoOffer: kind (product | combo), product_id, name, slug, price, old_price, benefit (money), benefit_percent (whole percent, rounded DOWN — a benefit shown to a buyer is a promise, and rounding it up would advertise a discount the shop does not give), promotion_name (the rule that gave the cut; empty for combo). preview is filled: the product's own preview when it has one, otherwise the first image of its gallery — the same rule the card and the listings use, so the same product carries the same picture everywhere. It is empty only when the product has neither. Pictures are resolved after the ranking cut, so a large catalogue costs one batch for the offers actually returned, not for everything scanned.

Ranking is deterministic and belongs to the server: benefit_percent desc → benefit desc → product_id asc. Percent leads because "−50%" is an offer, while "−5 000 ₽" without a base is nothing. limit is 0…100 (0 or omitted = 24; above 100 → 400, it is a validated field, not a clamp).

How the list is built, because it explains every surprise below: products are not selected by SQL "where there is a discount" — a discount is produced by the engine, not stored in a column. The server takes published products in batches, newest first (ORDER BY id DESC), and runs each through the very same engine that prices a product card. Ceilings: 500 products and 200 combo sets. They are reported (scanned_products, truncated) because a silent cut would read as "this shop has nothing else on sale".

What never appears in top_offers, so you do not go hunting:

• rules of class order or key — an offer is a per-product price, and those two are computed against a whole cart;
• kind: "issue_key" rules — they are missing from both rule lists as well: a coupon granted on a completed order is an issuance, not a price cut anyone can see today;
• unpublished or deleted products, and combo sets with an unavailable component or with no benefit at all.

One more thing that is true today and costs nothing to know: a dev-contour PAT reads the live shop here. This endpoint builds no dev contour, so what it returns is production data even for a key that sees your draft elsewhere.

An offer does not have to come from a rule. The test is "old_price is above price", so a product the seller marked down by hand (its own base_old_price) is an offer too, with an empty promotion_name — which is exactly what its card shows as well. For a product offer, price / old_price are byte-for-byte the card's numbers: same engine, same base. A combo offer goes through a separate path, and both of them now measure "sum of parts" the same way — see below.

Two defects this section used to warn about are fixed (2026-08-20, commit ac88c77), and the warnings are gone with them. They are worth one paragraph because both were of the kind that reads as correct data:

1. the rule lists were filtered by active and campaign budget only, so a rule whose ends_at was yesterday was still advertised as live. The lists now run the same period predicate the engine does — a rule that has ended, or has not started, is in neither list. Green: TestB5Landscape_ExpiredRuleIsNotAdvertisedAsActive;
2. a combo offer measured "sum of parts" from base prices while the card measured it from showcase prices, so a discounted component made the landscape advertise a set that was more expensive than buying the parts apart. Both now measure it from showcase prices. Green: TestB5Landscape_ComboBenefitMatchesCardWhenComponentIsDiscounted.

3.8 The price of a product inside a set — in_combos[].item_*

On a product card (GET /products/{id}, GET /products/slug/{slug}) in_combos[] lists the sets this product belongs to. Beside the set-level combo_price / components_total / benefit, three fields describe this product inside that set:

Why fields and not arithmetic: substitutions in own markup have no expressions — {{ }} cannot divide or compare — so a "в наборе вдвое дешевле" line cannot be written any other way; and a second computation on the storefront would drift from the cart on rounding, because the in-set price is floored server-side.

item_times_cheaper_x100 is 0 in exactly the cases where "cheaper" would be a lie: the in-set price is not lower than the regular one, either price is zero, or the component is price_mode: "free" — a gift has no ratio. Render a gift from item_price == 0, not from the ratio.

The value is an integer scaled by 100 on purpose (money and shares are integers here, Р-43). An agent that generates markup reads it and writes the wording once, at build time; a template that can only substitute should place item_price and item_regular_price ("в наборе N ₽ вместо M ₽") and treat the ratio as a signal, not as text — nothing on the storefront reformats hundredths for you.

One asymmetry worth remembering: the shop owner sees sets with no benefit at all (benefit may even be negative — a promotion on the components made them cheaper apart than together). That is deliberate: the admin list "Входит в комбо" has to show exactly the sets that are broken. A public visitor never sees them. So "in_combos is non-empty" does not mean "there is a benefit" when the caller is the shop.

3.9 Reading the money on an order

An order line is a snapshot of what the position cost — a fact of the deal, not a running total. Order-level steps (an order discount and a promo code) reduce items_total but are not spread across the lines. So the first thing every importer does — sum line_total — returns the total *before* the code, and nothing in the payload shouts about it.

That is deliberate. Rewriting a line snapshot after the fact would rewrite the price the buyer agreed to. Use the identities below instead; they hold whatever combination of mechanics fired.

Telling the steps apart — by kind inside promotions[]:

kind is a reliable discriminator, not a coincidence: the validator refuses class: "order" and class: "key" on any kind but order_discount, so an order-level entry can never arrive wearing product_discount or bundle.

Telling a gift apart — promotion.kind == "gift" on the line. A gift has unit_price: 0, line_total: 0, and base_unit_price holding its *value* — a number that appears in no total of the order. Exclude gift lines from every sum below. (The cart says this with a dedicated is_gift flag; the order does not have one yet.)

Let R = lines that are not gifts, K = promotions[] entries with kind == "order_discount", I = the remaining promotions[] entries.

base_unit_price: 0 means "no per-line discount here", not "the price was zero" — fall back to unit_price.

The total before discounts is a sum you compute, not a field you read. On an order it is items_total + discount_total (identity 2); on a cart, the same thing is subtotal + discount_total. The cart does carry a field of that name, and it is the wrong number to strike through: the server fills subtotal_before while it computes discounts, and a shop with no live promotion never runs that step at all — such a cart can answer subtotal_before: 0 with real goods in it, and a storefront that trusts it strikes through zero and advertises "−100 %". The field starts carrying a number the moment the shop has one active rule, even one this cart does not match, so it follows the seller's settings rather than the cart's contents: "it was right when I checked" says nothing about the next shop. The sum of the two fields is right on every server, and it is the only form the order side offers at all — so write the formula once and use it in both places.

Worked example (−15 % on one position, −10 % on the order, −10 % by code):

{ "items_total": 3130, "discount_total": 870,
  "items": [
    {"product_id":1,"unit_price":850,"base_unit_price":1000,"quantity":2,"line_total":1700,
     "promotion":{"id":7,"kind":"product_discount","amount":300}},
    {"product_id":3,"unit_price":2000,"base_unit_price":0,"quantity":1,"line_total":2000}
  ],
  "promotions": [
    {"id":7,"kind":"product_discount","amount":300},
    {"id":8,"kind":"order_discount","amount":370},
    {"id":9,"kind":"order_discount","amount":200,"code":"SUMFIX"}
  ] }

3700 − (370 + 200) = 3130. Summing the lines alone gives 3700 — 570 more than the order is worth.

There is no per-line share of an order discount in the contract, on purpose. The platform does compute one, but only for the fiscal receipt, where the law requires the sum of positions to match the amount charged to the kopeck: it is proportional to line_total, with the rounding remainder placed in the last non-zero position. Need such a share yourself — compute it the same way, and treat it as derived: a different rounding gives different numbers, and only identities 1–4 agree on both sides.

An order freezes every sum at checkout and is never recomputed when the rules change afterwards, so these identities still hold a year later. Money is whole currency units (roubles, not kopecks).

Verified by internal/api/catalog/promo_order_sums_integration_test.go (TestB5Sum*): a promo code plus an order discount, a gift line, and a shop margin cap that trims the order step.

3.10 Rounding — where the fraction goes

Money here is whole currency units, so every percentage has to land somewhere. The rule is not the same in every place, and the difference is exactly one unit — invisible in a contract, visible in a cart. Recomputing a price on the storefront with "the obvious" rounding is how a page and the cart start quoting two numbers for the same item.

<!-- gate:rounding -->

<!-- /gate -->

Two consequences worth reading twice:

• the per-line step rounds the price, the order and key steps round the discount — opposite halves of the same subtraction. The same "−50%" on a 3 ₽ position takes 1 ₽ off as a per-line rule and 2 ₽ off as an order rule. Neither is a bug; asking which one is "correct" is asking which of the two numbers the shop promised;
• everything a buyer reads as a promise rounds down: the offer's percent, the "twice cheaper" ratio, the in-set price. 49.6 % prints as "−49 %", because a shop that advertises more than it gives is caught by the first person who adds up their cart.

A gate test calls the three reachable formulas on a number where the two modes disagree, so the table cannot describe a rounding the code no longer does.

3.11 One cart through every layer

Every section above answers one question. This one answers the question sellers actually ask: *what will my buyer pay?* One cart, four paid lines, run through all seven price layers, with the number at every step and the arithmetic that produced it. The last number is the one that reaches the till.

The shop. Catalogue:

Rules:

The cart. Four paid lines, each priced by a different layer:

Line Г is the one that surprises people. The card advertises 8 000 and the cart charges 10 000, and nothing is broken: base_price on a configurable product is a "from" price, while the buyer pays for the thing they assembled — data.price.total from the configurator. That snapshot is not a hint. It is the price, and it is the number that flows into every layer below: into the subtotal before discounts, into the point where both thresholds are measured, and into the promo code base. Layers 2 and 3 are mutually exclusive on one line — a product has either variants or a configurator — but not in one cart, which is why both А and Г are here.

Step by step.

Plus a gift line: the plaid, unit_price: 0, base_unit_price: 5000 (its value), is_gift: true. It appears in no total, does not move any threshold, and is not in applied[]. The cart's count is 5 — four paid lines and the gift.

Checkout changes none of it. The order comes back with items_total: 60000 and discount_total: 20000, three entries in promotions[] (10 000 / 7 000 / 3 000 — the last one carrying code: "VIZEN20"), and all four identities of §3.9 hold on it. The configuration snapshot of line Г travels to the order untouched, price and breakdown both: unit_price is what you charge, data is what you build.

What did not fire, and why. The "−30 % on armchairs" rule is live for the whole time this cart exists. It is returned by GET /promotions/landscape as an active promotion, and the armchair really is offered at 7 000 in that shop. It simply never touches this cart, because there is no armchair in it — and the lamp therefore pays its full 10 000, with promotion absent and base_unit_price: 0 on its line. This is the most useful line in the whole example: a discount is a rule of the shop with a condition, not a property of a line. "The rule is on" and "the rule applied" are two different facts, and only the second one is in applied[].

Two more things that did not fire, and their absence is measured: nothing merged line А with line Г (layer 0, product_groups, never touches price — it only switches the buyer between cards), and no second order rule competed, because "one best" is decided inside a class.

Change one thing. Same shop, same rules, same settings — remove the lamp:

Read the two carts side by side and the machinery becomes visible. Removing a 10 000 lamp lowers the bill by 6 000, not by 10 000, because that lamp was holding up three separate things: it carried the cart over the 70 000 order threshold, it contributed a quarter of the promo code base, and it made the discounts large enough for both limiters to bite. The seller who priced this cart by subtracting the lamp's price would be 4 000 out.

The 70 000 threshold is the sharpest edge here. Both carts have a subtotal before discounts of 80 000 and 70 000 — measured there, the order rule would fire in both. It is measured after the per-line step, so it fires in one and not the other. The promo code threshold is measured at the very same point, 70 000 rather than the 63 000 that is left after the order step — which is worth knowing before you set a code's min_subtotal next to an order rule's.

Verified by internal/api/catalog/promo_worked_example_integration_test.go (TestB5Doc_WorkedExample): every number above is asserted against a live Postgres — 96 assertions across the two carts, including the two numbers this section computes but the cart response does not return as fields (the threshold reference point and the promo code base), the amount the shop cap trimmed (measured by switching the cap off on the same cart), and the point at which the code's threshold is measured (measured by raising it into the gap between 63 000 and 70 000). Change the engine and the build tells you which line of this section went stale.

3.12 The gift on a product card — product_promotions[].gift

A product card (GET /products/{id}, GET /products/slug/{slug}) carries product_promotions[] — the live rules that touch this product, for a "why is this interesting" block. No money in them: {id, name, description, kind, theme, icon}. A kind: "gift" entry carries one thing more — the gift product itself, so the card can show it the way a set shows its components instead of describing it in prose:

gift is absent in exactly three cases, and all three are deliberate:

• the rule is not a gift. No other kind hands a product out, so no other kind has anything to put there;
• this card is the gift itself — then the plaque carries the reverse side, triggers[] (below), instead of showing the product to itself;
• the gift is not available right now — unpublished, or stock does not cover the rule's own quantity (stock_quantity: null means stock is not tracked, hence available — §5). The plaque itself stays, description and all; what stops is the promise of a specific item. Availability is decided by the same resolver that hands gifts out in the cart and in the order, so the card cannot drift away from them into advertising a gift checkout would withhold.

One asymmetry worth knowing: the card cannot see the cart. If the buyer is already paying for units of that same product, the stock the gift needs grows (giftNeed, §5), and a gift the card showed can still be withheld at checkout — without moving any total, and without the buyer paying anything else. The card measures the smallest possible need, the level below which the rule can never fire; the opposite error would be both worse and invisible — staying silent about a gift that does work.

The other side of the same plaque — triggers, on the gift's own card

A gift product is still a product: buyers land on its card from search, from a category, from a link. There the interesting question is the reverse one — what do I have to buy to get this for free? So on the card of the gift itself the same kind: "gift" plaque arrives with gift empty and three fields filled instead:

Read the pair as: show a couple of strips inline, and if triggers_total is larger than what you showed, offer the rest — the array holds at most 12, and if triggers_total > len(triggers) even your "show all" list is a sample, not the whole set.

Rules of the reverse side:

• one side at a time. gift and triggers never arrive together on the same plaque: the card either tells you what you get, or what to buy for it;
• a product that is both the trigger and the gift ("buy two, the third is free") stays on the gift side — gift filled, triggers empty. The reverse side there would be a strip pointing the card at itself;
• only published, live triggers are listed and counted, for the same reason the gift disappears when it is unpublished: a strip is an invitation to buy, and slug empty still means publish no link;
• a category that no longer resolves (deleted, or belonging to another shop — products.categories has no FK) is dropped rather than shown nameless.

Verified against a live Postgres by internal/api/catalog/promo_gift_money_integration_test.go: TestB5Gift_CardShowsTheGiftItself (name, value, quantity, gallery-fallback preview and slug on the trigger's card — and the same product and value in the cart line the rule then produces), TestB5Gift_CardKeepsTextPlaqueWhenGiftIsOutOfStock (one unit in stock against a rule that gives two: gift gone, plaque and description still there, cart hands out nothing), TestB5Gift_CardHidesTheGiftOfAnUnpublishedProduct, TestB5Gift_CardCarriesNoGiftForOtherKinds, TestB5Gift_CardOfTheGiftShowsWhatEarnsIt (the gift's own card: gift empty, one trigger with its purchase price, gallery-fallback preview and slug — and nothing at all once that trigger is unpublished), TestB5Gift_CardOfTheGiftCapsTheTriggerList (15 triggers → 12 listed, triggers_total: 15), TestB5Gift_CardOfTheGiftNamesTheTriggerCategory (a category condition arrives as a name, not as products), TestB5Gift_CardOfTheSelfGiftStaysOnTheGiftSide.

4. Recipes

4.1 "Which products are on sale right now?"

There is no single "sale" endpoint. Ask two questions:

1. GET /promotions → rules with active: true and a live period. An empty array means this shop has no rules, see §5.
2. For a rule of kind: "product_discount", decode condition and read product_ids / category_ids. For prices as the buyer sees them, read the products: price.price is already discounted and price.old_price carries the pre-discount value, with price.promotion_name naming the rule.

Verify: pick one product id from the rule's condition, GET /products/{id}, and check price.old_price > price.price. If they are equal, the rule did not match that product — check the category ids, not the endpoint.

4.2 Create a 15% category sale

COND=$(printf '{"category_ids":[42]}' | base64)
EFF=$(printf '{"percent":15}' | base64)
curl -X POST "$API/promotions" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d "{\"item\":{
    \"name\":\"Summer −15%\",\"description\":\"On sofas until 31.08\",
    \"kind\":\"product_discount\",\"active\":true,
    \"condition\":\"$COND\",\"effect\":\"$EFF\"}}"

Verify: GET /products?filter.category_id=42 and check that price.old_price appeared on the items. Seeing 200 on the POST proves only that the rule was stored.

4.3 Create a promo code

# 1) a rule that waits for a code: −10% on orders from 5 000, at most 2 000 off
COND=$(printf '{"min_subtotal":5000}' | base64)
EFF=$(printf '{"percent":10,"max_discount":2000}' | base64)
curl -X POST "$API/promotions" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d "{\"item\":{
    \"name\":\"Promo −10%\",\"kind\":\"order_discount\",\"class\":\"key\",
    \"active\":true,\"condition\":\"$COND\",\"effect\":\"$EFF\"}}"
# → note result.id

# 2) the code itself
curl -X POST "$API/promo-keys" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"item":{
    "promotion_id":<RULE_ID>,"code":"SUMMER25","active":true,
    "usage_limit":100,"per_customer_limit":1}}'

Verify: as a buyer with a cart above the threshold, POST /cart/promo {"company_id":…,"code":"summer25"} (lower case on purpose) and check result.discount_total > 0 and result.promo_code == "SUMMER25". If promo_rejected came back instead, its code says exactly what is wrong.

4.4 Order with a code

Apply the code, then POST /cart/confirm with expected_total = the result.subtotal you last showed. Verify: read the created order — it carries discount_total and promotions[] as a snapshot; later edits to the rule never change a placed order.

4.5 Cap several promotions with one budget

A campaign is the only way to say "we issued a million worth of discounts". Note the order: create the campaign first, then point rules at it.

# 1) the budget itself
curl -X POST "$API/promo-campaigns" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"item":{
    "name":"Summer campaign","budget_kind":"spend","budget_limit":1000000,"active":true}}'
# → note result.id

# 2) point an existing rule at it (PUT is full-replace — send the whole item)
curl -X PUT "$API/promotions/<RULE_ID>" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"id":<RULE_ID>,"item":{
    "name":"Summer −15%","kind":"product_discount","active":true,
    "condition":"'"$COND"'","effect":"'"$EFF"'","campaign_id":<CAMPAIGN_ID>}}'

Verify: place a test order that the rule discounts, then GET /promo-campaigns and check that budget_used grew by the discount amount. If it stays at 0, the rule is not actually in the campaign — re-read the rule and check campaign_id.

Two behaviours that surprise people:

• budget_used also grows from ordinary promotions, not only from promo codes;
• when the budget is short, only a promo-code discount refuses the order (CAMPAIGN_BUDGET_SPENT). An ordinary promotion still applies to the order the buyer is placing — they already saw that price — so the budget can overshoot by at most one sale, and the rule stops on the next order.

4.6 Grant a coupon for a purchase

Two rules, and the order matters: first describe what the coupon gives, then the rule that grants it.

# 1) what the coupon gives: −15% off an order, unlocked by a key
COND=$(printf '{"min_subtotal":1000}' | base64); EFF=$(printf '{"percent":15}' | base64)
curl -X POST "$API/promotions" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d "{\"item\":{
    \"name\":\"Thanks for the purchase −15%\",\"kind\":\"order_discount\",
    \"class\":\"key\",\"active\":true,\"condition\":\"$COND\",\"effect\":\"$EFF\"}}"
# → GRANT_ID

# 2) who gets it: buyers whose completed order is 50 000 or more
COND2=$(printf '{"min_subtotal":50000}' | base64)
EFF2=$(printf "{\"grant_promotion_id\":$GRANT_ID,\"valid_days\":30}" | base64)
curl -X POST "$API/promotions" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d "{\"item\":{
    \"name\":\"Coupon for a purchase from 50 000\",\"kind\":\"issue_key\",
    \"active\":true,\"condition\":\"$COND2\",\"effect\":\"$EFF2\"}}"

Verify: place an order above the threshold, move it to status 3 (done), then as that buyer call GET /my-coupons?company_id=<ID> — the coupon must be there with the name of the granting rule. Nothing appears at checkout time: the coupon is granted on completion, not on ordering, so that "order → get coupon → cancel" does not work.

If the coupon does not appear: the threshold is measured on the amount actually payable (after discounts), not on the pre-discount total.

Where the coupon notification goes. On issuance the platform emails the buyer at their account address — not at the contact email typed into the order. A coupon is personal: it is bound to owner_user_id and only that account can redeem it, so sending it to an address a third party filled in at checkout would hand someone else's discount instrument to the wrong person. The letter carries the code, what it grants, the expiry date and a link to the buyer's coupons page. A key.issued webhook fires in parallel for the shop's own systems.

Both belong to this path. A coupon you hand out yourself (§4.10) sends neither letter nor webhook — you are already talking to that buyer, so tell them the code.

4.7 Protect the margin of a whole shop

Layers of benefit stack (combo → promotion → promo code), and the only built-in floor is a price of zero. The shop-wide cap is a separate setting:

curl -X PUT "$API/v1/orgs/<ID>" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"id":<ID>,"max_total_discount_percent":40}'

Verify: read the org back and check the field; then build a cart where the stacked discounts would exceed the cap and confirm in GET /cart/items that discount_total is exactly the cap's percent of subtotal + discount_total — the pre-discount total, computed rather than read (§3.9). 0 removes the cap.

Note the deliberate limit: the cap trims the ladder from the top (promo code, then order discount) and does not touch per-line discounts — trimming those would require re-allocating money across lines and would desynchronise the per-line snapshot stored in the order.

4.8 Build a "what is on sale" page for the whole shop

One call, and the ranking is already done. Ask for what you will show — the default is 24, and a page that renders 8 tiles should ask for 8.

curl -s "$API/promotions/landscape?limit=8" -H "Authorization: Bearer $TOKEN" | jq '{
  scanned: .result.scanned_products,
  truncated: .result.truncated,
  live_rules: [.result.promotions[].name],
  code_only:  [.result.code_promotions[].name],
  offers: [.result.top_offers[] | {kind, product_id, name, price, old_price, benefit_percent}]}'

Verify — three checks, all cheap, and each catches a different lie:

1. take the first offer with kind == "product" and read its card: GET /products/{product_id} must return exactly the same price.price and price.old_price. If they differ, the page and the card are quoting two prices to the same buyer — do not ship, report it.
2. check the arithmetic of one row by hand: benefit == old_price - price, and benefit_percent == floor(benefit * 100 / old_price) — DOWN, never up: 49.6% prints as "−49%", so the shop never claims more than it gives. This is what you will print in large type, so it is worth one subtraction.
3. read truncated. true (with scanned_products: 500) means the answer is "the best of the 500 newest products", not "the best in the shop" — either say so in the wording or do not promise "лучшие предложения магазина".

Do not put code_promotions[] into the same list as promotions[]. The honest wording for them is "−10% по промокоду": without the code the price on the card will not change, and a buyer who does not find the discount in the cart blames the shop, not the copy.

An empty top_offers[] with a non-empty promotions[] is a real, correct state — rules exist but hit nothing published (typical cause: category_ids of a category whose goods are still drafts). Check scanned_products > 0 before you blame the endpoint: 0 means the shop has no published products at all.

4.9 Write "в наборе вдвое дешевле" on a product card

curl -s "$API/products/$PID" -H "Authorization: Bearer $TOKEN" | jq '.result.in_combos[] | {
  set: .name, combo_price, components_total, benefit,
  item_price, item_regular_price, item_times_cheaper_x100}'

Then render from the fields as they are: item_price and item_regular_price give "в наборе 500 ₽ вместо 1 000 ₽", and item_times_cheaper_x100 tells you whether the stronger wording is allowed at all.

Verify with numbers you control, not with a status code. Put the product into a set with price_mode: "percent", price_value: 50, on a base price of 1 000:

• item_price must be exactly 500 (floor of base·(100−p)/100 — the same formula the cart uses, which is why you must not repeat it on the storefront);
• item_times_cheaper_x100 must be exactly 200, i.e. "вдвое";
• now start a product_discount of −20% on that component and read the card again: item_regular_price drops to 800 and the ratio falls to 160. That is correct and it is the point of the field — outside the set the buyer already pays 800, so "вдвое дешевле" would no longer be true.

If item_times_cheaper_x100 comes back 0, do not print a ratio: either the set gives this product nothing, or it is a free component (item_price == 0) that should read "В подарок".

4.10 Hand a coupon to one buyer

For a one-off — an apology for a late delivery, a thank-you to a regular — you do not need a rule that grants coupons to everybody who qualifies. Describe what the coupon gives (once, and reuse it afterwards), then mint a key onto one account. You need that buyer's account id, and their orders carry it as buyer_id (the seller's order list is POST /orders, not a GET). A guest order leaves buyer_id: 0 — there is no account to hang a coupon on, and issuing to 0 creates a shared code, not a coupon.

# 1) what the coupon gives — skip if you already have a class:"key" rule to reuse
COND=$(printf '{"min_subtotal":1000}' | base64); EFF=$(printf '{"percent":10}' | base64)
curl -X POST "$API/promotions" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d "{\"item\":{
    \"name\":\"Sorry for the delay −10%\",\"kind\":\"order_discount\",
    \"class\":\"key\",\"active\":true,
    \"condition\":\"$COND\",\"effect\":\"$EFF\"}}"
# → RULE_ID

# 2) the coupon itself, onto one account
curl -X POST "$API/promo-keys" -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"item":{
    "promotion_id":<RULE_ID>,"code":"SORRY-2026","active":true,
    "owner_user_id":<BUYER_USER_ID>,
    "expires_at":"2026-12-31T23:59:59Z"}}'

The limits are left out on purpose: a key created with an owner and without them is issued as one-off (usage_limit: 1, per_customer_limit: 1). Send explicit numbers only if you really mean "three visits". expires_at is optional too — without it the coupon lives as long as the rule it unlocks.

Verify — three checks, because each answers a different way of being wrong:

• read it back with GET /promo-keys?with_coupons=true and find your owner_user_id on it. Without with_coupons=true the list shows shared codes only, and a coupon that was created correctly looks like a call that failed;
• as that buyer, GET /my-coupons?company_id=<ID> — the coupon is there under the granting rule's name, which is what the buyer will read in the cart;
• as anyone else, POST /cart/promo {"company_id":…,"code":"SORRY-2026"} answers promo_rejected: "NOT_FOUND". A personal coupon is not a bearer instrument, and the reply does not even admit the code exists.

Two refusals worth knowing before you script this: an owner_user_id that belongs to no account is rejected (PROMO_KEY_OWNER_NOT_FOUND) instead of producing a code nobody can redeem, and the owner of an existing key cannot be edited (PROMO_KEY_OWNER_IMMUTABLE) — moving a coupon to another person is a delete plus a new issue, not a PUT.

5. Silently ignored

Cases where the platform answers 200 and does nothing. This section is mandatory and is written from the code, not from memory.

Loud failures (400, so you will notice): unknown keys inside condition/effect; max_discount on a per-line rule; a key attached to a non-key rule; changing a key's promotion_id or its owner_user_id (PROMO_KEY_OWNER_IMMUTABLE — including sending 0 for a coupon, which would quietly turn it into a code for everybody); an owner_user_id that belongs to no account (PROMO_KEY_OWNER_NOT_FOUND); a fixed-amount coupon without a threshold above its value; a bundle/gift set with both id lists empty; a kind × class pair outside the matrix in §3.1 (class: "key" on anything but order_discount, class other than item on a gift or an issue_key); limit above 100 on /promotions/landscape (a validated field — it is refused, not clamped).

6. Limits

Generated — every row below is a key of promotions.BuildPromoReference().Limits, whose value comes from the constant the validator (or the handler) enforces. A gate test compares the key set of this table with the reference, so a limit cannot be added to the code and forgotten here, or invented here and never enforced.

<!-- gate:limits -->

<!-- /gate -->

Not generated — these are SQL literals in the repository layer and a rate-limit bucket, so nothing checks them mechanically; read as of 2026-08-20 from pg/promo_keys.go, pg/promo_issue.go and the auth interceptor:

7. How this was verified

• 2026-08-20, live HTTP against an isolated instance (own port, own database, binary built from this branch): routes exist and are gated (/promo-keys and /cart/promo answer 401 anonymously, not 404); rule and key creation return the shapes documented above; duplicate code → 409; key on a non-key rule → 400; fixed-amount coupon without a threshold → 400; max_discount on a per-line rule → 400.
• 39 integration scenarios over a real Postgres (-run TestB5), including the redemption counter and its rollback on order cancellation, the per-customer limit, the price-changed guard, the campaign budget stopping a rule and being refunded on cancellation, coupon issuance on completion (and its idempotency), and foreign coupons staying invisible; 18 more for combo sets.
• The int64 → string wire detail was confirmed by reading real responses, not by reasoning about proto.
• An independent audit of the whole area on 2026-08-20 found four money defects that this document would otherwise have described incorrectly: editing a promotion from the cabinet silently removed a campaign cap; the budget was only charged for promo codes, so a cap over an ordinary promotion did nothing; the key.issued webhook could never be delivered; and coupon issuance was idempotent only against sequential repeats. All four are fixed and covered by tests — the statements above describe the fixed behaviour, not the intended one.
• Hand-issued coupons (§4.10, the `owner_user_id` statements of §3.2 and the refusals of §5) were written on 2026-08-20 together with the code that allows them, and each statement has its scenario in internal/api/catalog/promo_keys_integration_test.go, green over a real Postgres: TestB53_ManualCouponRedeemedByOwner follows one coupon from issuing to the money (seller sees it, buyer sees it, a stranger gets NOT_FOUND, the owner's order carries the discount, used becomes 1, the second attempt is EXHAUSTED); TestB53_ManualCouponUnknownOwnerRejected proves the dead coupon is not stored at all; TestB53_ManualCouponOwnerImmutableOnEdit proves both refusals of the owner field and that an honest edit still goes through; TestB53_PublicCodeKeepsNoLimits is the regression that shared promo codes did not silently become one-off.
• Enumerable content (kinds, classes, reject reasons, limits) is not written by hand here: it comes from promotions.BuildPromoReference(), and gate tests fail if this document and the server disagree in either direction.
• The gift statements of §3.1, §3.9 and §5 stopped being a claim on 2026-08-20 and became a check. TestB5Gift_* in internal/core/services/promotions/apply_gift_money_test.go asserts identities over the engine result rather than fixed numbers — the struck-through total is built from real lines only, the payable total is those lines minus the order and key steps, Σ applied equals the discount, the key base is the same with applies_to_discounted on and off, and the shop margin cap is measured without the gift; a gift worth more than the whole cart is used on purpose. internal/api/catalog/promo_gift_money_integration_test.go follows the gift past the engine: a 54-FZ receipt whose order-discount remainder must not be dropped onto the zero-priced gift line (it was, and the receipt then failed to build at all), and an order with no money refusing to produce a receipt instead of an empty one. The campaign row of §5 is the same file's third scenario, written to fail when the gap closes.
• §3.7, §3.8, §4.8, §4.9 and the landscape rows of §5: written on 2026-08-20 from the source (internal/api/catalog/get_promo_landscape.go, internal/adapters/repositories/pg/promo_landscape.go, and inCombosDesc / timesCheaperX100 in internal/api/catalog/combo_repack.go) and then run against a real Postgres the same day: TestB5Landscape* — 9 scenarios, all green; TestB49_InComboItemPrice — green (a component at −50% inside the set answers item_price 250, item_regular_price 500, item_times_cheaper_x100 200, and a component the set does not discount answers 0). Two of the nine were red when this section was first written; both defects were fixed the same day (commit ac88c77) and this document describes the fixed behaviour.

8. What own markup still needs (request to Track: agent-api)

Update 2026-08-20, measured, not assumed: own markup already gets promo prices. The products[] scope is built from GetProducts, whose repack runs the promotion engine, so p.price is the discounted price and p.old_price is the pre-discount one. Nothing new has to be transported for a "was/now" row.

What is still missing is one field that the API already returns and the scope simply does not map — and the cart-side set, which only matters once own markup gets its own cart. No second transport is being invented for either:

• per product: price.promotion_name — the rule's name, for a "why is it cheaper" badge (price.price / price.old_price are already in the scope);
• per product, optional: product_promotions[] {name, description, kind} — for a "why is it cheaper" block on a card;
• per cart: subtotal, discount_total, applied[] {name, amount}, promo_code, promo_rejected — enough for a custom cart summary and a code input with honest error text. subtotal_before is deliberately not on the list: the struck-through total is subtotal + discount_total (§3.9), so mapping the field would only give own markup a second, weaker way to reach the same number.

Nothing here is new data — all of it already leaves the API on the cart and product endpoints; it only needs to be declared in the scope white-list.