Copy page

Getting Started

Coupon

Coupons are specific promotional codes linked to a parent Reward. They represent the claimable codes issued to end users when milestones or campaign goals are achieved.

How it works

1. Create a reward — define a Reward record specifying the discount type, discount value, and expiry rules.
2. Add coupons — create Coupon entries linked to the reward's rewardId with unique couponCode values.
3. Issue to user — when a user completes a milestone, the platform selects an unissued coupon (isCouponIssued: false), marks isCouponIssued: true, and attaches it to the user's Reward Log.
4. Redeem — the user copies the couponCode from their widget or dashboard to redeem at checkout.

---

Fields

Basic information

Field	Type	Required	Max length	Description
rewardId	UUID	✅	—	The ID of the parent reward associated with this coupon
couponCode	string	✅	256	The unique promotional code (e.g., OFF2026, WEEKDAYSPECIAL)
isCouponIssued	boolean	✅	—	true · false (default: false). Indicates whether this coupon has been issued to a user
status	enum	✅	—	draft · live · paused — Current status of the coupon

---

Real-world examples

🛍️ E-commerce — 20% Off Campaign Coupon

An unissued promotional coupon ready for milestone assignment:

Code
{
  "rewardId": "123e4567-e89b-12d3-a456-426614174000",
  "couponCode": "OFF2026",
  "isCouponIssued": false,
  "status": "live"
}

---

☕ Food & Beverage — Weekday Special Coupon

A coupon that has already been issued to a user upon milestone completion:

Code
{
  "rewardId": "123e4567-e89b-12d3-a456-426614174001",
  "couponCode": "WEEKDAYSPECIAL",
  "isCouponIssued": true,
  "status": "live"
}

---

Access & permissions

Caller	Allowed operations
Admin	CREATE · GET · LIST · UPDATE · DELETE
End user	(none)
Guest (unauthenticated)	(none)

---

Related resources

Resource	Description
Reward	Parent reward that defines the discount benefit for this coupon
Reward Log	Logs generated when a coupon is issued to an end user
Milestone	Checkpoints that trigger reward and coupon issuance

---

API reference

See the API Reference for full request/response schemas and interactive examples for:

• GET /schema/coupon/record — list coupons
• POST /schema/coupon/record — create a coupon
• GET /schema/coupon/record/{id} — get a coupon by ID
• PATCH /schema/coupon/record/{id} — update a coupon
• DELETE /schema/coupon/record/{id} — delete a coupon