> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouclay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discounts

> Promo codes and discounts that take money off a subscription's invoices

> [!NOTE]
>
> Early access. Write to [hello@bouclay.com](mailto: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:

```bash theme={null}
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:

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.