Enable Subscribers to Upgrade Subscriptions

You can enable subscribers to upgrade their current subscriptions to superior subscriptions (as defined by you) through your self-care portal, with the upgrade taking effect immediately. To support this functionality, you must use the Subscribe APIs.

• Use Case: 2-4-10
• Completed By: Software Developer
• Estimated Completion Time: 1 day

​

Basic Scenario

A subscriber logs into your self-care portal and upgrades their subscription from product A to product B. This can also include changing the billing frequency from monthly to annually as an example. The upgrade is made effective immediately. The subscriber’s existing Subscription must be in Good Standing or in Soft or Hard Error, and the Subscription end date must not be in the past. The best practice is to provide a partial charge for the upgrade giving a prorated credit for the value left from the existing product A and only charge the subscriber the difference for the more expensive upgrade product B.

​

Design Approach

As shown in the following diagram, you must POST the change to the subscription endpoint, specifying which products/items on the subscription are to be replaced. You can optionally provide a new billing plan if the billing frequency is also going to change. If the upgrade fails due to an inability to collect funds, you must request a new payment method using PMT and resubmit the subscription upgrade with the new payment method.

• Upgrade Subscriptions Using Subscribe APIs

Parent topic:Subscription Upgrades & Downgrades

​

Upgrade Subscriptions Using Subscribe APIs

1. POST the subscription change to the subscriptions endpoint. You must provide Subscribe with the following information to perform the upgrade through the API:
   • The item ID on the subscription that you wish to replace/upgrade. (An item represents a current product on the subscription.)
   • The old product ID for the item being upgraded.
   • The new product ID for the upgrade.
   • A new item ID for the item being created (this identifies the new product being added to the subscription).
   • (optional) The new billing plan ID. (Only required if you wish to change to a new billing plan.)
   • The date when the upgrade is effective. (options: effective_date=today or effective_date=nextBill)
     • This use case specifies today to have an immediate effect.
   • Whether the upgrade is prorated. (options: billing_prorated_period=true or false) Sample Code:
   • Upgrading by replacing a product on a Subscription: https://github.com/Vindicia/CashBoxRESTCodeSamples/blob/master/Autobill/Autobill_modify_replaceAProduct.txt
   • Upgrading by changing the Billing Plan: https://github.com/Vindicia/CashBoxRESTCodeSamples/blob/master/Autobill/Autobill_modify_billing_plan_change.txt
   • Upgrading by both replacing a product and changing the Billing Plan: https://github.com/Vindicia/CashBoxRESTCodeSamples/blob/master/Autobill/subscription_modify_ProductAndBillingPlanChange.txt
2. If the upgrade fails due to an inability to collect funds, request a new payment method from the subscriber using PMT and resubmit the change with the new Payment Method VID.

• The Subscription contains the new product and the old one has been marked as removed.
• The new Billing Plan is in place (if applicable).
• The Transaction is generated if applicable, including any applicable taxation.
• Future billings are correctly predicted.
• The Account has been granted appropriate Entitlements.

Parent topic:Enable Subscribers to Upgrade Subscriptions