> ## Documentation Index
> Fetch the complete documentation index at: https://flexprice-mintlify-9d9353d9.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Apply Discount on Subscription
> Attach a coupon to a customer subscription from the dashboard or the API, including line-level targeting and mid-cycle changes.
You can attach a coupon to a subscription from the dashboard when you create or edit the subscription, or programmatically through the API. The API supports attaching coupons at subscription creation, adding or removing them mid-cycle, and targeting an individual line item instead of the whole subscription.
## Prerequisites
Before applying a discount, make sure:
1. The coupon is [created](/docs/product-catalogue/coupons/create), `published`, and inside its `redeem_after` / `redeem_before` window.
2. The coupon currency matches the subscription currency.
3. The coupon has not exhausted its `max_redemptions`.
## Apply a coupon during subscription creation
### From the dashboard
In the main navigation, select **Billing** → **Customers**, then select the customer.
Click **Create Subscription** and fill in plan, billing period, and currency.
In the **Coupon** section, click **Add Coupon**, pick the coupon from the dropdown, and confirm.
Review the pricing breakdown, then click **Create Subscription**.
### From the API
Pass one or more coupons under `subscription_coupons` when creating the subscription. Each entry references the coupon by its `coupon_code` (case-insensitive) and can optionally target a specific line item with `price_id`.
```bash cURL theme={null}
curl -X POST https://api.flexprice.io/v1/subscriptions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_customer_id": "ext-acme-corp",
"plan_id": "plan_pro_monthly",
"currency": "usd",
"billing_period": "month",
"billing_period_count": 1,
"subscription_coupons": [
{
"coupon_code": "WELCOME20",
"start_date": "2026-06-15T00:00:00Z"
},
{
"coupon_code": "API_ONLY_50_OFF",
"price_id": "price_api_calls"
}
]
}'
```
| Field | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------- |
| **`coupon_code`** | Human-readable code, unique per tenant and environment. Case-insensitive. |
| **`price_id`** | Optional. Restricts the discount to the line item that uses this price. Omit for a subscription-level discount. |
| **`start_date`** | Optional. Defaults to the subscription start date. |
| **`end_date`** | Optional. Overrides the coupon's `duration_in_periods` calculation. |
`subscription_coupons` is the preferred way to attach coupons at creation. The older `coupons` array that takes `coupon_id` is deprecated.
## Add or remove a coupon mid-cycle
Use the subscription modify API to attach or detach a coupon on an existing subscription. The same endpoint supports a preview that returns the proration impact without writing anything.
### Add a coupon
```bash cURL theme={null}
curl -X POST https://api.flexprice.io/v1/subscriptions/{subscription_id}/modify/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "coupon",
"coupon_params": {
"action": "add",
"coupon_code": "LOYALTY10",
"effective_date": "2026-07-01T00:00:00Z",
"price_id": "price_seats"
}
}'
```
| Field | Required | Description |
| -------------------- | ------------- | ------------------------------------------------------------------------------------ |
| **`action`** | Yes | `add` to attach a coupon. |
| **`coupon_code`** | Yes for `add` | Code of the coupon to attach. `coupon_id` is also accepted but deprecated. |
| **`effective_date`** | No | When the change applies. Defaults to now. |
| **`start_date`** | No | When the coupon association starts. Defaults to `effective_date`. |
| **`end_date`** | No | When the association ends. Overrides `duration_in_periods`. |
| **`price_id`** | No | Target a specific line item by its price ID. Omit for a subscription-level discount. |
To dry-run the change, call `/modify/preview` with the same body. The response includes the resulting `subscription`, any new `coupon_associations`, and the changed line items and invoices.
### Remove a coupon
To detach a coupon, send the `association_id` of the coupon association you want to soft-delete. You can find association IDs on the subscription response under `coupon_associations`, or list them with the [coupon associations API](#list-coupon-associations).
```bash cURL theme={null}
curl -X POST https://api.flexprice.io/v1/subscriptions/{subscription_id}/modify/execute \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "coupon",
"coupon_params": {
"action": "remove",
"association_id": "ca_01h...",
"effective_date": "2026-07-01T00:00:00Z"
}
}'
```
Removing a coupon affects invoices generated on or after `effective_date`. It does not change invoices that have already been finalized.
## List coupon associations
Use these endpoints to read the coupons currently attached to one or more subscriptions.
```bash List associations theme={null}
curl -G https://api.flexprice.io/v1/coupons/associations \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode "subscription_ids=sub_01h..." \
--data-urlencode "active_only=true"
```
```bash Get one association theme={null}
curl https://api.flexprice.io/v1/coupons/associations/{id} \
-H "Authorization: Bearer YOUR_API_KEY"
```
| Query parameter | Description |
| ------------------------- | ------------------------------------------------------------------------- |
| **`subscription_ids`** | Filter by subscription IDs. Up to 100. |
| **`coupon_ids`** | Filter by coupon IDs. Up to 100. |
| **`active_only`** | Return only associations whose `start_date`/`end_date` window covers now. |
| **`limit`**, **`offset`** | Standard pagination. |
Coupon associations are created and removed exclusively through the subscription modify API or at subscription creation. There is no `POST /coupons/associations` endpoint.
## How cadence applies
The discount duration on the association follows the coupon's `cadence`:
| Cadence | Behavior |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| **`once`** | Discount applies to the first qualifying billing period only. |
| **`repeated`** | Discount applies for `duration_in_periods` billing periods. An `end_date` on the association overrides this. |
| **`forever`** | Discount applies for the lifetime of the subscription, unless you remove the association. |
## Validation
Flexprice validates the following before attaching a coupon:
* The coupon exists, is `published`, and is within `redeem_after` / `redeem_before`.
* The coupon currency matches the subscription currency.
* `max_redemptions` has not been reached.
* Any custom rules on the coupon (for example, `customer_id`, `plan_id`, `amount`) match the target subscription.
If validation fails, the response includes a `hint` field that names the failing constraint.
## Troubleshooting
**Coupon not applying**
* Confirm the coupon `status` is `published` and inside its redeem window.
* Confirm the currency matches the subscription currency.
* Confirm `max_redemptions` has not been reached.
**`coupon_code` not found**
* Codes are case-insensitive but must match exactly otherwise. Check for trailing whitespace.
* Coupons are scoped per tenant and environment. A code in `production` is not visible from `sandbox`.
**Discount missing from a specific line item**
* If you passed `price_id`, confirm that the price belongs to a line item on the subscription.
* Subscription-level discounts apply to all eligible line items; line-level discounts apply only to the targeted line.