Coupons

Reusable discounts on subscription invoices, applied by id or through a promotion code.

A coupon is a percentage or a fixed amount off a subscription's cycle invoices: for the next invoice (once), for a number of months (repeating) or for good (forever). Apply it to a subscription by id, or hand out promotion codes that redeem it. The subscription keeps a snapshot of the discount, so editing or retiring the coupon never changes a running discount. The discount is taken off the lines' total and VAT is computed on what the customer pays; see subscriptions.

The coupon object

idstring

Prefixed cpn_.

objectstring

coupon

namestring

percent_offnumber | null

Percentage off each discounted invoice.

amount_offinteger | null

Fixed amount off, in minor units of currency.

currencystring | null

The currency of amount_off.

durationenum

once, repeating or forever.

duration_in_monthsinteger | null

For repeating.

max_redemptionsinteger | null

redeem_bytimestamp | null

After this the coupon can no longer be applied.

times_redeemedinteger

activeboolean

false once retired. Running discounts keep going.

metadataobject

created_attimestamp

updated_attimestamp

Create a coupon

POST/v1/couponsSecret key

Body

namestringrequired

percent_offnumber

0 to 100. Give this or amount_off.

amount_offinteger

In minor units; needs currency. Give this or percent_off.

currencystring

With amount_off. Subscriptions in another currency cannot use the coupon.

durationenumdefault: forever

once, repeating or forever.

duration_in_monthsinteger

Required with repeating, refused otherwise.

max_redemptionsinteger

Across every code and direct application.

redeem_bytimestamp

metadataobject

curl https://api.borga.is/v1/coupons \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring 20%", "percent_off": 20, "duration": "repeating", "duration_in_months": 3 }'

Errors: invalid_field for both or neither of percent_off and amount_off, missing_field for currency or duration_in_months.

Retrieve a coupon

GET/v1/coupons/:idSecret key

Update a coupon

POST/v1/coupons/:idSecret key

The discount itself cannot change; create a new coupon and retire this one.

Body

namestring

activeboolean

false retires the coupon.

metadataobject

List coupons

GET/v1/couponsSecret key

Query parameters

limitintegerdefault: 25

starting_afterstring