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.

Update timing details

Expand all

Immediate updates

When you set mode to IMMEDIATE , Solidgate resets the billing anchor to the current date and starts a new billing cycle. 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. Use this when a customer upgrades or downgrades their plan and you want the change to take effect right away.

Period-end updates

When you set mode to PERIOD_END , the current billing cycle completes at the original price and the billing period does not move. The change applies when Solidgate generates the next renewal invoice. Use this for scheduled plan changes, such as when a customer requests a downgrade at the end of their current period.

Subscription modifications

You can make the following changes to an active subscription.

Each subscription must always have exactly one recurring line item. You can add or remove one-time line items when updating an existing subscription.

To switch a subscription to a different billing period or price, replace the current recurring line item with a new one that references the target product price.

To change the customer, billing currency, or channel, create a new subscription.

Setting mode to IMMEDIATE applies only while the subscription status is ACTIVE . If the subscription is in any other status, including REDEMPTION , the update request returns SUBSCRIPTION_IN_PROCESSING .

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 its id and a new quantity value in to_update .

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:

Add one-time items

Add a one-time item, such as a setup fee or add-on, to an active subscription without changing the recurring item. Reference the target product_price_id and quantity in to_add .

The item appears on the next invoice generated for the subscription. Once that invoice is paid, the item is removed from the subscription automatically.

To remove a one-time item before it is billed, add its identifier to to_delete when updating the subscription.

Handle events

Solidgate sends SUBSCRIPTION_UPDATED when you change a subscription’s fields through an update request, such as applying a discount or changing the payment instrument. Status transitions, like moving to REDEMPTION or UNPAID , trigger their own events, listed in the subscription events reference.