Campaign API Guideline

Campaigns are the marketing promotions that generate coupon codes. A user browses the running campaigns, claims a coupon code, and then applies that code at checkout to receive a discount.

Concept of Product Composition

Integration Flow

1. List the campaigns available to your partner account with /api/v1/campaigns.
2. Open a campaign with /api/v1/campaigns/{slug} to show its coupons. Send the user's bearer token so coupons the user already claimed come back in the same list.
3. Optionally page through the still-unclaimed codes of one coupon with /api/v1/campaigns/{slug}/coupons/{id}/codes.
4. Claim a code for the signed-in user with /api/v1/campaigns/coupons/claim.
5. Show the user's wallet with /api/v1/me/campaign-coupons.
6. Release a claimed-but-unused coupon with DELETE /api/v1/campaigns/coupons/{couponId}.
7. At checkout, list the claimed coupons that actually fit the cart with /api/v1/campaigns/coupons/applicable.
8. Pass the coupon code to the product's checkout endpoint — see Coupon at Checkout for the two keys to add. The coupon is only redeemed once the booking is paid.

Key Concepts

Term	Meaning
Campaign	The promotion itself: timeline, images, terms, and the products it targets.
Coupon	A discount setting inside a campaign (percentage or fixed, min spend, per-user limit).
Coupon code	One redeemable row. id in the claim/delete endpoints always refers to this row.
Claim	Assigns a free coupon code to the signed-in user. Status becomes claimed.
Redeem	Happens inside checkout. Status becomes redeemed and the code cannot be reused.

Response Envelope

Every endpoint returns the standard envelope:

{
  "result": 1,
  "message": "success",
  "data": {}
}

result is 1 on success and 0 on failure. A business rule that blocks the request (expired coupon, minimum spend not met, …) returns result: 0 with an explanatory message and HTTP 200. Only a missing campaign returns HTTP 404, and validation errors return HTTP 422.