API REFERENCE

Coupons

One coupon engine handles eligibility, discount maths and redemption limits for invoice composition, validation and subscription application.

Manage coupons

MethodPathPurposePermission
POST/merchants/:merchantId/couponsCreate a coupon.coupons:write
GET/merchants/:merchantId/couponsList coupons with redemption counts. Filters: status, q.coupons:read
GET/merchants/:merchantId/coupons/:couponIdRead one coupon.coupons:read
PATCH/merchants/:merchantId/coupons/:couponIdUpdate configuration.coupons:write
POST/merchants/:merchantId/coupons/:couponId/archiveArchive a coupon.coupons:write
POST/merchants/:merchantId/coupons/:couponId/restoreRestore an archived coupon.coupons:write
GET/merchants/:merchantId/coupons/:couponId/redemptionsRedemption history.coupons:read
FieldTypeRequiredNotes
codestringYesUppercased, A-Z0-9_-. Unique per merchant.
name / descriptionstringNo—
typepercentage | fixed_amountYes—
amountnumberYesA percentage for percentage coupons.
currencystringNoRequired for fixed-amount coupons.
durationonce | repeating | foreverNo—
durationInMonthsintegerNoRequired when duration is repeating.
maxRedemptionsintegerNoAcross all customers.
maxRedemptionsPerCustomerintegerNoDefaults to 1.
minimumAmountnumberNo—
appliesToPlanIdsstring[]No—
firstTimeTransactionOnlybooleanNo—
redeemByISO dateNo—
activebooleanNo—

Validate and apply

Validation never redeems. Application stores the coupon on the subscription and the next invoice includes the discount.

MethodPathPurposePermission
POST/merchants/:merchantId/coupons/validateCheck a code against an amount, plan, customer and currency.coupons:read
POST/merchants/:merchantId/coupons/subscriptions/:subscriptionId/applyApply a code to a subscription.coupons:write
DELETE/merchants/:merchantId/coupons/subscriptions/:subscriptionIdRemove 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.