API REFERENCE
Coupons
One coupon engine handles eligibility, discount maths and redemption limits for invoice composition, validation and subscription application.
Manage coupons
| Method | Path | Purpose | Permission |
|---|---|---|---|
| POST | /merchants/:merchantId/coupons | Create a coupon. | coupons:write |
| GET | /merchants/:merchantId/coupons | List coupons with redemption counts. Filters: status, q. | coupons:read |
| GET | /merchants/:merchantId/coupons/:couponId | Read one coupon. | coupons:read |
| PATCH | /merchants/:merchantId/coupons/:couponId | Update configuration. | coupons:write |
| POST | /merchants/:merchantId/coupons/:couponId/archive | Archive a coupon. | coupons:write |
| POST | /merchants/:merchantId/coupons/:couponId/restore | Restore an archived coupon. | coupons:write |
| GET | /merchants/:merchantId/coupons/:couponId/redemptions | Redemption history. | coupons:read |
| Field | Type | Required | Notes |
|---|---|---|---|
| code | string | Yes | Uppercased, A-Z0-9_-. Unique per merchant. |
| name / description | string | No | — |
| type | percentage | fixed_amount | Yes | — |
| amount | number | Yes | A percentage for percentage coupons. |
| currency | string | No | Required for fixed-amount coupons. |
| duration | once | repeating | forever | No | — |
| durationInMonths | integer | No | Required when duration is repeating. |
| maxRedemptions | integer | No | Across all customers. |
| maxRedemptionsPerCustomer | integer | No | Defaults to 1. |
| minimumAmount | number | No | — |
| appliesToPlanIds | string[] | No | — |
| firstTimeTransactionOnly | boolean | No | — |
| redeemBy | ISO date | No | — |
| active | boolean | No | — |
Validate and apply
Validation never redeems. Application stores the coupon on the subscription and the next invoice includes the discount.
| Method | Path | Purpose | Permission |
|---|---|---|---|
| POST | /merchants/:merchantId/coupons/validate | Check a code against an amount, plan, customer and currency. | coupons:read |
| POST | /merchants/:merchantId/coupons/subscriptions/:subscriptionId/apply | Apply a code to a subscription. | coupons:write |
| DELETE | /merchants/:merchantId/coupons/subscriptions/:subscriptionId | Remove the coupon from a subscription. | coupons:write |
Invoice effect
- A negative discount line item is added to the renewal invoice.
- Invoice.discountAmount is populated for reporting and exports.
- A CouponRedemption row is written in the same transaction as the invoice.
- Fixed-amount coupons are currency checked before they are applied.