Skip to main content
POST
Scope required: rewards.issue
This endpoint creates a new partner-initiated campaign for a merchant. A campaign defines the time window, terms, and reward variants for issuing rewards to users. Each campaign must have between 1 and 4 variants. Treatment variants specify a reward_template_id that defines the reward to be issued. Control variants (named “Control”) do not require a reward_template_id. Use the List Reward Templates endpoint to discover available reward templates for a merchant.

​
Choosing a redemption window

A campaign can express its redemption window in two independent ways:
  • Fixed window — redeemable_from / redeemable_to. The same calendar dates apply to every guest, whenever their reward was issued.
  • Relative window — retire_after_days. Each guest gets that many days from the moment their own reward was issued.
For evergreen, always-on flows where guests enter continuously — birthday, abandoned cart, post-purchase, service recovery — set retire_after_days and omit end_at and redeemable_to. A campaign with no end date stays redeemable indefinitely, so every guest gets the same full window regardless of when they enter. Adding a fixed end date to that shape truncates the window for late entrants. A campaign with redeemable_to of 2026-12-31 and retire_after_days of 14 gives a guest issued a reward on 2026-12-30 a single day to redeem, not fourteen. The request still returns 201 and nothing surfaces the shortened window, so choose the shape deliberately rather than setting both out of habit.
A campaign with no end date sends no “expiring soon” notification — that reminder is driven by the campaign end date, not by the per-guest relative window. Guests on an evergreen campaign are not warned before their reward expires.

​
Parameters

​
string
required
Merchant ID
​
string
required
Campaign name
​
string
Campaign objective
​
string
Terms and conditions
​
string
required
Campaign start date (ISO8601)
​
string
Campaign end date (ISO8601). Omit for an evergreen campaign with no end date. Required when redeemable_to is sent — sending redeemable_to on its own returns a 400.
​
string
required
Reward redemption start date (ISO8601)
​
string
Reward redemption end date (ISO8601). Omit for an open-ended redemption window.
​
integer
Reward expiry measured in days from issuance, 1-999 — for example 14 for “expires 14 days after the guest receives it”. Omit for no relative expiry, which leaves each reward bounded only by the campaign’s redemption window.
​
array
required
Campaign variants (1-4 variants)

​
Response

Returns 201 Created with the campaign object.