Rewards

A reward is the thing you send to a recipient. There are two types, and which one you pick changes when gift cards get issued.

Fixed rewards

You choose the exact gift card — brand and amount — at send time.

{
  "type": "FIXED",
  "utid": "U561593",
  "valueCents": 2500,
  "recipient": { "email": "casey@example.com", "firstName": "Casey" }
}

• utid identifies a catalog item; find it via GET /v1/catalog.
• The card is issued immediately when you send. The recipient's link shows their card as soon as issuance completes (usually seconds).

Choice rewards

You choose a value; the recipient chooses the cards.

{
  "type": "CHOICE",
  "valueCents": 5000,
  "recipient": { "email": "casey@example.com", "firstName": "Casey" },
  "allowedBrandKeys": ["B916708", "B725361"]
}

• The recipient can mix and match — a $30 card now, $20 later. Their link keeps working until the value is used up or the reward expires.
• allowedBrandKeys (optional) restricts which brands they can pick from. Omit it to allow the whole catalog.

Lifecycle

CREATED → SENT → OPENED → PARTIALLY_REDEEMED → REDEEMED
                    ↘ EXPIRED / CANCELED

Every transition emits a webhook event, and the full event history is on GET /v1/rewards/:id.

Useful fields

• externalId — your own reference (order id, user id). Filterable on GET /v1/rewards.
• campaign — free-form label for grouping sends.
• expiresAt — optional expiry; must be at least an hour in the future.
• message — a personal note shown on the redemption page.