Skip to main content

Create prepayment charge

Zuora

Create prepayment charge

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.

A prepayment charge allows you to sell prepaid services to customers and collect payment upfront. A typical prepaid service is prepaid cell phone plans, for example, a monthly plan with a list price of $20 that includes 500 minutes of talk time.

You can create a prepayment charge through the Zuora UI, REST API, or SOAP API. Its charge type needs to be one-time or recurring. Its charge model needs to be flat fee or per unit.

Use the Zuora UI

Suppose you run a software company that charges customers by the number of calls to your API. You can create the following prepayment charges to sell your service:

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

Steps:

  1. Create a product in the product catalog.
  2. Add 2 rate plans for the product.

To create the Monthly Plan charge:

1. Within one rate plan created, click +add new under Recurring charges/Period.

2. Complete the following fields:

  • Charge name: Monthly Plan
  • Charge model: Flat Fee Pricing
  • List price: 20 USD/Month

3. Switch on the Prepayment toggle. Complete the following fields:

  • Prepayment UOM: Million calls
  • Prepayment Units: 10
  • Validity Period: Month
  • Prepayment Total Units: 10 Million calls/Month (Automatically calculated)

Create prepayment charge.png

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 Prepaid icon Prepaid charge icon.png next to its name in the rate plan.

 

To create the One-time Top-up charge:  

1. Within the other rate plan created, click +add new under One-time Charges.

2. Complete the following fields:

  • Charge name: One-time Top-up
  • Charge model: Flat Fee Pricing
  • List price: 3 USD

3. Switch on the Prepayment toggle. Complete the following fields:

  • Prepayment UOM: Million calls
  • Prepayment Units: 1
  • Validity Period: Month
  • Prepayment Total Units: 1 Million calls /Month (Automatically calculated)

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 Prepaid icon Prepaid charge icon.png next to its name in the rate plan.

After creating the prepayment charges above, you will see them listed in your product. 

Create prepayment charge - result.png

Below is a summary of the fields specific to a prepayment charge:  

UI Label Description Note
Prepayment UOM Unit of measurement for this prepayment charge. For example, minutes. GB, seat, or token.
Prepayment Units The number of units included in this prepayment charge. Must be positive (>0) and can be decimal (for example, 19.5).
Validity Period The period in which the prepaid units are valid to use. Options: 
  • Subscription Term
  • Annual
  • Semi-Annual
  • Quarter
  • Month
See Validity period
Prepayment Total Units The total amount of units your customers can use when they subscribe to this prepayment charge. Automatically calculated by the system with this formula: Prepaid Quantity * Default Quantity.

For the flat fee charge model, the Default Quantity is 1. 

After creating the product and the prepayment charges, you can create drawdown charges in the rate plans to match the prepayment charges.

Use REST API

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

Field name Type Description
IsPrepaid boolean Set to true for prepayment charge. 
PrepaidOperationType string(enum) The type of this charge. Values: topup or drawdown.  Set to topup for prepayment charge.
PrepaidQuantity decimal The number of units included in this prepayment charge. Must be positive (>0).  
PrepaidUom string Unit of measurement for this prepayment charge.
ValidityPeriodType string(enum) The period in which those prepayment units are valid to use. One of the following values:
  • Subscription_Term 
  • Annual 
  • Semi_Annual  
  • Quarter 
  • Month 

See Validity period for more information. 

Sample REST API request: Create a monthly recurring prepayment charge.

Request POST    /v1/object/product-rate-plan-charge
Request body
{
"Name": "Monthly Plan",
"ChargeModel": "Flat Fee Pricing",
"BillingPeriod": "Month",
"BillCycleType":"DefaultFromCustomer",
"ChargeType":"Recurring",
"ProductRatePlanChargeTierData":
{
   "ProductRatePlanChargeTier":
   [
       {
       "Active": true,
       "Currency":"USD",
       "Price":"20"
       }
   ]
},
"ProductRatePlanId":"2c92c0f87a85be74017a88ee747862a8",
"TriggerEvent":"ContractEffective",
"BillingPeriodAlignment":"AlignToCharge",
"AccountingCode":"Accounts Receivable",

//Fields related to prepayment charge
"IsPrepaid":true,
"PrepaidOperationType":"topup",
"PrepaidQuantity":"1",
"PrepaidUom”:"Million calls",
"ValidityPeriodType”:"MONTH"
}

Use SOAP API

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

Sample SOAP API request: Create a monthly recurring prepayment charge.

<ns1:create>
 <ns1:zObjects xsi:type="ns2:ProductRatePlanCharge">
  <ns2:AccountingCode>Accounts Receivable</ns2:AccountingCode>
  <ns2:BillingPeriod>Month</ns2:BillingPeriod>
  <ns2:BillingPeriodAlignment>AlignToCharge</ns2:BillingPeriodAlignment>
  <ns2:ChargeModel>Flat Fee Pricing</ns2:ChargeModel>
  <ns2:ChargeType>Recurring</ns2:ChargeType>
  <ns2:Name>Monthly Plan</ns2:Name>
  <ns2:ProductRatePlanChargeTierData>
   <ns1:ProductRatePlanChargeTier xsi:type="ns2:ProductRatePlanChargeTier">
    <ns2:Active>true</ns2:Active>
    <ns2:Currency>USD</ns2:Currency>     
    <ns2:Price>20</ns2:Price>
   </ns1:ProductRatePlanChargeTier>
  </ns2:ProductRatePlanChargeTierData>        
  <ns2:ProductRatePlanId>2c92c0f87a85be74017a88ee747862a8</ns2:ProductRatePlanId>
  <ns2:TriggerEvent>ContractEffective</ns2:TriggerEvent>
//Fields related to prepayment charge
           <ns2:IsPrepaid>true</ns2:IsPrepaid>
           <ns2:PrepaidOperationType>topup</ns2:PrepaidOperationType>
           <ns2:PrepaidQuantity>1</ns2:PrepaidQuantity>
           <ns2:PrepaidUom>Million calls</ns2:PrepaidUOM>
           <ns2:ValidityPeriodType>MONTH</ns2:ValidityPeriodType>
 </ns1:zObjects>
</ns1:create>

See ProductRatePlanCharge for information on the object and its fields.

Validity period

Note the following things when setting the validity period for a prepayment charge.

1. Validity period must be evenly distributed over the subscription term. 

validity period and sub term.png

2. Order actions like adding a recurring prepayment product, updating a prepayment product, and extending a prepayment subscription must happen on the first day of a validity period.

validity period and order actions.png

3. Validity period must be equal to or multiple times of the billing period of a prepayment charge.

validity period and billing period.png

Notes and limitations

  • Billing Period for prepayment charges cannot be Week.
  • When a prepayment charge is using the Per Unit model, the list price billing period should not be Week.