Overview
What a promotion is, where it comes from and how to join one.
A promotion is a discount with a deadline on a Connection. You create your own and accept the campaign invitations the marketplace sends. Each listing takes part through an entry, with its own promotional price.
Where this fits in the journey: Grow and track.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /v1/promotions | List promotions |
POST | /v1/promotions | Create promotion |
GET | /v1/promotions/{promotionId} | Get promotion |
PATCH | /v1/promotions/{promotionId} | Update promotion |
DELETE | /v1/promotions/{promotionId} | Cancel promotion |
GET | /v1/promotions/{promotionId}/listing-entries | List entries |
PUT | /v1/promotions/{promotionId}/listing-entries | Replace entries |
GET | /v1/listings/{listingId}/promotions | Listing promotions |
GET | /v1/listings/{listingId}/promotion-eligibilities | Listing eligibilities |
POST | /v1/listings/{listingId}/promotions | Create promotion for a listing |
All of them need Authorization: Bearer mk_your_api_key. See Authentication.
Origin and type
origin: seller: created by you through the API.origin: marketplace: a campaign invitation. You only join; you cannot edit or cancel it.
type is discount, campaign, coupon, bundle, flash_sale or volume. A campaign starts only at the marketplace. What each Connection can create comes from its capabilities.
Period and subsidy
A promotion has startsAt, endsAt and, on an invitation, joinDeadlineAt: the deadline to join. sellerShareBps is the share of the discount the seller pays, in bps (5000 is 50%). null means the marketplace does not say.
States
status | Meaning |
|---|---|
pending | created here, the marketplace has not confirmed yet |
scheduled | confirmed, starts in the future |
active / paused | running / paused |
ended / cancelled | finished / cancelled |
rejected | the marketplace refused it; see statusReasons |
unknown | a state we do not know |
Entries
Each entry links a listing to the promotion, with promotionalPriceInCents or discountBps, stockLimit and purchaseLimit. Its status is candidate (invited), pending, active, paused, rejected, removed, ended or unknown.
Before joining, check eligibility: it shows the accepted price range (priceRange).
Effects
Writes return 202 with a job. Reads come from our database, kept fresh by sync. You receive the promotion.created, promotion.updated and promotion.entry_updated webhooks. To renew your own promotion before it ends, see Promotion renewals.