Coupons

Coupons are typically granted as an effect of a matched decide rule, then redeemed and checked through these two endpoints.

Redeem a coupon

POST https://api.retidal.com/api/v1/coupons/redeem

Auth: X-API-Key with scope coupon:redeem.

Rate limit: 30 requests/minute per (project, IP).

Redemption is idempotent per (profileId, couponId) unless you supply an explicit idempotencyKey — pass your own order ID or similar if you need to distinguish separate redemption attempts.

projectIdbodystringrequired

Must match the API key’s project.

codebodystringrequired

The coupon code to redeem.

profileIdbodystringrequired

The user/profile redeeming the coupon.

idempotencyKeybodystring

Defaults to <profileId>:<couponId> when omitted.

contextbodyobject

Optional free-form redemption context.

Request

{
  "projectId": "prj_123",
  "code": "SAVE10",
  "profileId": "uid_456",
  "idempotencyKey": "order-789"
}

200 — accepted (pending settlement)

{
  "redemptionId": "8f2c…",
  "status": "pending_settlement",
  "benefits": { "discountPercent": 10 }
}

benefits reflects whatever is configured on the coupon pool — it’s an empty object when the pool defines none.

Errors

Status	Meaning
400	Invalid JSON or a required field is missing (POST /api/v1/coupons/redeem).
401	Missing or invalid API key (POST /api/v1/coupons/redeem).
403	The key lacks the coupon:redeem scope (POST /api/v1/coupons/redeem).
404	Coupon not found, or cross-tenant (same response shape either way, to prevent enumeration) — POST /api/v1/coupons/redeem.
409	Not redeemable — already_redeemed, expired, revoked, or pool_not_ready (POST /api/v1/coupons/redeem).
429	Rate limit exceeded (30/min per project + IP) — POST /api/v1/coupons/redeem.

Look up a coupon

GET https://api.retidal.com/api/v1/coupons/{code}?projectId={projectId}

Auth: X-API-Key with scope coupon:read.

Returns sanitized metadata only — no userId or profileId is included in the response.

codepathstringrequired

The coupon code to look up.

projectIdquerystringrequired

Must match the API key’s project.

200

{
  "status": "redeemed",
  "form": "percentage",
  "poolId": "pool_1",
  "expiresAt": "2026-12-31T23:59:59Z",
  "redeemedAt": "2026-07-20T10:00:00Z"
}

redeemedAt is present only once the coupon has actually been redeemed.

Errors

Status	Meaning
401	Missing or invalid API key (GET /api/v1/coupons/{code}).
403	The key lacks the coupon:read scope (GET /api/v1/coupons/{code}).
404	Coupon not found, or cross-tenant (same shape) — GET /api/v1/coupons/{code}.

Next steps

Decide

See how a decision rule can grant a coupon in the first place.

Profiles

Keep profile traits current so decision rules evaluate correctly.