Changing a subscription

A subscription is not fixed once it starts. You can add and remove items, change how many of something a customer has, and move them to a different price. Each change can take effect right away or be scheduled for later.

What you can change

Change	What it does
Add an item	Put a new plan, add-on, or one-off on the subscription.
Remove an item	Take an item off.
Change the quantity	Change how many of an item, like the number of seats.
Change the price	Move an item to a different price, an upgrade or a downgrade.

You can also move a subscription to a different billing day when your organization uses calendar billing. See changing the billing day later.

Each of these acts on one item on the subscription. See how the catalog becomes a subscription for how items and prices fit together.

When the change takes effect

Every change has a timing:

Timing	When it lands
Now	Right away, in the middle of the current period.
End of term	At the next renewal, so the current period is untouched.
A specific date	On a date you choose.

A change made now happens mid-cycle, so it is prorated: the customer is credited for the unused part of the old item and charged for the rest of the period on the new one. See how proration works for the full picture, including the timeline of the credit and charge.

A one-off added now is the exception: there is no period to prorate, so the full charge is queued and billed once on the next invoice. It shows on the subscription as settled from the moment it is added, and it can be voided from the subscription's unbilled charges until it bills. If the subscription invoices upgrades immediately, the charge is invoiced right away.

A change set for end of term or a specific date is a scheduled change. It waits until then and applies on its own.

Scheduled changes

A scheduled change sits pending until its time comes, then it applies. Until then you can see it on the subscription and cancel it if plans change. If a scheduled change cannot apply when its time comes, it is marked failed rather than applied silently, so nothing changes without a record.

This is how you set up a change in advance: schedule a customer's upgrade for the start of next quarter, and it happens without anyone remembering to do it.

In the API

Make a change through the POST /v1/subscriptions/{id}/changes endpoint, giving the operation, the item, and the timing. You can also work with items directly: POST /v1/subscriptions/{id}/items to add one, PATCH to change it, and DELETE to remove it. List and cancel scheduled changes through /v1/subscriptions/{id}/scheduled_changes. See the API reference.

Edge cases

• A change now is prorated; a scheduled change is not. Proration only applies to the part of the period the change affects, which for an end-of-term change is none.
• A scheduled change can be cancelled while it is pending. Once it applies, it is part of the subscription.
• A scheduled change that cannot apply is marked failed, never applied halfway.