Skip to main content

Create subscriptions containing charges with annual prices and specific-month billing periods through the REST API

Zuora

Create subscriptions containing charges with annual prices and specific-month billing periods through the REST API

With the Annual List Price feature, you can sell products and services with an annual list price, but bill your customers through contract negotiations according to a non-annual billing period through the REST API, for example, four months. The total billed amount for the annual service across multiple invoices equals the sum of the annual selling price.

Assume that you expect to define an annual list price of $21,500 for a recurring service, and bill your end customers every four months. You expect to send three invoices for the first year:

  • First invoice with the amount of $7166.67
  • Second invoice with the amount of $7166.67
  • Third invoice with the amount of $7166.66

To achieve this goal through the REST API, complete the following tasks:

  1. Use the CRUD: Create a product rate plan charge operation to create a product rate plan charge with an annual list price of $24,000.
  2. Use the Create an order operation to create a subscription to the charge while updating the list price and billing period.

Create product rate plan charges with annual list prices

You have first to use the CRUD: Create a product rate plan charge operation to define a recurring charge with an annual list price of $24,000 and an annual billing period. The list price can be overwritten when selling the charge to your end customers through contract negotiations.

The following information is a sample API request that creates such a product rate plan charge with the annual billing period.

{
   "AccountingCode":"Deferred Service Revenue",
   "BillCycleType":"DefaultFromCustomer",
   "BillingPeriod":"Annual",
   "ChargeModel":"Flat Fee Pricing",
   "ChargeType":"Recurring",
   "Name":"Recurring flat fee",
   "ProductRatePlanChargeTierData":{
      "ProductRatePlanChargeTier":[
         {
            "Currency":"USD",
            "Price":24000
         }
      ]
   },
   "ProductRatePlanId":"8ad096ca860be7370186112e0b9f0c5e",
   "ListPriceBase":"Per Year",
   "DeferredRevenueAccount":"Deferred Service Revenue",
   "RecognizedRevenueAccount":"Accounts Receivable",
   "TriggerEvent":"ContractEffective",
   "UOM":"each",
   "UseDiscountSpecificAccountingCode":false
}

Create subscriptions containing charges with annual prices and specific-month billing periods

When selling the service, your end customer selects a non-annual billing period of four months instead and agrees on an annual net sales price of $21,500 through contract negotiations.

The following information lists basic information about the expected subscription.

Subscription number Start date Term Charge number Net sales price Billing period

S1

01/01/2021

12

C1

$21,500 per year

Specific months: 4 months

During order creation, you can use the Create an order operation to create a subscription while overwriting the annual list price and billing period. The following information is a sample API request that creates such a subscription through the CreateSubscription order action.

{
   "orderDate":"2023-01-01",
   "existingAccountNumber":"A00000528",
   "subscriptions":[
      {
         "orderActions":[
            {
               "type":"CreateSubscription",
               "triggerDates":[
                  {
                     "name":"ContractEffective",
                     "triggerDate":"2023-01-01"
                  }
               ],
               "createSubscription":{
                  "terms":{
                     "autoRenew":true,
                     "initialTerm":{
                        "period":"12",
                        "periodType":"Month",
                        "termType":"TERMED"
                     },
                     "renewalSetting":"RENEW_WITH_SPECIFIC_TERM",
                     "renewalTerms":[
                        {
                           "period":"12",
                           "periodType":"Month"
                        }
                     ]
                  },
                  "subscribeToRatePlans":[
                     {
                        "productRatePlanId":"8ad0887184099dd101841289f34453cc",
                        "uniqueToken":"ss2",
                        "chargeOverrides":[
                           {
                              "productRatePlanChargeId":"8ad0887e84f5b7600184f63259327d82",
                              "billing":{
                                 "billCycleType":"ChargeTriggerDay",
                                 "billingPeriod":"Specific_Months",
                                 "specificBillingPeriod":4,
                                 "billingPeriodAlignment":"AlignToCharge"
                              },
                              "pricing":{
                                 "recurringFlatFee":{
                                    "listPrice":21500,
                                    "listPriceBase":"Per_Year"
                                 }
                              }
                           }
                        ]
                     }
                  ]
               }
            }
         ]
      }
   ]
}

Because the billing period is four months, one invoice is generated on the first day of January, May, and September respectively for the subscription. The following table lists basic information about the three expected invoices generated for the preceding subscription.

Invoice number Invoice date Service period Invoice amount
 INV001

01/01/2023

01/01/2023 to 04/30/2023

7,166.67

 INV002

05/01/2023

05/01/2023 to 08/31/2023

7,166.67

 INV003

09/01/2023

09/01/2023 to 12/31/2023

7,166.66

 Total - -

21,500.00

The total annual amount is evenly divided across three invoices. Meanwhile, the total billed amount across these invoices equals the sum of the annual selling price for each individual charge.