Create prepayment charge

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)

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

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

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

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

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:

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

{
"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. 

2. Updating a prepayment product must happen on the first day of a validity period.

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

Best practice for billing settings

When configuring a recurring prepayment charge with a list price base, we recommend selecting the validity period as the list price base. This is the most natural way for your customers to understand the pricing for a prepaid service. Also, this configuration triggers the system to automatically set the product price for each of the billing periods so that the total amount across multiple billing periods within a validity period matches your designed pricing. Therefore, when the product price is not divisible by the number of billing periods,  this configuration can help prevent pricing inconsistency and save your effort to manually change the product price. We use the examples below to show you how this works.

Before proceeding with the example, note that the following prerequisite billing settings are required for a prepaid subscription service. This is because prepayment charges cannot be prorated and we must avoid situations where two validity periods are associated with the same billing period. For more information, see Prepaid with Drawdown FAQs.

• The subscription term should equal one or multiple validity periods.
• The validity period should equal one or multiple billing periods.
• The billing day of a prepayment charge should be the Term Start Day or Term End Day.
• The billing period of a prepayment charge should be month-based and not week-based. 

Example 1

Suppose your company provides a prepaid subscription service with a quarterly validity period and a monthly billing period. The charge price is $10 per quarter (the list price base is set to the validity period, as recommended). A customer subscribes to this service for a year. The following diagram shows the subscription term, the validity periods, and the billing periods for this subscription.

As in the preceding diagram, a validity period equals three billing periods, so presumably, the amount due for each billing period on the invoice would be as follows:

10/3 = 3.33 $/month

This amount will cause a problem for product pricing because, according to the subscription, the revenue for a validity period should be $10, but the amount to collect for a quarter will be as follows and not match your desired price. 

3.33 * 3 = 9.99 $

Actually, the system prevents the preceding problem if you select the validity period as the list price base. The system automatically updates the amount due for one of the three months in the validity period to $3.34 to make sure the total amount for a quarter is $10.

Example 2

Setting the list price base as the validity period can also benefit the scenario when you want to change the length of the validity period for a prepaid service. Suppose your company extends the validity period for the preceding prepaid service from 3 months to a year, without changing the list price. Another customer subscribes to this service for a year with a monthly billing period. If you select the validity period as the list price base, the system automatically updates the amount due for each of the 12 billing periods properly to make sure the total amount for a validity period is $10 per year, as you expect. Otherwise, you have to figure out an approach and then manually update the amount due for each billing period.

Credit option

Credit Option allows you to choose how to credit back when a prepayment charge or commitment true-up 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 or commitment true-up charge balance.
• Full Credit: Issue the full credit.

Here is an example to explain the difference. A prepayment charge is used in the example. The logic is the same for a commitment true-up charge.

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. 

• 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 the following behaviors about the drawdown usage records when 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.

The preceding behaviors also apply to a credit commitment charge when the commitment true-up charge is removed, canceled, or shortened.

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

Notes and limitations

• Billing Period for prepayment charges cannot be Week.
• List price base for prepayment charges should not be Week.
• The unit of the subscription term should not be Week.