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.
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.

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.

Via API Send a request to the modify subscription API v2 endpoint with the subscription ID and the fields to modify. Include the optional application object with the mode field to control when the change takes effect. Pass immediate for instant changes or period_end to apply from the next billing period. Via Hub To modify a subscription

  1. Go to Billing > Billing 2.0 > Subscriptions.
  2. Click on the subscription ID to open the details page.
  3. In the top right corner, click on Update and modify the subscription.
  4. 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.