​

Run the incentives ledger

​

1. What an incentive is — and what it is not

​

2. Issue one-off promos and support credits

• Reward type — pick the reward class above. For a credit, set the billing ledger as the destination; for a discount_code or gift_card, give an amount (percentage points for a discount, minor units — cents — for a gift card) and currency (ISO 4217).
• Recipient — attach a contact_id or an out-of-band email; at least one is required so the ledger can trace the reward back to a person.
• Source ref — any caller-side reference (ticket id, order id, campaign run label) up to 200 chars. It keeps ledger rows auditable later.
• Provider id — optional; defaults per reward type when omitted. credit is handled internally; gift cards route manual until you wire provider credentials.
• Idempotency key — send an Idempotency-Key header or the idempotency_key body field to make retries safe: a matching retry replays the original incentive instead of minting a duplicate. Retries after a redeem or void return the CURRENT lifecycle, not a stale snapshot.

​

3. Audit the issued-incentive ledger

​

4. Redeem or void a reward

• POST /incentives/{id}/redeem with an optional reference (order id, ticket id, …) and metadata stamps redeemed_at and marks the row redeemed.
• POST /incentives/{id}/void with an optional reason (audit-friendly note) stamps voided_at and marks the row voided.

​

5. Wire incentive codes into outbound campaigns

• Per-recipient campaign codes — the campaigns engine has a {{coupon_code}} merge-tag that derives a deterministic code from the recipient identity, so a whole audience receives a unique value that nothing shares.
• Standalone issue then campaign — for your API-minted rows, read code from GET /incentives/issued?…, put it into your template variables for that send, then mark the row redeemed when fulfillment actually happens so the lifecycle stays honest.

​

Worked example — end to end

# 1) Issue the support credit (gift card example; the same shape fits discount codes
#    and account credits). Idempotency key makes the retry safe.
curl -X POST "{API_BASE}/incentives/issue" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-4891-gc-001" \
  -d '{
    "reward_type": "gift_card",
    "source_ref": "support-ticket-4891",
    "recipient": { "email": "customer@example.com" },
    "amount": 2500,
    "currency": "USD"
  }'

{
  "data": {
    "id": "ipo_d7a2f1c9e8b34f01a2c3d4e5f6a7b8c9",
    "status": "issued",
    "reward_type": "gift_card",
    "amount": 2500,
    "currency": "USD",
    "issued_at": "2026-08-29T11:04:00.000Z",
    "replayed": false
  }
}

# 2) Audit the ledger filtered to this issue's class
curl "{API_BASE}/incentives/issued?source=api&reward_type=gift_card" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "data": [ { "id": "ipo_d7a2f1c9e8b34f01a2c3d4e5f6a7b8c9", "status": "issued" } ] }

# 3) Redeem it
curl -X POST "{API_BASE}/incentives/ipo_d7a2f1c9e8b34f01a2c3d4e5f6a7b8c9/redeem" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reference": "order-99821", "metadata": { "channel": "web" } }'

# 4) Void if the credit is scrapped; a terminal row rejects further transitions
curl -X POST "{API_BASE}/incentives/ipo_d7a2f1c9e8b34f01a2c3d4e5f6a7b8c9/void" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "customer declined the credit" }'