Managing subscriptions often means responding to real-life customer behavior, including special offers or adjustments to pricing plans. The Solidgate subscription update allows you to handle multiple subscription modifications through a single request. It ensures quick responses to customer needs without complex sequences of actions. This flexibility aims to reduce churn while supporting retention and upselling strategies.
Subscription update options
You can use the following subscription management options on their own or consider combining them to match the specific business case:
Adjust the trial period to support customer decision-making, increase the likelihood of conversion, and improve their experience.
Typical use cases include:
- extend the trial to give the customer more time to explore the product
- end the trial early to convert the customer, optionally with a discount for an upgrade
Apply a discount to an active subscription to retain customers or encourage upgrades. You can use a specific coupon ID or share a coupon code for customers to redeem. Discounts take effect from the next billing period.
You might offer a discount to:
- reduce churn by maintaining engagement and keeping customers subscribed
- encourage customers to upgrade to a higher-tier product
Modify customer subscriptions and adjust invoices with proration. Solidgate supports mid-period changes, applying proration and updating billing schedules to ensure fair charges for the service used.
Possible actions to combine:
- change the product and apply a discount to meet customer needs
- skip the trial and change the product to provide a more tailored offer
Please note that any active discount is:
- replaced when a new discount is applied
- removed when the customer’s offer is upgraded or downgraded
id and at least one field with a preferred value to apply the needed change. You can update the trial period, apply a discount using a coupon_id or coupon_code, or switch to a new product by passing the new product_id. Changes can be combined in one request if needed.
Upgrade and downgrade subscription
Upgrading or downgrading a subscription means switching a customer from their current product to another product with a different price or billing period. Once you pass the new product_id in your request with the preferred change options, Solidgate automatically:
- calculates price differences through proration
- aligns the billing schedule
- generates an invoice for the price adjustment
- charges the customer
This guarantees fair service usage. Customers are charged only for the portion of the service used up to the moment of the switch.
Proration
When a customer switches products in the middle of a billing period, Solidgate automatically calculates the final charge that the customer needs to pay. The calculation considers:
- Whether billing periods match or not
- Whether it is an upgrade or a downgrade
- Unused portion from the old product
- Price of the new product
Depending on the billing period, Solidgate may credit or refund the unused portion of the old product before charging for the new product.
The price is prorated when changing subscription products:
- If the prorated payment for the new product fails, the subscription reverts to the previous product.
- If proration results in a negative balance, Solidgate charges the full price of the new product and always refunds the unused amount of the old product.
Examples:
A customer switches from a 6-month product costing $60 to an Annual product. The switch occurs halfway through the 6-month billing period, on day 90 of 180 at 00:00 UTC.
The customer’s unused portion is $30, and the new product price is $100.
The final charge amount is prorated, and the customer is charged $70 at the switch. The next billing date is one year from the switch date, starting a new annual billing period.
A customer switches from a 12-month product costing $120 to a 3-month product. The switch occurs on day 200 of a 365-day annual billing period at 00:00 UTC, leaving 165 days remaining.
The customer’s unused portion is $54.25, and the new product price is $30.
In this case, the price difference between products results in a -$24.25 amount.
Due to a negative proration result, Solidgate refunds $54.25 for the unused portion of the old product. It also charges the $30 price of the new product at the switch. The subscription’s next billing date is three months from the switch date, starting a new quarterly billing period.
Trial and product switch
When switching from one product with a trial to a different one with a trial, the original trial end date is preserved.
- If the new trial is free, no charge is made, and billing starts at the original trial end date.
- If the new trial is paid, the full trial price is charged immediately, but the trial still ends on the original trial end date.
Switching from a product with an active free or paid trial to a different product with a paid trial charges the full trial price at the switch. The original trial end date remains unchanged.
If a customer has paid for a trial before switching to another product with a paid trial, refunds for the previous trial payments are not processed automatically. In such cases, the merchant should issue refunds manually.
To change the trial end date during the subscription update request, use the
trial_end_date object to deactivate the trial immediately or set a specific end date.
Billing period alignment
The effect on the billing period and charge logic depends on whether the new product uses the same billing period as the old product.
Same billing period
When switching between products with the same billing interval, like monthly to monthly or yearly to yearly:
- Existing billing period dates are preserved
- Next billing date remains unchanged
- Current period charges are adjusted through proration
In this way, the billing schedule remains unchanged, and the customer keeps their original billing date. Price adjustments apply only to the current period and do not affect the next invoice.
Example:
A customer switches from a Basic monthly product costing $10 to a Premium monthly product costing $20. The billing period is monthly for both products, with a charge on the 1st of each month. The switch occurs on March 15 at 00:00, leaving 17 days remaining.
The customer’s unused portion is $5.48, and the remainder of the new price is $10.97.
The final charge amount is prorated, and the customer is charged $5.49 at the switch. The next billing date of the subscription remains April 1, starting the next monthly billing period.
Different billing period
When switching between products with different billing intervals, like monthly to yearly or quarterly to monthly:
- Existing billing period realigns to the switch date
- Next billing date resets to match the new product’s interval
- Current period charges are adjusted through proration
As a result, the customer’s billing date changes to the switch date, creating a new billing period. Proration ensures fair adjustment for both the unused old period and the new period cost.
Example:
A customer switches from a Monthly product costing $15 to an Annual product on March 10 at 00:00 UTC.
The customer’s unused portion is $10.16, and the new product price is $150.
The final charge amount is prorated, and the customer is charged $139.84 at the switch. The next billing date is March 10 next year, starting a new annual billing period.
Proration applies automatically to both upgrades and downgrades, so customers are only billed for what they use. Billing periods align automatically when products are switched, and this process works seamlessly with other subscription updates, such as applying discounts or adjusting trials. All adjustments can be combined, and Solidgate calculates charge amounts automatically when you update a subscription.
Handle subscription update errors
When an update request cannot be processed, you receive an error response that helps you quickly locate and fix the reason for the error.
Common error scenarios appear when:
- Request excludes required fields or includes incorrectly formatted data. For example, the
trial_ended_atfield must not be empty if you include the trial information. - Request format is correct but does not match the current state of the subscription. For example, if the subscription is no longer in a trial period, trying to skip or extend the trial results in an error.
- Request includes an unsupported value. For example, an unsupported value is passed for the
trial_ended_atfield, only immediate or specific_date values are allowed.