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, 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

1. Open the customer

   In the main navigation, select Billing → Customers, then select the customer.

2. Start a new subscription

   Click Create Subscription and fill in plan, billing period, and currency.

3. Link a coupon

   In the Coupon section, click Add Coupon, pick the coupon from the dropdown, and confirm.

   
4. Verify and save

   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.

cURL

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

cURL

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.

cURL

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.

List associations

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"

Get one association

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.

Create a coupon

Coupons overview