Add prepayment product to subscription
Overview
After you have created a prepayment subscription through Orders, if your customer is interested in purchasing more prepaid units, you can add additional prepayment products to the customer’s existing subscription.
You can add recurring prepayment charges or one-time prepayment charges to subscriptions anytime.
- Adding a recurring prepayment charge is allowed anytime, provided that the following fields are configured.
- For a recurring prepayment charge to be added to a standard period subscription at any time, you must configure the following fields:
- Select Term Start Day from the
Billing Day
list. - Select Align to Term Start from the
Billing Period Alignment
list.
BillCycleType
field to TermStartDay and theBillingPeriodAlignment
field to AlignToTermStart in the request body. - Select Term Start Day from the
- For a recurring prepayment charge to be added to a subscription containing a partial period at any time, you must configure the following fields:
- Select Term End Day from the
Billing Day
list. - Select Align to Term End from the
Billing Period Alignment
list.
BillCycleType
field to TermEndDay and theBillingPeriodAlignment
field to AlignToTermEnd in the request body. - Select Term End Day from the
The following behaviors of the recurring prepayment charges added to subscriptions are to be noted:
- The Start Date of the newly added fund is the Effective Date of the charge.
- No proration exists for the first partial validity period, which means the charge amount of the first partial validity period should be the same as that of an entire validity period.
- Recurring prepayment charges cannot be added to a shrunk subscription term.
- For a recurring prepayment charge to be added to a standard period subscription at any time, you must configure the following fields:
- Adding a one-time prepayment charge is allowed anytime during a validity period. The prepaid units in this newly added one-time charge will be valid from the charge effective date to the end of the current validity period.
Suppose you have configured an API Calls One-time Top-up rate plan in your API Calls Prepayment Service product as shown below:
Product: API Calls Prepayment Service | |
Product rate plan: API Calls One-Time Top-Up | |
Prepayment charge | Drawdown charge |
|
|
Your customer who has already subscribed to a 12-month plan wants to use more of your API because of new business for the coming month. You can do this by adding the above one-time rate plan to your customer’s existing subscription through the Zuora UI or REST API.
Zuora UI
Follow the steps described in Add a product to a subscription.
Select the desired product to be added to the order.
Update the one-time charge details if needed. In this example, you can increase the prepaid quantity to 10 if your customer needs an extra 10 Million API calls on an ad-hoc basis.
- For prepayment charge, you can update Price, Prepaid Quantity and Validity Period.
- For drawdown charge, you can update Price and Drawdown Rate.
- See the notes and limitations section for things to consider when adding prepayment products.
REST API
Use the Create an order operation to add a prepayment charge to a subscription. Determine the values of the following fields specific to the prepayment charge and drawdown charge to be added:
- prepayment charge:
prepaidQuantity
validityPeriodType
- drawdown charge:
drawdownRate
Sample request body: Add a one-time prepayment charge to an existing subscription.
Request | POST /v1/orders |
---|---|
Request body |
... "orderActions": [ { "type": "AddProduct", "addProduct": { "productRatePlanId": "4028818a7e2ef879017e327fb1ff0008", "chargeOverrides":[ { "productRatePlanChargeId": "4028818a7e2ef879017e327fb276000a", "prepaidQuantity": 10, "validityPeriodType": "MONTH" } ] } } ] |
You can view the customer’s prepaid balance through the Zuora UI or Data Query.
Notes and limitations
- If the newly added prepayment charge has the same Prepaid UOM with any existing prepayment charge in the subscription, the new prepayment charge must have the same validity period as the existing prepayment charge.
- Within a validity period, when the drawdown usage exceeds the existing prepaid balance, the overage usage record will not be displayed in the Transaction Records list in the Prepayment Balance section. If the prepaid balance fund is topped up with new prepayment charges, the overage item will not be immediately drawn down from the top-ups until the next bill run. Upon bill run, the overage item will be re-drawn down from the top-up balance appropriately.
-
Note the following options are also available for non-prepaid recurring charges:
- Billing Day: Term Start Day and Term End Day
- Billing Period Alignment: Align to Term End
You must follow the rules below when using the above options;
- The Term End Day option of the Billing Day field must be coupled with the Align to Term End option of the Billing Period Alignment field.
- For prepaid charges, the Term Start Day option of the Billing Day field must be coupled with the existing Align to Term Start option of the Billing Period Alignment field.
- For non-prepaid recurring charges:
- If Billing Day is set to Term Start Day, Billing Period Alignment must be Align to Term Start.
- If Billing Day is set to Term End Day, Billing Period Alignment can be set to other values.