# Service period coupons

Discount a specific time window on a subscription regardless of billing cadence or invoice timing.

> Service period coupons are in [private preview](https://docs.stripe.com/release-phases.md), and functionality might change during development. Use the registration form below to request access.

Service period coupons determine discount eligibility based on when you provide service, not when you create an invoice. Stripe discounts the portion of each subscription line item whose service dates overlap the discount’s service period schedule. Use a service period coupon when a promotion must apply to specific service dates instead of billing events.

### Request access to service period coupons

Enter your email to request access.

```bash
curl https://docs.stripe.com/preview/register \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Referer: https://docs.stripe.com/billing/subscriptions/service-period-coupons" \
  -d '{"email": "EMAIL", "preview": "service_period_coupons_preview"}'
```

## Before you begin

Service period coupons have the following limitations:

- You can’t apply them to metered prices with `max` or `last` aggregation formulas.
- You can’t apply them to metered prices with tiers.
- You can’t add them to draft invoices.
- You can’t create them as script coupons.
- A service period coupon’s service cycle anchor doesn’t update if you later change the subscription’s service cycle anchor.
- They can create more invoice line items because Stripe doesn’t aggregate line items that represent separate service periods.

## Choose a coupon type 

Use a service period coupon when the discount must follow service dates instead of billing events.

| Goal | Classic coupon | Service period coupon |
| --- | --- | --- |
| Discount a fixed service window across subscription cadences | Applies to the entire eligible line item created while the discount is active. A two month coupon can discount an entire annual line item. | Discounts only the portion of a line item whose service dates overlap the configured window. For example, a two month, 50% discount on a 240 USD annual subscription applies to 40 USD of service and discounts 20 USD. |
| Discount multiple service periods on one invoice | Applies one fixed amount to the eligible invoice. | Provides a separate amount-off allowance for each service period iteration. For example, three 30 USD monthly iterations apply up to 90 USD to one quarterly invoice. |
| Preserve an amount-off allowance during a plan change | Applies according to the billing events created by the plan change and doesn’t track a balance for a service period iteration. | Credit prorations restore previously consumed allowance, and eligible replacement charges can use the restored balance. For example, if a plan change credits 20 USD of previously discounted service, that 20 USD returns to the allowance for the same iteration. |
| Attach a discount now and start it in a future period | Doesn’t provide a coupon level start date setting. Your integration must wait to attach the coupon. | Set `start_date=current_period_end` to leave the current period undiscounted. For example, if you attach the coupon on January 15 and the current period ends February 1, the February 1 renewal is discounted. |
| End a discount at a subscription service cycle boundary | The coupon duration isn’t anchored to the subscription’s service cycle. | Use the subscription service cycle anchor to align iteration boundaries with the subscription. For example, a one month coupon that starts January 15 can have a shortened first iteration that ends at the February 1 renewal. |
| Apply a discount to the current service period | A discount-only update takes effect at a future billing event. | Adding an overlapping discount creates prorations. For example, after a service disruption, set `proration_behavior=always_invoice` to invoice the adjustment for the current service period immediately instead of waiting for the next renewal. |

## Define the service period schedule 

1. Create a service period coupon by setting `duration=service_period`.
2. Use `service_period.interval` and `service_period.interval_count` to define the length of each iteration.
3. Use `service_period.iterations` to define whether the iteration occurs a fixed number of times or continues indefinitely. Iterations are particularly significant for `amount_off` coupons because each iteration provides a separate allowance. For `percent_off` coupons, the percentage scales with the eligible service amount in each iteration. For example, the following coupon provides an allowance of up to 20 USD during each two month iteration. With three iterations, it lasts six months and provides up to 60 USD in total.

```curl
curl https://api.stripe.com/v1/coupons \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount_off=2000 \
  -d currency=usd \
  -d duration=service_period \
  -d "service_period[interval]=month" \
  -d "service_period[interval_count]=2" \
  -d "service_period[iterations][type]=count" \
  -d "service_period[iterations][count]=3"
```

## Calculate the discount 

Percent-off and amount-off service period coupons use the service period schedule specified in `service_period`, but calculate discounts differently.

### Calculate a percent-off discount 

A `percent_off` coupon applies its percentage to the portion of a line item whose service dates overlap the current iteration. For example, 50% off two months of a 240 USD annual subscription discounts 50% of the 40 USD attributable to those two months, resulting in a 20 USD discount.

### Calculate an amount-off discount 

An `amount_off` coupon provides a maximum allowance for each iteration. Stripe applies the allowance to eligible charges until it exhausts the allowance. Stripe doesn’t prorate the allowance according to the number of eligible service days. For example, if an iteration has a 200 USD allowance and the first eligible charge is 150 USD, Stripe discounts 150 USD. Other eligible charges, such as debit prorations, can use the remaining 50 USD during the same iteration. Eligible charges consume the allowance, and credit prorations restore it.

## Apply a service period coupon 

When you apply a service period coupon, Stripe creates a `Discount` with its own service period schedule. Configure [discount settings](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-discounts-settings) to choose when the schedule starts and how its iterations align with the subscription’s service cycle.

### Choose a start date 

When you [update a subscription](https://docs.stripe.com/api/subscriptions/update.md?api-version=2025-11-17.preview) to attach a coupon, use [`start_date`](https://docs.stripe.com/api/subscriptions/update.md?api-version=2025-11-17.preview#update_subscription-items-discounts-settings-start_date) to choose when the discount schedule begins. Suppose the current subscription item service period runs from January 1 through February 1, and you apply the coupon on January 15:

| Start date | Discount starts | Result |
| --- | --- | --- |
| `current_period_start` | January 1 | Sets the service period eligible for discounting to begin at the start of the current subscription item service period and creates prorations, but doesn’t discount service consumed before the update. |
| `now` | January 15 | Applies the discount only to service provided on or after January 15 and creates prorations. |
| `current_period_end` | February 1 | Leaves the current subscription item service period undiscounted. The renewal on February 1 is discounted. |

When an invoice line item spans the discount’s start date, Stripe creates prorations to apply the discount only to the overlapping service dates. Use [proration_behavior](https://docs.stripe.com/api/subscriptions/update.md?api-version=2025-11-17.preview#update_subscription-proration_behavior) to leave those adjustments pending or invoice them immediately. The following request starts the discount’s service period at the end of the current subscription item service period. Stripe creates the `Discount` immediately but doesn’t calculate a discount amount until the renewal on February 1.

```curl
curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "discounts[0][coupon]={{COUPON_ID}}" \
  -d "discounts[0][settings][service_period_anchor_config][type]=subscription_service_cycle_anchor" \
  -d "discounts[0][settings][start_date]=current_period_end"
```

### Align iterations to an anchor 

The [service period anchor](https://docs.stripe.com/api/subscriptions/create.md?api-version=2025-11-17.preview#create_subscription-discounts-settings-service_period_anchor_config) controls where iteration boundaries fall. When you apply a coupon directly to a subscription, Stripe uses the subscription’s service cycle anchor by default. You can also provide a custom calendar anchor. Suppose a one month service period coupon starts on January 15, and the subscription renews on the first day of each month:

- **Subscription service cycle anchor:** The first iteration runs from January 15 through February 1. The anchor shortens the first iteration so that later iterations align with the subscription’s service cycle.
- **Custom anchor on the fifteenth day of the month:** The first iteration runs from January 15 through February 15, preserving an entire one month iteration from the discount’s start date. The following request starts the service period immediately and aligns its iteration boundaries with the subscription’s service cycle anchor.

```curl
curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "discounts[0][coupon]={{COUPON_ID}}" \
  -d "discounts[0][settings][service_period_anchor_config][type]=subscription_service_cycle_anchor" \
  -d "discounts[0][settings][start_date]=now"
```