Skip to main content

Create drawdown charge


Create drawdown charge

After creating a prepayment charge, you need to create a drawdown charge, which doesn't need to be in the same product rate plan, to track how your customers consume the units they have prepaid. 

You can create a drawdown charge through the Zuora UI, REST API, or SOAP API. Its charge type needs to be usage. Its charge model cannot be flat-fee.

Use the Zuora UI

Suppose your software company has created the following prepayment charges:

  • Monthly Plan: $20, 10 million API calls per month
  • One-time Top-up: $3, 1 million API calls

Now you can create a drawdown charge to track usage consumption and charge any usage exceeding the total prepaid units at $5 per million calls. 

Complete the following steps to create the drawdown charge:

Create drawdown charge-Monthly-result.png

After creating the prepayment and drawdown charges, you can start selling your product to customers by creating subscriptions through Orders.

  1. Navigate to the product rate plan with the Monthly Plan prepayment charge.
  2. Under the Usage Charges/UOM section, click +add new.
  3. Specify the following fields:
    • Charge name: API Calls Drawdown
    • Charge model: Per unit  
    • List price: 5
    • UOM ( the drawdown usage charge's UOM, also referred to as Usage UOM): Million calls 
    • Select the Drawdown checkbox
    • Drawdown UOM ( the prepayment balance charge's UOM): Million calls
    • Drawdown Rate: 1

    If you have more than one UOM, you can use different Usage UOM and Drawdown UOM, which are connected through a drawdown rate. If the two UOMs are of the same unit, you must set the drawdown rate as 1; if the two UOMs are of different units, you need to set a drawdown rate as the conversion ratio. For more information, see UOM conversion. The Drawdown Exchange value is automatically calculated by the system showing the conversion between Usage UOM and Drawdown UOM.

  4.  Complete the fields in the Timing and Frequency of Charge section as applicable. See product rate plan charge for more information.
  5.  Click Save. This charge will have a Drawdown icon Drawdown charge icon.png next to its name in the rate plan.


You can use the CRUD: Create a product rate plan charge operation to create a drawdown charge. Note that WSDL version 114+ is required for the X-Zuora-WSDL-Version header parameter. Determine the following mandatory fields specific to a drawdown charge:

Field name Type Description
IsPrepaid boolean Set to true for drawdown charge. 
PrepaidOperationType string(enum) The type of this charge. Values: topup or drawdown.  Set to drawdown for drawdown charge.
DrawdownRate decimal

Conversion rate between Usage UOM and Drawdown UOM. 


  • Must be a positive number (>0).
  • Must be 1 when Usage UOM and Drawdown UOM are the same. 
  • If both DrawdownRate and DrawdownUom are empty, the system will set default values respectively:
    • DrawdownRate: 1
    • DrawdownUom: Same as the Usage UOM of this drawdown charge. 
  • DrawdownRate and DrawdownUom need to have values or be empty at the same time. 
DrawdownUom string Unit of measurement for this drawdown charge, should be the same as the PrepaidUOM configured in its paired prepayment charge

Sample REST API request: Create a monthly usage drawdown charge.

Request POST    /v1/object/product-rate-plan-charge
Request body
"AccountingCode":"Accounts Receivable",
"ChargeModel": "Per Unit Pricing",
"BillingPeriod": "Month",
"Name": "Drawdown",
       "Active": true,
"UOM":"Million calls",

//Fields related to drawdown charge
"IsPrepaid" : true,
"PrepaidOperationType": "drawdown",
"DrawdownUom" : "Million calls",
"DrawdownRate": 1,


You can also use SOAP API to create a drawdown charge. Note that WSDL version 114+ is required for the Prepaid with Drawdown feature.  

Sample SOAP API request: Create monthly usage drawdown charge.

 <ns1:zObjects xsi:type="ns2:ProductRatePlanCharge">
  <ns2:AccountingCode>Accounts Receivable</ns2:AccountingCode>
  <ns2:ChargeModel>Per Unit Pricing</ns2:ChargeModel>
   <ns1:ProductRatePlanChargeTier xsi:type="ns2:ProductRatePlanChargeTier">
  <ns2:UOM>Million calls</ns2:UOM>
//Fields related to drawdown charge
  <ns2:DrawdownUom>Million calls</ns2:DrawdownUom>

See ProductRatePlanCharge for information on the object and its fields. 

UOM conversion

You can configure a drawdown charge where Usage UOM and Drawdown UOM are different and connected through a Drawdown Rate, like the exchange rate between two currencies. Note that the Drawdown UOM, Usage UOM, and Drawdown Rate need to have the same number of decimal places.

Suppose a gaming company has two UOMs: Hour and Point. It can configure the following prepayment charges and drawdown charges where customers purchase Points to get gaming time measured in Hours.

  • Prepayment charge: $10/one-time, 100 Points, Prepaid UOM (Point)
  • Drawdown charge: Drawdown UOM (Point), Usage UOM (Hour), Drawdown Exchange: 2 Points = 1 Hour

When you upload 10 hours of usage for a customer, it will be converted to 20 Points (10 * 2). The customer’s remaining balance will be 80 Points (100-20).  

In the case where a drawdown rate is a float number (a number that has decimal places, for example, 2.5), the system keeps the most accurate calculation when doing the conversion. 

For example, assume the following scenario:

  • Drawdown Exchange is 2.5 Points = 1 Hour
  • Your customer’s remaining prepaid balance is 1 Point

You upload 0.1 Hour of usage for this customer -> The usage is converted to 0.25 Point (0.1 * 2.5) -> This customer’s prepaid balance is drawn down to 0.75 Point (1.00 - 0.25).

Notes and limitations

  • When a subscription contains a prepayment charge, it should also contain a drawdown charge to track usage consumption, and the Drawdown UOM should be the same as the Prepayment UOM.  
  • Flat-fee charge model is not supported on drawdown charges.
  • When a drawdown charge is configured in the tiered pricing charge model, the Tier 1 price is effective only after the prepaid units are used up. For example, if you set Tier 1 price = 0 to give your customers some free units, they will enjoy the zero price only after their prepaid units are drawn down to 0. 
  • You can update both the pending and processed drawdown usage records before their associated drawdown usages are billed. After the charges are billed, you cannot edit the drawdown usage records anymore.

Note the following behaviors of the drawdown usage charge status: 

  • After uploading a drawdown usage record to Zuora, if the usage record is fully drawn down by the prepayment balance, the usage record will turn to processed*. After invoices being generated, the usage record in processed* status will be changed to processed status.
  • If the usage record is not fully drawn down by the prepayment balance, the record will stay in pending. After the drawdown charges are billed, the status of the usage will turn to processed.
  • The Pre-Rated Per Unit Pricing and Pre-Rated Pricing charge models are unavailable on drawdown charges.