Overview
How renewal recreates a promotion before it ends.
A promotion has a deadline, and forgetting to redo it drops the promotional price. Renewal is our own rule: before the end, it creates a copy of the promotion. No marketplace renews on its own.
Where this fits in the journey: Grow and track.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /v1/promotion-renewals | List renewals |
POST | /v1/promotion-renewals | Create renewal |
PATCH | /v1/promotion-renewals/{renewalId} | Update renewal |
DELETE | /v1/promotion-renewals/{renewalId} | Delete renewal |
All of them need Authorization: Bearer mk_your_api_key. See Authentication.
How it works
The rule has duration and renewBefore, both in days (duration 1 to 180, renewBefore 1 to 30). Renewal runs at endsAt - renewBefore, the nextRunAt.
When it runs, a promotion.renew job creates the next promotion with the same terms and the active entries. It starts when the previous one ends and lasts duration. The rule then follows the new promotion (currentPromotionId).
Rules
- Only your own promotion (
origin: seller), withendsAt, of typediscount,coupon,bundleorvolume. Otherwise:409(promotion_not_renewable). - One rule per promotion chain. Otherwise:
409(renewal_exists). - If the marketplace refuses, the error goes to
lastError, the rule stays on and tries again at the next sweep. - Inactive Connection: the rule stays paused.
Webhooks
promotion.renewed arrives on every renewal. The new promotion also fires promotion.created. See Promotions.