---
title: Applying a coupon to a subscription
description: Attach a coupon, let it run for its duration, and remove it.
domain: subscription
status: shipped
visibility: public
last_verified: 2026-07-11
order: 20
---
A coupon discounts a subscription once it is applied to it. Applying attaches the coupon, and from then on the subscription's invoices carry the discount for as long as the coupon's duration says.

## One coupon at a time

> [!NOTE]
> A subscription can have at most one active coupon. There is no stacking. To change which coupon applies, remove the current one first, then apply the new one.

Applying a coupon to a subscription that already has one is not how it works today; you remove the current one first.

## What applying does

When you apply a coupon:

1. It attaches to the subscription and starts discounting invoices.
2. It follows its duration: the first invoice only, every invoice, or a set number of months or years.
3. When a limited-duration coupon reaches the end of its window, it expires on its own and the discount stops.

## Removing a coupon

You can remove a coupon from a subscription at any time. From then on, invoices bill at the full price again. The record of the coupon having been applied stays for the history.

## The application's own state

A coupon on a subscription is in one of three states:

| State | Meaning |
|---|---|
| Active | Discounting the subscription's invoices now. |
| Expired | A limited-duration coupon that reached the end of its window. |
| Removed | Taken off by hand. |

## In the API

Apply a coupon to a subscription with `POST /v1/subscriptions/{id}/coupon`, remove it with `DELETE /v1/subscriptions/{id}/coupon`, and read the active one with a `GET` on the same path. A subscription can also be created with a coupon already attached. See the [API reference](/reference).

## Edge cases

- **One active coupon per subscription.** To change which coupon applies, remove the old one and apply the new one.
- **Removing does not undo past discounts.** Invoices already issued with the discount keep it; only future invoices go back to full price.
- **Redemption caps still apply.** A coupon that has hit its total or per-customer limit cannot be applied, even to a subscription that has none.