Skip to main content

Add prepayment product to subscription


Add prepayment product to subscription

The Prepaid with Drawdown feature is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at Zuora Global Support.


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. 

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. 


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",
                 "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.
  • Adding a recurring prepayment charge can only happen at the beginning of a validity period. For example, a prepayment charge in the original 12-month subscription has 4 quarterly validity periods: 
    • 01/01/2022-03/31/2022
    • 04/01/2022-05/31/2022
    • 06/01/2022-09/30/2022
    • 10/01/2022-12/31/2022

You can only add a new recurring prepayment charge to this subscription on 01/01/2022, 04/01/2022, 06/01/2022, or 10/01/2022. 

  • 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 to use from the charge effective date to the end of the current validity period.