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

Last updated
Save as PDF

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:

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