Coupons & Discounts

Coupons let you define reusable discount configurations that can be applied to subscriptions. When a coupon is applied to a subscription, it creates a discount that reduces the bill amount for one or more billing cycles.

How coupons work

A coupon defines the discount rules — what type of reduction, how much, and for how long. When you apply a coupon to a subscription, a discount is created on that subscription using the coupon's configuration.

1. Create a coupon — define the discount type, value, duration, and optional limits.
2. Apply to a subscription — apply the coupon to an active or trialing subscription to create a discount.
3. Bills are reduced — subsequent bills are automatically reduced by the discount amount.
4. Discount expires — the discount ends based on the coupon's duration setting.

Discount types

Coupons support two discount types:

Percentage example

A 20% discount coupon:

{
  "name": "Summer Sale 20%",
  "discount_type": "percentage",
  "value": 20,
  "duration": "repeating",
  "duration_in_cycles": 3
}

Fixed amount example

A £5.00 discount coupon:

{
  "name": "£5 Off",
  "discount_type": "fixed_amount",
  "value": 5.00,
  "currency": "GBP",
  "duration": "once"
}

📘

Currency matching

For fixed_amount coupons, the currency field is required and must match the subscription's price currency when applied.

Duration

The duration controls how many billing cycles the discount applies for once it is active on a subscription:

Redemption limits

You can optionally set max_redemptions to limit how many times a coupon can be applied across all subscriptions. Once the limit is reached, the coupon can no longer be applied to new subscriptions. Existing discounts already using the coupon are not affected.

Coupon lifecycle

To archive a coupon, submit a DELETE request to the /coupons/{coupon_id} endpoint. For more information, see the archive coupon API reference.

Applying a coupon to a subscription

To apply a coupon, submit a POST request to the /subscriptions/{subscription_id}/discount endpoint with the coupon_id:

{
  "coupon_id": "01JCX5Y8K9M3N4P6Q7R8S9T0UV"
}

Rules

• Only one discount can be active per subscription at a time.
• The subscription must be in active or trialing status.
• The coupon must be in active status and not have reached its max_redemptions limit.
• For fixed_amount coupons, the coupon's currency must match the subscription's price currency.

Scheduled activation

You can schedule a discount to take effect at a future date by providing effective_from:

{
  "coupon_id": "01JCX5Y8K9M3N4P6Q7R8S9T0UV",
  "effective_from": "2026-01-01T00:00:00Z"
}

The discount is created immediately on the subscription but only begins reducing bill amounts from the specified date.

Removing a discount

To remove a discount from a subscription, submit a DELETE request to the /subscriptions/{subscription_id}/discount endpoint. Removing a discount does not decrement the coupon's redemption count.

Viewing discounts

The discount is returned as part of the subscription response. By default, only the coupon_id is included. Use the expand query parameter to include the full discount details:

GET /subscriptions/{subscription_id}?expand=discount response:

{
  "id": "01HNY4G8G5ZMAXQB8T0Z1Y1ZMW",
  "status": "active",
  "customer": {
    "id": "c3e06b6f-bb52-4b2c-81a3-899860652240"
  },
  "discount": {
    "coupon_id": "01JCX5Y8K9M3N4P6Q7R8S9T0UV",
    "discount_type": "percentage",
    "value": 20,
    "remaining_cycles": 2,
    "applied_at": "2025-11-01T09:00:00Z",
    "effective_from": "2025-11-01T09:00:00Z",
    "end_date": null
  }
}