You can update active subscriptions without cancelling and recreating them. Updates let you switch plans, adjust quantities, manage discounts, change the payment instrument, and add or remove line items.
Changes apply either immediately or at the start of the next billing cycle, depending on when you decide the change should take effect.
When changes take effect
Once you update a subscription, you control when the change takes effect by using the optional application object with the mode field. It lets you apply the change immediately or at the end of the current billing period.
| Value | Behavior |
|---|---|
| immediate | The change applies now. The billing anchor resets to the current date and a new billing cycle starts immediately. The subscription anchor_at and next_billing_at fields are updated to reflect the new cycle. The change applies without proration, so the customer is not credited or debited for unused time in the current period. |
| period_end | The change is scheduled and applies at the next renewal. The current billing cycle continues unchanged at the current price, and the billing period does not move. The new items, quantities, or prices take effect when the next renewal invoice is generated. |
Subscription modifications
You can make the following changes to an active subscription.
| Change | Effect |
|---|---|
| Switch to a different price | Changes the plan amount or billing period. Use to upgrade or downgrade. |
| Change quantity | Increases or decreases the number of units, for example, seats. |
| Add a line item | Adds a recurring or one-time item to the subscription. |
| Remove a line item | Removes a recurring or one-time item from the subscription. |
| Apply or remove a coupon | Applies or clears a discount on the subscription. |
| Change payment instrument | Sets a different saved payment method for future charges. |
| Update metadata or description | Has no effect on billing. |
| Reset billing anchor | Resets the billing period to start from the update date. |
To switch a subscription to a different billing period or amount, remove the current line item and add a new one referencing the target product price.
To change a customer, billing currency, or channel, create a new subscription.
- Go to Billing > Billing 2.0 > Subscriptions.
- Click on the subscription ID to open the details page.
- In the top right corner, click on Update and modify the subscription.
- Click on Save.
Common tasks
Upgrade and downgrade
Upgrading or downgrading a subscription means switching a customer to a different product price. Pass a new product_price_id for an existing line item to change the plan. Solidgate updates the subscription and applies the new price based on the mode field.
When upgrading to a price with a different billing interval (for example, monthly to yearly), the billing anchor always resets regardless of the mode setting. A new billing cycle starts from the update date.
You can also change the quantity of an existing line item. Pass the line_item_id with a new quantity value.
Manage discounts
You can apply or remove a coupon on an active subscription. Pass a coupon_id or coupon_code in the update request. Send an empty discount value to remove an applied coupon.
Solidgate evaluates the discount just before each renewal:
- A one-time discount is removed after the first renewal.
- A limited-time discount is removed when its duration expires.
- A forever discount continues to apply on every renewal.
Handle events
Solidgate sends a webhook event when a subscription is updated.
| Event | Description |
|---|---|
| SUBSCRIPTION_UPDATED | The subscription was updated. The payload includes the updated subscription object with the new line items, discount, and metadata. |