Read and answer the promotions vendors offer your company, follow them from offer to end, and show their prices. A promotion adjusts the price of shared SKUs for a window; it does not replace the four sellability gates.
Who needs this#
Integrators building a promotions inbox, auto-accept rules, or discount sync into a storefront.
TL;DR#
- Read with
seller:promotions:read; accept / decline / respond withseller:promotions:respond. - Subscribe to the
promotion.*events, or poll the lists withupdatedSince. - Answer an offer before its
respond_by. One answer per offer: it cannot be changed afterwards. - Catalogue prices carry the live promotion (
listPromo,advertisedPriceCents,promo) and the upcoming ones (promotions), so a store can stage a sale before it starts. - Promotions never make an unshared or unallocated SKU sellable on their own.
Concepts#
Two kinds of offer reach your company. Both are called a promotion in this guide.
| Kind | What it is | Its id | sourceType |
|---|---|---|---|
| Platform event share | A vendor takes part in a platform-wide sale (a seasonal event on a platform) and shares its discounts with you | share_id (shareId in paths) | event |
| Custom deal | A vendor proposes its own promotion to you | id of your answer slot (responseId in paths) | custom |
The calendar, the catalogue promotion fields, order lines and finance rows name a promotion by
sourceType and sourceId; sourceId is the share id or the deal response id above. A "share"
here is always a share of a platform event, not a product share (the access a vendor gives
you to a product): see the Glossary.
Lifecycle#
| Step | Share status | Deal response_status | Event |
|---|---|---|---|
| The vendor sends the offer | pending | pending | promotion.offered |
| The vendor changes its products or discounts | pending (an acceptance is reset) | — | promotion.changed |
| You accept | accepted | approved | promotion.accepted |
| You decline | declined | rejected | promotion.declined |
Nobody answers by respond_by | expired | expired | promotion.expired |
| The vendor withdraws it | vendor_withdrawn | unchanged; the deal stops applying | promotion.withdrawn |
| An accepted promotion's window opens | accepted | approved | promotion.started |
| An accepted promotion's window closes | accepted | approved | promotion.ended |
A share the vendor has prepared but not sent yet is never listed, counted or readable.
Answering. respond_by on every share and deal is the last instant an answer is taken: the
answer deadline or the start of the window, whichever is earlier. After it the offer becomes
expired. An offer takes one answer. There is no opt-out after accepting: a promotion you
accepted ends when its window closes or when the vendor withdraws it. If the vendor
changes the products of a share you accepted, your acceptance is reset to pending and you answer
again (promotion.changed with answerAgain: true).
Windows. startDate and endDate (on shares event_starts_at and event_ends_at) are UTC
instants and both are inclusive: the promotion applies from the first instant to the last.
Scopes#
| Scope | Operations |
|---|---|
seller:promotions:read | Summary, list/detail shares and deals, share discounts, calendar |
seller:promotions:respond | Accept / decline share; respond to deal |
Summary#
GET /api/seller/v1/promotions/summary
Returns counts of platform event shares and custom deals by status: pending, accepted /
approved, declined / rejected, expired and, for shares, vendor_withdrawn. Use it for
dashboards and “needs attention” badges.
Platform event shares#
vendors share platform-event promotions with your company.
| Method | Path | Purpose |
|---|---|---|
GET | /promotions/shares | List shares (filter by status: pending, accepted, declined, expired, vendor_withdrawn) |
GET | /promotions/shares/{shareId} | Detail with products (SKU, discount, price_effect, …) |
POST | /promotions/shares/{shareId}/accept | Accept |
POST | /promotions/shares/{shareId}/decline | Decline |
GET | /promotions/shares/{shareId}/discounts | SKU-level discount table (accepted shares only) |
Suggested flow:
GET /promotions/shares?status=pending, or react topromotion.offeredGET /promotions/shares/{shareId}— review products,price_effectandrespond_byPOST .../acceptorPOST .../declinebeforerespond_by- After accept:
GET .../discountsto stage storefront pricing
The discount table and the window. meta.window carries the window and meta.active says
whether it is open now. Apply the discounts only while meta.active is true. On contract date
2026-12-01 and later the rows come back before and after the window too, with
meta.active: false, so you can stage a sale as soon as you accept. On earlier dates data is
empty outside the window.
Custom deals#
vendors' own deals (not platform events) use a parallel surface:
| Method | Path | Purpose |
|---|---|---|
GET | /promotions/deals | List deals (filter by vendor / status) |
GET | /promotions/deals/{responseId} | Detail with products (price_effect, product_id) |
POST | /promotions/deals/{responseId}/respond | Body: { "decision": "approved" | "rejected", "note"?: "…" } |
response_status is pending, approved, rejected or expired.
Lists, filters and sync#
Both lists, shares and deals, page like every list (Lists and pagination) and take the same filters:
| Parameter | Meaning |
|---|---|
status | Comma-separated statuses |
vendor | Only offers from this vendor (company id) |
from, to | Only offers whose window overlaps [from, to] (ISO 8601, UTC) |
updatedSince | Only offers that changed at or after this instant (updated_at) |
sort | -offeredAt (default, newest offer first), offeredAt, -updatedAt, updatedAt |
To keep a mirror in step, store the largest updated_at you have seen and ask for
updatedSince with it, sort=updatedAt. Keep the same sort while you follow nextCursor.
The discount table is not paged: it returns every row.
Events#
Every change of an offer is in your event log (GET /events, resourceType=promotion,
resourceId = the sourceId) and is delivered to the webhook endpoints that subscribe to it:
promotion.offered, promotion.changed, promotion.accepted, promotion.declined,
promotion.withdrawn, promotion.expired, promotion.started and promotion.ended. An answer
given in the console sends the same event as one given over the API. promotion.started and
promotion.ended are sent within about 15 minutes of the window's edge. Payloads are listed in
the Event reference.
Integration notes#
- Treat accept / decline / respond as one logical decision per share or deal. To retry
safely, send an
Idempotency-Key(the same one on every retry of that decision): a retry replays the first answer withIdempotency-Replayed: true. Without a key, a repeat after the first call landed answers400 BAD_REQUEST; on contract date2026-12-01and later it answers200with the promotion'sstatuswhen it is the same answer, and409 CONFLICTwithdetails.currentStatuswhen it is a different one. A promotion keeps its first answer; two different answers sent at once never both land. - Too late, withdrawn, not accepted. On contract date
2026-12-01and later a call the offer's state forbids is409 CONFLICTwithdetails.reason:SHARE_EXPIRED,PROMOTION_STARTED,RESPONSE_DEADLINE_PASSED,PROMOTION_WITHDRAWN(answering), orNOT_ACCEPTED(the discount table of a share you have not accepted). Earlier dates answer400 BAD_REQUEST. A deal offered to another company is404on2026-12-01and later. - Discount tables are authoritative for the accepted share — do not invent percentages from the list payload alone.
- Catalog sync and checkout still require BMA, share (catalog + orders), allocation, and territory pricing. A promotion discount cannot override a hard territory or sellability refusal.
Promo in the price#
A promotion's priceEffect says which of two prices it touches: what you pay Avrix per unit
(the settlement price) and what the vendor asks you to advertise to the buyer (the list price).
POST /orders/preview and POST /orders/hold report both on every quoted line, so the checkout
call is the only call a store needs to render a sale.
Every promotion is both by default. The vendor funds the discount, so once you accept a
share or approve a deal, the promotion lowers unitPriceCents on every API-model line it covers,
and promo and listPromo name the same source. This applies to preview, hold, reservation and
POST /orders alike, and to promotions that were already live on 2026-09-25. list_price and
settlement_price remain supported values, but no console flow sets them today.
priceEffect | What you pay | What to advertise | Fields on the line |
|---|---|---|---|
both (default) | Discounted: unitPriceCents drops | The same discount | promo and listPromo set from the same source, promoResolution: "applied"; unitPriceCents = advertisedUnitPriceCents |
list_price | List price: unitPriceCents unchanged | discountPercent off the list price | promo: null, promoResolution: "none", listPromo set, advertisedUnitPriceCents = list price with the discount applied |
settlement_price | Discounted: unitPriceCents drops | Nothing asked; your pricing decision | promo set, promoResolution: "applied", listPromo: null, advertisedUnitPriceCents = initialUnitPriceCents |
Promotions never change an agreed per-key price. On Wholesale, Traditional Revenue Share and
Buy-In Wholesale (pre-order) lines, unitPriceCents is the price in your agreement and promo
is always null, whatever the promotion's priceEffect.
Settlement-affecting promotions (settlement_price or both) are applied by Avrix, not by your
store. Every quoted or billed price tells you when that happened:
| Surface | Fields |
|---|---|
| POST /orders/preview lines, POST /orders/hold | unitPriceCents (effective, echo it as expectedUnitPriceCents), initialUnitPriceCents (list), promo, promoResolution, listPromo, advertisedUnitPriceCents |
| GET /finance/api-sales, GET /finance/statements lines | salePriceCents (billed), initialSalePriceCents, promo (sourceType, sourceId) |
| GET /activity entries | promo (sourceType, sourceId); filter with promoId |
The promotion travels with a bound price. A price-commitment token, a checkout hold or a hot-drop
reservation carries the promotion it was quoted under, so a sale committed after the promotion
ended still records it. Refund, chargeback and reinstatement rows carry the original sale's
promo (and promoId on GET /activity matches them), while their initialSalePriceCents
is null. A sale recorded in a second currency before 2026-10-09, when that path still existed,
also has initialSalePriceCents null: its pre-promo price exists only in the catalog currency.
promo.sourceId and listPromo.sourceId are the shareId (sourceType: "event") or
responseId (sourceType: "custom") from this page, so a statement line can be attributed to the
campaign that discounted it. Render was/now from the integers (initialUnitPriceCents vs
advertisedUnitPriceCents on the product page, initialUnitPriceCents vs unitPriceCents for
your own margin) and never recompute a price from discountPercent. A list_price promotion
never changes the cents you pay and is reported as listPromo, never as promo.
advertisedUnitPriceCents is only filled under the API business model, where the line is priced
at the territory catalog list price for the countryCode you previewed. On wholesale and
revenue-share lines unitPriceCents is your negotiated cost, so the field is null; apply
listPromo.discountPercent to the country's list price from GET /products/{id}/pricing there.
promoResolution: "unavailable" means promotions could not be read at quote time — the price is
the list price, listPromo is null, and a promo may still exist, so re-preview before showing a
sale badge. When two promotions overlap on one SKU, each axis picks its own highest discount: an
80% list_price event and a 20% settlement_price deal give listPromo at 80% and promo at
20% side by side.
Promotions on catalogue prices#
GET /products/{productId} and GET /products/{productId}/pricing list each SKU's price per
country in skus[].prices[]. basePriceCents stays the undiscounted list price; beside it:
| Field | Meaning |
|---|---|
listPromo | The live promotion to show to buyers (priceEffect list_price or both), or null |
advertisedPriceCents | basePriceCents with listPromo applied: the price to show now |
promo | The live promotion that lowers what an API-model order is billed (settlement_price or both), or null |
promoResolution | applied, none, or unavailable when promotions could not be read |
Each SKU also carries promotions: the accepted promotions on it whose window is live or
upcoming, with discountPercent, priceEffect, startDate, endDate and window. The billed
price of an order depends on its allocation and the buyer's country, so POST /orders/preview
remains the price you charge against.
Scheduled discount calendar#
GET /api/seller/v1/promotions/calendar (seller:promotions:read) lists the windows of shares
you have accepted and deals you have approved, per SKU: sourceType, sourceId, skuId,
productId, name, vendorCompanyId, discountPercent, priceEffect, startDate, endDate,
window (live | upcoming | ended). It returns live and upcoming windows by default. Narrow
it with from and to (window overlap), skuId, productId, sourceId (comma-separated, at
most 50 each), vendor, and window (ended reads windows that closed since from, or in the
last 90 days).
Use it to plan sale pages before a promotion begins, and promotion.started and
promotion.ended to learn when one did. sku.pricing_updated is about the list price itself and
is not sent when a promotion starts or ends. The calendar carries percentages only; the price for
a country comes from the catalogue promotion fields above or from POST /orders/preview at sale
time (advertisedUnitPriceCents next to listPromo). The base_price_cents on share and deal
detail is the SKU's own-region display price in currency_code, shown to the vendor when
the promotion was authored — it is not the list price of the country you sell in, so never derive
a shelf price from it.
Read the calendar for December, live and upcoming windows:
curl -s -X GET "https://api.avrix.io/api/seller/v1/promotions/calendar?window=live,upcoming&from=2026-12-01T00:00:00.000Z&to=2026-12-31T23:59:59.000Z" \
-H "Authorization: Bearer $AVRIX_API_KEY"The SKU-level discounts of one accepted share (GET /promotions/shares/{shareId}/discounts,
paginated with cursor):
curl -s -X GET "https://api.avrix.io/api/seller/v1/promotions/shares/3f6c1a52-8d4e-4b7a-9c21-5e0f7d9a1b34/discounts?limit=100" \
-H "Authorization: Bearer $AVRIX_API_KEY"Rehearse in sandbox#
Every sandbox environment carries promotions on SANDBOX-PROMO-001: a live deal and an upcoming
deal you have approved, a deal waiting for your answer, and an event share waiting for your answer.
So GET /promotions/summary, the share and deal lists, GET /promotions/calendar and the answer
calls all have data to work on.
- Answer an offer. Accept or decline the share, and approve or reject the pending deal, as you
would in production; the matching
promotion.*events reach your sandbox endpoints. - Start or end a deal now. In your store's isolated sandbox environment,
POST /sandbox/promotions/deals/{responseId}/windowwith{"action": "start"}or{"action": "end"}moves a deal the vendor sent so its window starts or ends now. An approved deal sendspromotion.startedorpromotion.endedright away instead of at the next window check. Only the dates move; percentages and products stay as the vendor set them. - Start over.
POST /sandbox/resetmakes the share pending again and re-creates any deal that is missing.
The window control and the reset answer 422 SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED on the shared
sandbox, because its promotions are seen by every store on it. See
Sandbox.
Recipe pointer#
The compact call card lives in Integration recipes under promotions.
Code samples#
List the shares waiting for your answer. Each row's id is the shareId of the calls below.
curl -s -X GET "https://api.avrix.io/api/seller/v1/promotions/shares?status=pending&limit=50" \
-H "Authorization: Bearer $AVRIX_API_KEY"Accept a share. Send an Idempotency-Key, so a retry after a timeout cannot accept twice;
sellerNotes is optional. Decline is the same call on /decline.
curl -s -X POST "https://api.avrix.io/api/seller/v1/promotions/shares/3f6c1a52-8d4e-4b7a-9c21-5e0f7d9a1b34/accept" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "Idempotency-Key: share-accept-3f6c1a52" \
-H "Content-Type: application/json" \
-d '{
"sellerNotes": "Live on the store from the start date of the share."
}'Answer a custom deal from GET /promotions/deals?status=pending: decision is approved or
rejected, and note is optional.
curl -s -X POST "https://api.avrix.io/api/seller/v1/promotions/deals/7b2e9d40-1c5a-4f8e-b3d6-0a9c8e7f6d51/respond" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
-H "Idempotency-Key: deal-respond-7b2e9d40" \
-H "Content-Type: application/json" \
-d '{
"decision": "approved",
"note": "Approved for the December window."
}'The ids in these samples are placeholders. Take yours from the list calls.