Seller API promotions

List, accept, and decline platform event shares and custom vendor deals that change what you can sell through the API.

TopicsCatalog

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 with seller:promotions:respond.
  • Subscribe to the promotion.* events, or poll the lists with updatedSince.
  • 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.

KindWhat it isIts idsourceType
Platform event shareA vendor takes part in a platform-wide sale (a seasonal event on a platform) and shares its discounts with youshare_id (shareId in paths)event
Custom dealA vendor proposes its own promotion to youid 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#

StepShare statusDeal response_statusEvent
The vendor sends the offerpendingpendingpromotion.offered
The vendor changes its products or discountspending (an acceptance is reset)—promotion.changed
You acceptacceptedapprovedpromotion.accepted
You declinedeclinedrejectedpromotion.declined
Nobody answers by respond_byexpiredexpiredpromotion.expired
The vendor withdraws itvendor_withdrawnunchanged; the deal stops applyingpromotion.withdrawn
An accepted promotion's window opensacceptedapprovedpromotion.started
An accepted promotion's window closesacceptedapprovedpromotion.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#

ScopeOperations
seller:promotions:readSummary, list/detail shares and deals, share discounts, calendar
seller:promotions:respondAccept / 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.

MethodPathPurpose
GET/promotions/sharesList 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}/acceptAccept
POST/promotions/shares/{shareId}/declineDecline
GET/promotions/shares/{shareId}/discountsSKU-level discount table (accepted shares only)

Suggested flow:

  1. GET /promotions/shares?status=pending, or react to promotion.offered
  2. GET /promotions/shares/{shareId} — review products, price_effect and respond_by
  3. POST .../accept or POST .../decline before respond_by
  4. After accept: GET .../discounts to 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:

MethodPathPurpose
GET/promotions/dealsList deals (filter by vendor / status)
GET/promotions/deals/{responseId}Detail with products (price_effect, product_id)
POST/promotions/deals/{responseId}/respondBody: { "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:

ParameterMeaning
statusComma-separated statuses
vendorOnly offers from this vendor (company id)
from, toOnly offers whose window overlaps [from, to] (ISO 8601, UTC)
updatedSinceOnly 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 with Idempotency-Replayed: true. Without a key, a repeat after the first call landed answers 400 BAD_REQUEST; on contract date 2026-12-01 and later it answers 200 with the promotion's status when it is the same answer, and 409 CONFLICT with details.currentStatus when 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-01 and later a call the offer's state forbids is 409 CONFLICT with details.reason: SHARE_EXPIRED, PROMOTION_STARTED, RESPONSE_DEADLINE_PASSED, PROMOTION_WITHDRAWN (answering), or NOT_ACCEPTED (the discount table of a share you have not accepted). Earlier dates answer 400 BAD_REQUEST. A deal offered to another company is 404 on 2026-12-01 and 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.

priceEffectWhat you payWhat to advertiseFields on the line
both (default)Discounted: unitPriceCents dropsThe same discountpromo and listPromo set from the same source, promoResolution: "applied"; unitPriceCents = advertisedUnitPriceCents
list_priceList price: unitPriceCents unchangeddiscountPercent off the list pricepromo: null, promoResolution: "none", listPromo set, advertisedUnitPriceCents = list price with the discount applied
settlement_priceDiscounted: unitPriceCents dropsNothing asked; your pricing decisionpromo 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:

SurfaceFields
POST /orders/preview lines, POST /orders/holdunitPriceCents (effective, echo it as expectedUnitPriceCents), initialUnitPriceCents (list), promo, promoResolution, listPromo, advertisedUnitPriceCents
GET /finance/api-sales, GET /finance/statements linessalePriceCents (billed), initialSalePriceCents, promo (sourceType, sourceId)
GET /activity entriespromo (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:

FieldMeaning
listPromoThe live promotion to show to buyers (priceEffect list_price or both), or null
advertisedPriceCentsbasePriceCents with listPromo applied: the price to show now
promoThe live promotion that lowers what an API-model order is billed (settlement_price or both), or null
promoResolutionapplied, 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}/window with {"action": "start"} or {"action": "end"} moves a deal the vendor sent so its window starts or ends now. An approved deal sends promotion.started or promotion.ended right 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/reset makes 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.

What links here

Published guides that link to this page.

Search docs

Search documentation…