Backdate subscriptions

You can backdate a subscription to bill customers for time that has already elapsed. This is often used when migrating to Stripe or for record keeping purposes. The backdate_start_date field specifies the subscription’s backdated start date. You also have the option to bill customers for this elapsed time and set the next billing date.

Billing mode considerations

As of API version 2025-04-30, the behaviour of backdating depends on your subscription’s billing_mode:

Backdating and charging users

Sometimes users can have access to your service before you create a subscription for them, and you want to charge them for that access.

This creates an invoice with charges for the time between the backdated start date and the current time.

If a subscription has billing_mode=classic, Stripe creates a single prorated amount for the backdated period based on an imagined interval starting from the backdated start date. For example, if you have a monthly billing cycle beginning on the first of the month and set backdate_start_date to 15 February (in a non-leap year), Stripe calculates the proration based on an imagined month running from 15 February to 15 March. Because February has 28 days, the prorated amount for the 14 days from 15 February to 1 March is exactly half the amount of a normal monthly charge.

Similarly, if you set the backdate_start_date to 15 January, Stripe bases the proration calculation on an imagined month running from 15 January to 15 February. That imagined month has 31 days, so the prorated amount for the 17 days from 15 January to 1 February is 17 divided by 31 (approximately 0.548) of a normal monthly charge.

You can also view the calculation by considering the backdated start date as the original start date. The beginning of the first full billing period then becomes the updated start date.

If a subscription has billing_mode=flexible, Stripe generates separate line items for each natural billing cycle that occurred during the backdated period. This means that each cycle is treated as if Stripe billed it normally during that time.

Backdating without charging users

You can also backdate a subscription without charging the customer for the backdated period, which you can use if you’re migrating to Stripe. To do so, pass proration_behavior: 'none' when you create the subscription. That sets the start_date to the same value as backdate_start_date, but it doesn’t charge the customer for backdated time.

Backdating and setting the billing cycle anchor

You can combine backdate_start_date with billing_cycle_anchor to backdate a subscription and set the billing cycle anchor to a date in the future. This creates a pro-rata item on the next invoice for the time between the backdated start date and the billing cycle anchor. You can use this if you’re migrating to Stripe and need to carry over the next billing date for your subscriptions while billing customers for elapsed time.

For example, say it’s 15 October and you’re migrating to Stripe. You have a subscription that started on 1 September, and the next billing date is 1 November. To migrate that subscription, create a new subscription and set backdate_start_date to 1 September and billing_cycle_anchor to 1 November.

curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d backdate_start_date=1575176400 \
  -d billing_cycle_anchor=1572580800 \
  -d "items[0][price]"=
{{PRICE_ID}}

This immediately issues an invoice for the pro-rata amount covering the time between 1 September and 1 November. It also sets the start_date of the subscription to 1 September. Stripe issues the next invoice on 1 November.

Backdating an update

To set the effective date of prorations when updating a subscription, use the proration_date parameter. Pass an integer Unix timestamp that occurs within the current period of the subscription’s items. If the subscription uses a subscription schedule, make sure that the timestamp is before the start date of the next phase of the schedule.

You can set the proration_date earlier than the current period only during the first period of a backdated subscription. In this situation, the proration_date must be on or after the subscription[start_date] (the backdated start date). In all other cases, the proration_date can’t be earlier than the current_period_start.