Promotions allow you to offer discounts, credits, and special pricing to customers through coupon codes, automatic rules, or manual application.
Key concepts:
- Code - the coupon code a customer enters (e.g.,
SAVE20) - Effects - what the promotion does: percentage discount, fixed discount, free trial extension, or credit grant
- Conditions - eligibility rules: minimum spend, specific plans, customer segments, date ranges
- Budget - optional spending cap; the promotion deactivates when the budget is exhausted
- Stackable - whether this promotion can combine with other active promotions
- Simulation - preview the financial impact of a promotion before activating it
List a customer's promotion redemptions
Returns a customer's promotion redemptions, newest first. Cursor-paginated (default 50, max 200 per page).
path Parameters
idCustomer UUID
Customer UUID
query Parameters
statusFilter by redemption status (active|dormant|pending|expired|revoked)
Filter by redemption status (active|dormant|pending|expired|revoked)
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List a customer's promotion redemptions › Responses
OK
List promotions
Returns a paginated list of promotions. Supports the unified field.op=value filter grammar (see /docs/pagination).
query Parameters
archetypeFilter on archetype (enum). Operators: eq, in — dot grammar, e.g. archetype.in=value; a bare archetype=value means eq. A bare comma-separated value is in-sugar: archetype=a,b means archetype.in=a,b. Legal values: generic, coupon_discount, bundle_discount, volume_rebate, first_purchase_credit, free_trial, cross_sell_free, loyalty_ladder, growth_ladder.
codeFilter on code (string). Operators: eq, contains, in — dot grammar, e.g. code.contains=value; a bare code=value means eq. A bare comma-separated value is in-sugar: code=a,b means code.in=a,b.
created_atFilter on created_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. created_at.gt=value; a bare created_at=value means eq.
distributionFilter on distribution (enum). Operators: eq, in — dot grammar, e.g. distribution.in=value; a bare distribution=value means eq. A bare comma-separated value is in-sugar: distribution=a,b means distribution.in=a,b. Legal values: AUTO_APPLY, AUTO_ENROLL, COUPON, DIRECT.
nameFilter on name (string). Operators: eq, contains — dot grammar, e.g. name.contains=value; a bare name=value means eq.
stacking_groupFilter on stacking_group (string). Operators: eq, in — dot grammar, e.g. stacking_group.in=value; a bare stacking_group=value means eq. A bare comma-separated value is in-sugar: stacking_group=a,b means stacking_group.in=a,b.
stacking_modeFilter on stacking_mode (enum). Operators: eq, in — dot grammar, e.g. stacking_mode.in=value; a bare stacking_mode=value means eq. A bare comma-separated value is in-sugar: stacking_mode=a,b means stacking_mode.in=a,b. Legal values: stack, exclusive.
updated_atFilter on updated_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. updated_at.gt=value; a bare updated_at=value means eq.
valid_fromFilter on valid_from (date). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. valid_from.gt=value; a bare valid_from=value means eq.
valid_toFilter on valid_to (date). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. valid_to.gt=value; a bare valid_to=value means eq.
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
searchCase-insensitive substring match over name and code; relevance-ranked (exact > prefix > substring)
Case-insensitive substring match over name and code; relevance-ranked (exact > prefix > substring)
statusFilter by status (sugar for status.eq). Filterable fields (status, distribution, name, code, archetype, stacking_mode, stacking_group, valid_from, valid_to, created_at, updated_at) accept apifilter operator suffixes in the dot grammar, e.g. status.in=a,b
Filter by status (sugar for status.eq). Filterable fields (status, distribution, name, code, archetype, stacking_mode, stacking_group, valid_from, valid_to, created_at, updated_at) accept apifilter operator suffixes in the dot grammar, e.g. status.in=a,b
derived_statusPost-filter on the computed derived_status DTO field
Post-filter on the computed derived_status DTO field
countsComma-separated countable fields (status, archetype) to include per-value counts for
Comma-separated countable fields (status, archetype) to include per-value counts for
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List promotions › Responses
OK
Create a promotion
Creates a new promotion in draft status.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a promotion › Request Body
application_timingWhen a redeemed promotion first takes effect: NEXT_CYCLE, RETROACTIVE, or IMMEDIATE.
archetypeFrontend-only preset hint; not persisted as rule logic.
Live targeting set (who sees / auto-enrolls into the promotion); omit for all customers.
budget_behaviorWhat happens when a redemption would exceed max_budget: SKIP or PARTIAL.
budget_currencyISO 4217 currency the budget is denominated in; required when max_budget is set.
codeCoupon code; required when distribution is COUPON and must be omitted otherwise.
descriptionInternal description of the promotion (not shown to customers).
distributionHow a customer comes to hold the promotion: AUTO_APPLY, AUTO_ENROLL, COUPON, or DIRECT. Required.
effectsSingle-phase shorthand: the effects to apply. Mutually exclusive with phases.
Single-phase shorthand: the eligibility condition set. Mutually exclusive with phases.
evaluation_scopeWhere the engine evaluates the promotion: invoice (default), subscription, usage_event, or reserve.
max_budget^-?\d+(\.\d+)?$MAJOR units, denominated in budget_currency (required when max_budget is set).
max_redemptionsCap on total redemptions across all customers; omit for unlimited.
max_redemptions_per_customerCap on redemptions by any single customer; omit for unlimited.
nameOperator-facing promotion name.
Phased-ladder rule shape: ordered phases with per-phase conditions and effects. Mutually exclusive with eligibility/effects.
priorityOrdering priority on the invoice pass; higher applies first and wins within a stacking group.
public_descriptionCustomer-facing description of the promotion.
stacking_groupNamed mutual-exclusion group for stacking_mode=stack; promotions sharing a group never combine with each other.
stacking_modeHow the promotion combines with others on the invoice pass: stack (default) or exclusive (applies alone).
Localized overrides for customer-facing text, keyed by locale.
valid_fromFirst calendar day (UTC) the promotion is valid; required.
valid_toLast calendar day (UTC) the promotion is valid, inclusive; null = open-ended.
Create a promotion › Responses
Created
Redeem a promotion using a coupon token
Redeems a promotion for a customer using a customer-locked coupon token.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Redeem a promotion using a coupon token › Request Body
customer_idCustomer redeeming the token; must match the customer the token is locked to. Required.
subscription_idSubscription to scope the redemption to, when applicable.
tokenThe customer-locked coupon token to redeem; required.
Redeem a promotion using a coupon token › Responses
Created
Simulate promotion impact
Runs the invoice pipeline without persisting invoices or incrementing promotion budgets.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Simulate promotion impact › Request Body
billing_period_endLast day (UTC) of the billing period to simulate; must be after billing_period_start.
billing_period_startFirst day (UTC) of the billing period to simulate; required.
customer_idCustomer to simulate the invoice for; required.
promotion_idsPromotions to apply in the simulation; at least one is required.
subscription_idSubscription whose charges are simulated; required.
Simulate promotion impact › Responses
OK
Validate promotion eligibility
Checks which promotions a customer is eligible for.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Validate promotion eligibility › Request Body
coupon_codeCoupon code to include coupon-gated promotions in the eligibility check.
customer_idCustomer to check promotion eligibility for; required.
invoice_subtotalDecimal string, MAJOR units. Currency is the evaluated customer/subscription context's currency.
subscription_idSubscription context to evaluate against, when applicable.
Validate promotion eligibility › Responses
OK
Get a promotion
Returns a single promotion with derived read-time fields: a derived_status evaluated against the current instant plus remaining budget and remaining redemptions where caps are set.
path Parameters
idPromotion UUID
Promotion UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a promotion › Responses
OK
Delete a promotion
Soft-deletes a draft promotion.
path Parameters
idPromotion UUID
Promotion UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Delete a promotion › Responses
No Content
Update a promotion
Merge-patch update: only supplied fields change. Publishing is the explicit POST /promotions/{id}/publish; effective_at/save_as_draft here stage scheduled changes (ADR-0006). expected_version is the optimistic-concurrency token: when supplied and stale, the update returns 409.
path Parameters
idPromotion UUID
Promotion UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update a promotion › Request Body
application_timingNew application timing (NEXT_CYCLE, RETROACTIVE, IMMEDIATE); omit to leave unchanged.
archetypeFrontend-only preset hint; not persisted as rule logic.
New targeting set; a full replacement of the live audience when set (no version bump).
budget_behaviorNew over-budget behavior (SKIP or PARTIAL); omit to leave unchanged.
budget_currencyISO 4217 currency the budget is denominated in; required (on the merged state) when max_budget is set.
codeNew coupon code; only valid when distribution is COUPON (biconditional enforced on the merged state).
descriptionNew internal description; omit to leave unchanged.
distributionNew distribution axis (AUTO_APPLY, AUTO_ENROLL, COUPON, DIRECT); omit to leave unchanged.
effective_atADR-0006 control: schedule this edit to publish as a new version at the given time. Mutually exclusive with save_as_draft.
effectsSingle-phase shorthand effects; full replacement of the rule when set. Mutually exclusive with phases.
Single-phase shorthand eligibility set; full replacement of the rule when set. Mutually exclusive with phases.
evaluation_scopeNew evaluation scope (invoice, subscription, usage_event, reserve); omit to leave unchanged.
expected_versionOptimistic-concurrency token: send the version you last read and a stale value answers 409 CONFLICT. Omitted: the update applies unconditionally (last write wins).
max_budget^-?\d+(\.\d+)?$MAJOR units, denominated in budget_currency.
max_redemptionsNew total-redemptions cap; omit to leave unchanged.
max_redemptions_per_customerNew per-customer redemptions cap; omit to leave unchanged.
nameNew operator-facing name; omit to leave unchanged.
Phased-ladder rule; full replacement when set. Mutually exclusive with eligibility/effects.
priorityNew invoice-pass ordering priority; omit to leave unchanged.
public_descriptionNew customer-facing description; omit to leave unchanged.
save_as_draftADR-0006 control: save the edit as a draft version instead of publishing. Mutually exclusive with effective_at.
stacking_groupNew mutual-exclusion group; an empty string clears the group, omission leaves it unchanged.
stacking_modeNew stacking mode (stack or exclusive); omit to leave unchanged.
Localized overrides for customer-facing text, keyed by locale.
valid_fromNew first valid calendar day (UTC); omit to leave unchanged.
valid_toNew last valid calendar day (UTC), inclusive; omit to leave unchanged.
Update a promotion › Responses
OK
Archive a promotion (terminal)
Terminally retires an active promotion: no new redemptions, and there is no way back to active - create or copy a new promotion instead. Already-applied benefits on issued invoices are untouched; only future invoices stop receiving them.
path Parameters
idPromotion UUID
Promotion UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Archive a promotion (terminal) › Responses
OK
Preview a promotion's audience
Returns the customers matching an audience definition plus the total match count and each customer's enrollment status. Omit the audience body to preview the stored audience; pass one to preview unsaved editor state.
path Parameters
idPromotion UUID
Promotion UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Preview a promotion's audience › Responses
OK
Copy a promotion as a new draft
Clones an existing promotion (any status) into a new draft promotion. Conditions, effects, and phases are duplicated.
path Parameters
idSource promotion UUID
Source promotion UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Copy a promotion as a new draft › Request Body
codeCoupon code for the new draft; only valid when the promotion's distribution is COUPON.
nameName for the new draft; defaults to the source promotion's name suffixed as a copy when omitted.
valid_fromFirst calendar day (UTC) the new draft is valid; required.
valid_toLast calendar day (UTC) the new draft is valid, inclusive; null = open-ended.
Copy a promotion as a new draft › Responses
Created
Bulk-enroll customers into a promotion
Synchronously enrolls explicit customers and/or every current audience match (sweep semantics). Each enrollment goes through the regular redeem path, so caps, conditions, and budget all apply. Returns a per-customer outcome list.
path Parameters
idPromotion UUID
Promotion UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Bulk-enroll customers into a promotion › Request Body
customer_idsfrom_audienceBulk-enroll customers into a promotion › Responses
OK
Preview promotion eligibility
Evaluates a single promotion's conditions for a customer and returns per-condition pass/fail details.
path Parameters
idPromotion UUID
Promotion UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Preview promotion eligibility › Request Body
customer_idCustomer to evaluate the promotion's conditions for; required.
subscription_idSubscription context to evaluate against, when applicable.
Preview promotion eligibility › Responses
OK
Publish a promotion
Takes a draft (or scheduled) promotion live: flips its status to active so it starts matching and redeeming. This is the explicit first-publish trigger; scheduled or superseding changes go through PATCH /promotions/{id} with effective_at.
path Parameters
idPromotion UUID
Promotion UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Publish a promotion › Responses
OK
Redeem a promotion
Redeems a promotion for a customer, creating a redemption record.
path Parameters
idPromotion UUID
Promotion UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Redeem a promotion › Request Body
coupon_codeCoupon code, required when the promotion's distribution is COUPON.
customer_idCustomer to redeem the promotion for; required.
subscription_idSubscription to scope the redemption to, when applicable.
Redeem a promotion › Responses
Created
List a promotion's redemptions
Returns the customers who have redeemed (or currently hold) the promotion, newest first. Cursor-paginated (default 50, max 200 per page).
path Parameters
idPromotion UUID
Promotion UUID
query Parameters
statusFilter by redemption status (active|dormant|pending|expired|revoked)
Filter by redemption status (active|dormant|pending|expired|revoked)
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List a promotion's redemptions › Responses
OK
Preview a benefit clawback
Prices what revoking with revert_benefits would reverse — per-currency totals from the applied-promotions invoice ledger plus wallet credits granted by this redemption. Moves no money.
path Parameters
idPromotion UUID
Promotion UUID
redemptionIdRedemption UUID
Redemption UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Preview a benefit clawback › Responses
OK
Opt a customer out of a promotion
Neutral departure: benefits stop forward, past benefits keep, auto-enrollment never re-adds, explicit re-join stays possible.
path Parameters
idPromotion UUID
Promotion UUID
redemptionIdRedemption UUID
Redemption UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Opt a customer out of a promotion › Responses
OK
Revoke a redemption (blacklist, optionally clawing back benefits)
Operator action: terminally revokes a redemption and BLACKLISTS the customer (redeem is rejected until unblock). Optionally claws back granted benefits with revert_benefits. This is distinct from opt-out, which is a neutral, rejoinable stop that never claws back - use opt-out for a customer-initiated departure, revoke to remove and bar.
path Parameters
idPromotion UUID
Promotion UUID
redemptionIdRedemption UUID
Redemption UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Revoke a redemption (blacklist, optionally clawing back benefits) › Request Body
revert_benefitsWhen true, additionally claws back everything the redemption delivered (invoice-ledger benefits and wallet credit grants) via a signed wallet adjustment. Destructive and not restored by a later re-join.
Revoke a redemption (blacklist, optionally clawing back benefits) › Responses
OK
Unblock a revoked (blacklisted) redemption
Lifts the blacklist: revoked → opted_out. The customer may be enrolled again; nothing previously consumed or clawed back is restored.
path Parameters
idPromotion UUID
Promotion UUID
redemptionIdRedemption UUID
Redemption UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Unblock a revoked (blacklisted) redemption › Responses
OK
List coupon tokens
Returns paginated coupon tokens for a promotion.
path Parameters
idPromotion UUID
Promotion UUID
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List coupon tokens › Responses
OK
Generate coupon tokens
Generates customer-locked single-use coupon tokens for a promotion.
path Parameters
idPromotion UUID
Promotion UUID
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Generate coupon tokens › Request Body
countNumber of coupon tokens to generate (1-10000); larger campaigns repeat the call.
emailsOptional customer emails to lock the tokens to, one per token; when provided its length must equal count.
Generate coupon tokens › Responses
Created
List promotion versions (with lifecycle filter)
Returns version rows for the entity, keyset-paginated (default 100, max 200 per page). The status filter accepts draft, scheduled, published, archived; the default excludes draft (ADR-0007). Supports ?include=usage_count and ?archived_reason=.
path Parameters
idEntity UUID
Entity UUID
query Parameters
statusLifecycle status filter (repeatable / comma-separated): draft, scheduled, published, archived. Default excludes draft.
Lifecycle status filter (repeatable / comma-separated): draft, scheduled, published, archived. Default excludes draft.
archived_reasonNarrow archived rows by reason (repeatable / comma-separated): canceled, discarded, errored, superseded
Narrow archived rows by reason (repeatable / comma-separated): canceled, discarded, errored, superseded
includeComma-separated includes. Currently supports usage_count.
Comma-separated includes. Currently supports usage_count.
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List promotion versions (with lifecycle filter) › Responses
OK
Get a promotion version snapshot
Returns the static snapshot row for one promotion version (naming, code, distribution, stacking, budget, validity, and release fields). The version's linked phases, conditions, and effects are fetched separately when drilling in.
path Parameters
idEntity UUID
Entity UUID
versionVersion number
Version number
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a promotion version snapshot › Responses
OK
List promotion version referrers
Offset-paginated drill-down of the referrers of one type for one version of the entity.
path Parameters
idEntity UUID
Entity UUID
versionVersion number (positive integer)
Version number (positive integer)
query Parameters
typeReferrer type to list (required)
Referrer type to list (required)
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
offsetRow offset (default 0)
Row offset (default 0)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List promotion version referrers › Responses
OK
Get promotion version usage summary
Referrer counts for one version of the entity, grouped by referrer type. Powers the version-switcher hover card.
path Parameters
idEntity UUID
Entity UUID
versionVersion number (positive integer)
Version number (positive integer)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get promotion version usage summary › Responses
OK