Updating plans
Odus allows you to modify active subscriptions by changing their pricing plan at any time. This functionality enables both upgrades (moving to a higher-priced plan) and downgrades (moving to a lower-priced plan) with automatic proration calculations.
Before applying any changes, a preview must be generated to show the customer the exact impact of the change. This ensures that both merchants and customers can understand the implications of the Subscription plan change before proceeding.
Flow Overview
Generating a Preview
Before applying any changes to a subscription, a preview must first be generated that calculates the exact impact of the change. This preview calculation takes into account the current subscription state, the new pricing plan, and applies the configured proration strategy to determine the final result.
Always show a preview to your customers before applying subscription changes. This ensures transparency and allows customers to understand the financial impact of their plan changes.
To generate a preview, send a POST /subscriptions/:id/preview request with the new price ID. The request is straightforward and only requires the target price:
{
"price": "price_new_id"
}
The preview response includes the following:
amountDue: The total amount the customer needs to pay to proceed with the upgrade.amountCredit: The total amount the customer will be credited after the downgrade.id: A unique identifier for this preview, which must be used when applying the changes.previewValidUntil: The timestamp indicating when the preview expires (15 minutes from generation).subscription: Subscription as it will look like after the changes are applied.
Any changes made to the subscription after generating the preview will invalidate the preview. This also includes automatic updates performed as a part of recurring billing. If the preview expires or becomes invalid, you must generate a new preview.
Proration Strategies
Odus uses different strategies to calculate how subscription changes are prorated. The system is designed to support multiple approaches, but currently only one strategy is available.
Add Remaining Days Strategy
The addRemainingDays strategy calculates proration by extending the subscription period instead of issuing credits.
When both upgrading and downgrading, the customer pays full price of the new plan immediately, and any remaining days from the current plan are added to the new subscription period. The date of the plan update becomes the start of the new subscription period.
A customer purchased a $10/month monthly plan on the 10th of the month. They used the plan for a week and decided to upgrade to an annual plan priced at $100/year on the 17th of that same month.
The customer will be charged $100 for the annual plan, and the remaining days from the monthly plan (ex. 23 days) will be added to the new subscription period. This means the annual plan will start immediately after upgrading and extend for 365 days plus the remaining 23 days, resulting in a total of 388 days of service.
A customer on an annual plan priced at $120/year decides to downgrade to a monthly plan priced at $10/month halfway through their annual subscription (after 6 months).
The customer will not receive any credit for the remaining 6 months of the annual plan. Instead, they will be charged $10 for the monthly plan, and the remaining 6 months of the annual plan will be added to the new monthly subscription period. This means the first cycle of the new monthly subscription will last for 30 days plus the remaining 6 months, resulting in a total of 210 days of service before the next payment is due, after which the customer will be charged according to the new plan.
Applying Subscription Changes
Once you have generated and reviewed a preview, you can apply the subscription changes using the preview ID.
You must use the preview ID from the previous step. You cannot apply subscription changes without first generating a preview. This ensures that all calculations are accurate and consistent with what was shown to the customer.
To apply the changes, send a POST /subscriptions/{id} request with the preview ID:
{
"previewId": "sub_preview_generated_id"
}
When the request is submitted, Odus will validate the preview and subscription state to ensure they are still valid for modification. If there's an amount due from the preview, a new invoice will be created and automatically billed using the customer's default payment method through the gateway that was used to setup the subscription.
The payment will fail if customer action, such as 3DS Authentication, is required.
This is a safety measure as customer action is asynchronous by its nature and could lead to the preview becoming invalid before the payment has finished processing.
If the invoice is not paid successfully, it is immediately voided, and the subscription remains unchanged. This means that if the payment fails, the customer will not be charged, and they can retry the upgrade after resolving any payment issues.
Edge Cases
To ensure the smoothest user experience, there are some edge cases to consider.
Invalidated Previews
As mentioned earlier, previews can be invalidated due to:
- Changes made to the subscription after the preview was generated, including automatic system updates.
- The preview expiration time of 15 minutes being reached.
If a preview becomes invalid, you must generate a new preview before applying any changes. This ensures that the customer sees the most accurate and up-to-date financial impact of their subscription changes.
Declined Payments
In case of a declined payment, the invoice will be voided, and the subscription will not be updated. This will be accompanied by a 400 error response indicating that the invoice billing failed.
We recommend that the customer is informed about the payment failure.
At this moment, the system does not support subscription upgrades or downgrades with a payment method that is not the customer's default payment method.