Skip to main content

​
Coupons

Coupons provide discounts that are applied to customer invoices during generation.

​
Create a coupon

curl -X POST /v1/coupons \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME20",
    "name": "Welcome 20% Off",
    "coupon_type": "percentage",
    "percentage_rate": "20.00",
    "frequency": "recurring",
    "frequency_duration": 3,
    "reusable": true,
    "expiration": "time_limit",
    "expiration_at": "2025-12-31T23:59:59Z"
  }'

​
Coupon types

TypeDescriptionRequired field
fixed_amountFixed monetary discountamount_cents, amount_currency
percentagePercentage off subtotalpercentage_rate

​
Frequency

FrequencyBehavior
onceApplied to one invoice, then terminated
recurringApplied for frequency_duration billing periods
foreverApplied indefinitely

​
Apply a coupon to a customer

curl -X POST /v1/coupons/apply \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "coupon_code": "WELCOME20",
    "customer_id": "customer-uuid"
  }'
  • Non-reusable coupons can only be applied to one customer (409 if already used)
  • Expired or terminated coupons cannot be applied (400)
  • Amount and percentage can be overridden per application

​
How discounts are calculated

During invoice generation:
  1. All active applied coupons for the customer are retrieved
  2. Percentage discounts: discount = subtotal × rate / 100
  3. Fixed amount discounts: min(amount_cents, remaining_subtotal)
  4. Discounts are applied sequentially — if the subtotal reaches zero, remaining coupons are skipped
  5. The total discount is recorded as coupons_amount_cents on the invoice

​
Terminate a coupon

DELETE /v1/coupons/{code}
Sets the coupon status to terminated. Existing applied coupons remain active until consumed.

​
Add-ons

Add-ons are one-time charges applied to customers. When an add-on is applied, a one-off invoice is generated.

​
Create an add-on

curl -X POST /v1/add_ons \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "onboarding",
    "name": "Onboarding Fee",
    "amount_cents": 50000,
    "amount_currency": "USD"
  }'

​
Apply an add-on

curl -X POST /v1/add_ons/apply \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "add_on_code": "onboarding",
    "customer_id": "customer-uuid",
    "amount_cents": 45000
  }'
When applied:
  1. An AppliedAddOn record is created
  2. A one-off invoice is generated with the add-on as a line item
  3. A fee with fee_type: add_on is created
The amount_cents can be overridden from the default add-on price.

​
API endpoints

​
Coupons

MethodPathDescription
POST/v1/couponsCreate a coupon
GET/v1/couponsList coupons (filterable by status)
GET/v1/coupons/{code}Get coupon details
PUT/v1/coupons/{code}Update a coupon
DELETE/v1/coupons/{code}Terminate a coupon
POST/v1/coupons/applyApply coupon to customer

​
Add-ons

MethodPathDescription
POST/v1/add_onsCreate an add-on
GET/v1/add_onsList add-ons
GET/v1/add_ons/{code}Get add-on details
PUT/v1/add_ons/{code}Update an add-on
DELETE/v1/add_ons/{code}Delete an add-on
POST/v1/add_ons/applyApply add-on to customer