Discounts

Early access. Write to hello@bouclay.com to have it turned on for your account.

A discount takes money off a subscription’s invoices for as long as you choose. You create discounts in the dashboard under Catalog → Discounts; your app applies them through the API by code or id.

What a discount can be

Setting	Options
Type	`percentage` (such as 20% off) or `flat` (such as ₦2,000 off, in one currency).
Duration	`once` (the first invoice), `repeating` (the first `durationInIntervals` billing periods) or `forever`.
Covers	`everything` (every fee and usage line) or `fixed_fees` (plan and add-on fees only, so a launch offer on a usage plan costs a known amount however much the customer uses).
Limits	An optional code customers type, a start and expiry date, and a maximum number of redemptions.

Proration lines never take a discount. Tax is worked out on the discounted amount.

Apply a code when someone subscribes

Pass the code the customer typed. It is matched without regard to case:

curl https://bouclay.com/api/v1/subscriptions \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: subscribe-user-42-pro" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "ctm_…",
    "collectionMode": "automatic",
    "items": [{ "priceId": "price_…" }],
    "discountCode": "LAUNCH20"
  }'

A code that doesn’t exist, has expired or has run out is refused with a 422 on discountCode that says why. With a trial, the discount starts on the invoice the trial converts to. You can pass discount (a disc_… id) instead of a code.

Apply or remove one later

For a code entered after signing up, or one your support team gives:

curl https://bouclay.com/api/v1/subscriptions/sub_…/discount \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: discount-sub-123-SORRY10" \
  -H "Content-Type: application/json" \
  -d '{"discountCode": "SORRY10"}'

A subscription holds one discount at a time, so this replaces any discount already on it, from the next invoice. DELETE /subscriptions/{id}/discount takes it off. Invoices already issued keep theirs.

Read discounts

GET /discounts and GET /discounts/{id} return your discounts with timesRedeemed, so you can show what a code gives before the customer applies it.

Get started

Connect your app

Gateways

Catalog and subscriptions

Usage billing

Invoices and payments

Credits

Reporting

What a discount can be

Apply a code when someone subscribes

Apply or remove one later

Read discounts

​What a discount can be

​Apply a code when someone subscribes

​Apply or remove one later

​Read discounts

What a discount can be

Apply a code when someone subscribes

Apply or remove one later

Read discounts