Update subscription

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.

Update timing details

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.

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.