Coupons

Overview#

Coupons are discount codes your customers enter at checkout, or that you apply when you subscribe a customer. A coupon gives a percentage or fixed discount, can be limited to products or subscriptions (or to specific ones), and can have a validity window, a minimum amount and redemption limits. Manage them in the dashboard under Coupons or with the API on this page.

Requirements#

Coupons need the Coupons feature in your plan. Without it the Coupons page is not in the menu and shows an upgrade notice, hosted checkout shows no coupon field and a coupon code is rejected with "Coupons are not included in your plan". The API endpoints also need the REST API; without Coupons they return 403 plan_restricted ("Coupons are not included in your plan"). In the dashboard, viewing coupons needs coupons:read and creating or changing them coupons:write (see Roles).

Where coupons apply#

Coupons are not used on invoices, payment links or in the customer portal. When a coupon is used on a subscription, the subscription keeps its couponId and the coupon keeps applying per its duration, even if the coupon is later disabled or expires.

Coupon settings#

How discounts are calculated#

• The discount is taken from the price before discount and tax: the product amount, or the plan price × quantity for subscriptions.
• percent: price × value / 100, rounded to the nearest cent. fixed: the value. Either way the discount is never more than the price and never negative.
• Products: tax is calculated on the discounted price (added for exclusive prices, contained for inclusive prices).
• Subscriptions: a setup fee is not discounted. The first payment is setup fee + price − discount, with tax added on top when your prices exclude tax.
• A coupon that works out to no discount is rejected ("This coupon gives no discount on this item").

Example: WELCOME10 (10%) on a R 499,00 per month plan gives a discount of R 49,90, so the first payment is R 449,10 (plus tax if your prices exclude it).

Subscriptions: once, repeating or forever#

Recurring products are billed by the gateway at a fixed amount, so only forever coupons can be used on them ("This coupon cannot be used for recurring products"). duration has no effect on once-off products.

Validation rules#

A code is checked when it is entered at checkout, when the checkout is submitted, when a subscription is created with it, and by POST /api/v1/coupons/validate. The rules are checked in this order; the first that fails is returned with a customer-safe message:

When a customer subscription is created with a code that doesn't exist or is disabled, the error is "Coupon not found or no longer active"; the other reasons use the messages above.

Redemptions and limits#

Each use of a coupon is recorded as a redemption with a status:

• Hosted checkout: a pending redemption is recorded when the payer is sent to the gateway, and settled when the payment completes, fails or is cancelled. For a package checkout the redemption belongs to the subscription and is marked redeemed when the subscription activates.
• Trials and subscriptions created through the API or dashboard: no pending redemption is recorded; a redeemed one is recorded when the subscription activates (its first charge is paid).
• maxRedemptions and maxPerCustomer count redeemed redemptions plus pending ones less than 2 hours old, so an abandoned checkout frees its slot after 2 hours. The daily housekeeping job (01:00 South African time) voids stale pending redemptions (after 2 hours once the payment has failed or been cancelled, or after 24 hours while it is still pending).
• Hosted checkout counts maxPerCustomer across every customer record with the email address the payer enters (the validate endpoint does the same with customerEmail). A subscription created through the API or dashboard counts that customer's own redemptions.

The coupon's page in the dashboard lists its redemptions (customer, payment, subscription, discount, status and date). Through the API, use GET /api/v1/coupons/{id}?include=redemptions.

The coupon object#

{
  "id": "cmg5c8u2p0001cpn0001abcd",
  "object": "coupon",
  "code": "WELCOME10",
  "description": "Launch campaign",
  "type": "percent",
  "value": 10,
  "currency": null,
  "appliesTo": "subscription",
  "productIds": [],
  "planIds": [
    "cmg4p1a2b0002pln0001abcd"
  ],
  "duration": "repeating",
  "durationCycles": 3,
  "validFrom": "2026-09-28T08:00:00.000Z",
  "validTo": "2026-12-31T21:59:59.000Z",
  "maxRedemptions": 500,
  "maxPerCustomer": 1,
  "minAmount": null,
  "enabled": true,
  "redemptions": {
    "redeemed": 42,
    "pending": 2
  },
  "createdAt": "2026-09-28T08:00:00.000Z",
  "updatedAt": "2026-09-28T08:00:00.000Z"
}

Create a coupon#

Takes the fields in Coupon settings; only code, type and value are required. Numbers may be sent as numbers or numeric strings. Unknown fields are ignored.

curl -X POST "https://app.centrapoint.co.za/api/v1/coupons" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Idempotency-Key: 7a4c1e9b-2d3f-4b6a-8e0c-9f1d2a3b4c5e" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "welcome10",
    "description": "Launch campaign",
    "type": "percent",
    "value": 10,
    "appliesTo": "subscription",
    "planIds": [
      "cmg4p1a2b0002pln0001abcd"
    ],
    "duration": "repeating",
    "durationCycles": 3,
    "validTo": "2026-12-31T23:59:59+02:00",
    "maxRedemptions": 500,
    "maxPerCustomer": 1
  }'

Returns 201 with the coupon (redemptions is { redeemed: 0, pending: 0 }). Supports the Idempotency-Key header.

List coupons#

Returns { "data": [ … ] }, newest first, each with its redemptions counts.

curl -X GET "https://app.centrapoint.co.za/api/v1/coupons?code=WELCOME10" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Get a coupon#

Returns the coupon with its counts. With ?include=redemptions it also has recentRedemptions, a list of the latest 100 redemptions, newest first (redemptions stays the counts object):

curl -X GET "https://app.centrapoint.co.za/api/v1/coupons/cmg5c8u2p0001cpn0001abcd?include=redemptions" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY"

Update or disable a coupon#

Send any of the create fields. They are merged with the stored coupon and the result is validated as a whole (for example, switching to fixed needs a currency); an invalid result returns 400 invalid_request with the zod issues. null clears validTo, the limits and minAmount; validFrom: null keeps the current start. The code can't change once the coupon has been used. Unknown fields are ignored. The Idempotency-Key header is not used.

curl -X PATCH "https://app.centrapoint.co.za/api/v1/coupons/cmg5c8u2p0001cpn0001abcd" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Validate a coupon#

Checks whether a code would apply to a product or plan, for example to show the discount in your own checkout. Nothing is reserved or redeemed. The Idempotency-Key header is not used.

curl -X POST "https://app.centrapoint.co.za/api/v1/coupons/validate" \
  -H "Authorization: Bearer $CENTRAPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "welcome10",
    "planId": "cmg4p1a2b0002pln0001abcd",
    "customerEmail": "[email protected]"
  }'

Always returns 200 when the product or plan exists. total is amount − discount (before tax and setup fees); coupon is the coupon object, with its redemptions counts.

{
  "valid": true,
  "discount": 49.9,
  "amount": 499,
  "total": 449.1,
  "currency": "ZAR",
  "coupon": {
    "id": "cmg5c8u2p0001cpn0001abcd",
    "object": "coupon",
    "code": "WELCOME10",
    "…": "…"
  }
}

{
  "valid": false,
  "reason": "customer_limit",
  "message": "You have already used this coupon"
}

reason is one of the values in Validation rules.

Errors#