Skip to main content

Add prepayment product to subscription

Zuora

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.
      If you use the “CRUD: Create a product rate plan charge” REST API or the “Create ()” SOAP API to create recurring prepayment charges, make sure to set the BillCycleType field to TermStartDay and the BillingPeriodAlignment field to AlignToTermStart in the request body.
    • 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.
      If you use the “CRUD: Create a product rate plan charge” REST API or the “Create ()” SOAP API to create recurring prepayment charges, make sure to set the BillCycleType field to TermEndDay and the BillingPeriodAlignment field to AlignToTermEnd in the request body.

    The following behaviors of the recurring prepayment charges added to subscriptions are to be noted:

    1. The Start Date of the newly added fund is the Effective Date of the charge.
    2. 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.
    3. Recurring prepayment charges cannot be added to a shrunk subscription term.
  • 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
  • Charge name: One-time Top-up
  • Charge type: One-time
  • Charge model: Flat Fee
  • List price: $3
  • Prepaid UOM: Million calls
  • Prepaid units: 1
  • Validity period: Month
  • Charge name: API Calls Drawdown
  • Charge type: Usage
  • Charge model: Per unit
  • List price: $5
  • UOM: Million calls

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.

Add onetime product.png

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. 

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:

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.