Read and respond to vendor platform event shares and custom deals over the Seller API. Promotions adjust commercial terms for shared SKUs; they do 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. - Start with
GET /promotions/summary, then list shares and deals. - Accept a share before reading its SKU discount table.
- Promotions never make an unshared or unallocated SKU sellable on their own.
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). 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) |
GET | /promotions/shares/{shareId} | Detail with products (SKU, discount, …) |
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=pendingGET /promotions/shares/{shareId}— review products and termsPOST .../acceptorPOST .../decline- After accept:
GET .../discountsto sync storefront pricing
Custom deals#
Vendor-specific 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 |
POST | /promotions/deals/{responseId}/respond | Body: { "decision": "approved" | "rejected", "note"?: "…" } |
Statuses typically include pending, approved, rejected, and expired.
Integration notes#
- Treat accept / decline / respond as one logical decision per share or deal. Retry safely if your client is unsure of the outcome; confirm current status with a GET before re-posting a conflicting decision.
- 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#
Settlement-affecting promotions (priceEffect of 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 |
| GET /finance/api-sales, GET /finance/statements lines | salePriceCents (billed), initialSalePriceCents, promo (sourceType, sourceId) |
promo.sourceId is 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 two integers; list_price promos never change the cents and are not reported as
applied. promoResolution: "unavailable" means promotions could not be read at quote time — the
price is the list price and a promo may still exist, so re-preview before showing a sale badge.
Scheduled discount calendar#
GET /api/seller/v1/promotions/calendar (seller:promotions:read) lists live and upcoming
windows for shares you have accepted and deals you have approved — sourceType, sourceId,
skuId, discountPercent, priceEffect, startDate, endDate, window (live | upcoming).
Use it to plan sale pages before a promotion begins, and sku.pricing_updated (effectiveAt) to
learn when a price actually changed. The calendar carries percentages only; the effective price
for a country comes from POST /orders/preview at sale time.
Recipe pointer#
The compact call card lives in Integration recipes under promotions.