Skip to main content
Once a subscription exists you can change it over its lifetime. Every change is available through the Update Subscription endpoint (and cancellation through Cancel Subscription), or from your dashboard.
One change per request. Each update carries exactly one intent: change the plan, or the payment method, or the trial, or the metadata. Combining them in a single request returns 400.
Fetch the current state first with Get Subscription; every update returns the full, updated subscription object.

​
Change the plan

Move a subscriber to a different plan by sending the target product_id. Bachs resolves the price from that product for the subscription’s currency, so you name the plan and the plan owns the price. Include a proration_behavior to say how the price difference is settled.
  • invoice_now: apply now and settle the difference immediately (upgrade charged, downgrade credited).
  • next_cycle: apply now, roll the difference into the next renewal.
  • none: change the terms with no proration.
The target product must bill at the same interval as the subscription and have a price in its currency, otherwise the request returns 400. A downgrade’s credit goes to the customer’s credit balance and is applied to future invoices automatically. See Proration for the full model.
Per-seat and quantity-based pricing are coming soon. Today a plan is a fixed-price product.

​
Manage the trial

Add, extend, or end a trial by setting trial_end. A future timestamp adds or extends the trial (nothing is charged); a past-or-now timestamp ends it and bills the first cycle immediately.
Full details, including ending a trial early, are on the Trials page.

​
Update the metadata

Merge into the subscription’s key-value metadata (up to 20 keys). Sent keys are added or overwritten and any keys you don’t mention are left untouched. To remove one key, send it with an empty-string value; to clear everything, send "".
Metadata is first attached at the checkout session that starts the subscription and copied onto it on success; this endpoint lets you change it afterward. The system-managed checkout_id key is preserved and can’t be overwritten.

​
Cancel a subscription

Cancel with the Cancel Subscription endpoint. You choose when the cancellation takes effect with cancel_at_period_end.
The subscription keeps working until current_period_end (the customer paid for that period), then transitions to canceled. Bachs sets cancel_at_period_end: true and emits customer.subscription.updated.
This is the gentler option: no partial refund, no interruption, access continues to the date they already paid for.
reason is optional (max 255 characters) and is stored on the subscription. Canceling an already-canceled subscription returns 400.

​
What makes a subscription canceled

A subscription reaches the terminal canceled status in exactly three ways:
  1. Immediate cancel: a DELETE with cancel_at_period_end: false.
  2. Scheduled cancel reaching the period end: after a DELETE with cancel_at_period_end: true, when current_period_end passes.
  3. Payment recovery exhausted: a subscription in recovery runs out of retries and your account is set to cancel (the default). The cancellation reason is payment_failed.
Once canceled, a subscription is terminal; a later payment can’t revive it. The customer must start a new subscription.

​
What customers can do themselves

When a payment fails, the customer receives an email with a hosted link to update their card. Completing it charges the outstanding invoice and reactivates the subscription, with no action needed from you. See Payment recovery.

Proration

How plan-change price differences are settled.

Subscriptions API

List, retrieve, update, and cancel subscriptions programmatically.