Skip to main content

Create prepayment charge

Zuora

Create prepayment charge

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.

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

Complete the following steps to create the Monthly Plan charge:

  1. Create a product in the product catalog.
  2. Add two rate plans for the product.
  3. Create a recurring charge within one rate plan by completing the following steps:
    1. Under the Recurring charges/Period section, click +add new.
    2. Specify the following fields for the charge:
      • Charge name: Monthly Plan
      • Charge model: Flat Fee Pricing
      • List price: 20 USD/Month
      • Charge function: Prepayment
      • Commitment Type: Unit
        Note: To create a payment charge based on currency, select the Commitment Type as Currency.
  4. Switch on the Prepayment toggle. Complete the following fields:
    • Prepayment UOM: Million calls
    • Prepayment Units: 10
    • Validity Period: Month
    • Credit Option: Time Based
    • Prepayment Total Units: 10 Million calls/Month (automatically calculated)Create prepayment charge.png
  5. Complete the fields in the Timing and Frequency of Charge section as applicable. See product rate plan charge for more information.

  6. Click Save. This charge will have a Prepaid icon Prepaid charge icon.png next to its name in the rate plan.

  • Create a one-time top-up charge within the other rate plan by completing the following steps:

    1. Under the One-time Charges section, click +add new.

    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
      • Credit Option: Time Based
      • 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:  

Available options are Standard, Prepayment, and Commitment True-up. Select Prepayment here.

UI Label Description Note
Charge Function Function of the charge.  
Commitment Type Type of the prepayment charge. Available options are Unit and Currency.
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
Credit Option The way to calculate credit. Options: 
  • Time Based
  • Consumption Based
  • Full Credit
See Credit option.
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. 

CreditOption string(enum) The way to calculate credit. One of the following values ( Default to TimeBased if no value is specified):
  • TimeBased 
  • ConsumptionBased
  • FullCreditBack

See Credit Option 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

The validity period is the period in which prepayment units are valid to use. Note the following things when setting the validity period for a prepayment charge.

1. Validity period should be evenly distributed over the subscription term with non-standard period subscriptions being an exception. 

validity period and sub term.png

2. Updating a prepayment product 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

Credit Option

Credit Option allows you to choose how to credit back when a prepayment charge is removed, canceled, or shortened. The following options are provided:

  • Time Based: Issue credit based on time proration, which is the normal approach and default behavior. 
  • Consumption Based: Issue credit based on the prepayment balance.
  • Full Credit: Issue the full credit.

Here is an example to explain the difference.

You offer the following prepayment charge: 

  • Charge model: Per unit
  • List price: $1
  • Prepayment UOM: Each
  • Prepayment Units: 120
  • Validity period: Annual
  • Prepayment Total Units: 120 / Year
  • Billing Period: Year

Your customer subscribed to the prepayment charge through a 12-month subscription from 2022/1/1 to 2022/12/31. You run a bill run on 1/1 and collected $120 from your customer. On 2022/7/1, this customer decides to remove this prepayment charge from the subscription. As of 2022/7/1, this customer has consumed 90 prepayment units, reducing the prepayment balance to 30 units for the annual validity period. 

Credit-option.png

  • If you choose Time Based credit option, your customer would receive a $60.49 (183 days / 365 days * $120) credit for the period from 2022/7/1 to 2022/12/31 in the next bill run. 
  • If you choose Consumption Based credit option, your customer would receive a $30 (30 units * $1) credit for the period from 2022/7/1 to 2022/12/31 in the next bill run.
  • If you choose Full Credit credit option, your customer would receive a $120 (120 units * $1) credit for the period from 2022/7/1 to 2022/12/31 in the next bill run.

Note that the following behaviors about the drawdown usage records after prepayment charges are removed, canceled, or shortened.

  • Time Based charges: All the drawdown usage records from the effective date of removal, cancelation, or shrinking the term to the end date of the prepayment charge will be reversed during bill runs. The reversed drawdown usage records are in Pending status. If other funds are available in the same validity period and if the start dates of the pending usage records are within one of the funds, the pending usage records will be drawn down to the funds again. If no available funds exist, the usage records will be billed as regular usage charges in the bill runs.
  • Full Credit charges: All the drawdown usage records in the current or future validity periods will be reversed during bill runs. The reversed drawdown usage records are in Pending status. If other funds are available in the same validity period and if the start dates of the pending usage records are within one of the funds, the pending usage records will be drawn down to the funds again. If no available funds exist, the usage records will be billed as regular usage charges in the bill runs.

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.