Skip to main content

Adding Dynamic Pricing enabled products to subscriptions

Zuora

Adding Dynamic Pricing enabled products to subscriptions

  1. Last updated
  2. Save as PDF

Overview

This tutorial demonstrates how to add a dynamic pricing enabled product to a subscription by creating an order.

In this tutorial, you will set the following dates to today's date:

  • The date when the order is signed

  • The contract effective date of the product addition

  • The service activation date of the product addition

  • The customer acceptance date of the product addition

The following features must not be enabled: Single Version Subscription, Pending Subscription Processing.

Pre-configuration

Create a rate plan,  Demo Rate Plan 1 with one recurring per Unit charge, License Fee. Define the following pricing attribute for License Fee.

Pricing Attribute Name Description Category Mapping Relationship / Data Type

SubscriptionRenewalTerm

The term length for subscription renewal. 

Mapped

{                        

 "field": "RenewalTerm",                                     "object": "subscription"                     

}

AccountType

The account type. 

Mapped

{                     

 "field": "Type__c",                                           "object": "account"

}

SubscriptionRatePlanClass

The class of the subscription rate plan.

Mapped

{                  

 "field": "RateClass__c",                                   "object": "rateplan"

}

Site_Size

The size of the site. 

External

Integer

EffectiveDate

The effective date of the price. 

Default

Datetime

Configure the License Fee dynamic pricing decision table on the Product Catalog UI as follows:License Fees.png

In the examples below, we assume the parent Account’s custom field, Type__c = “VIP”

Add a Dynamic Pricing enabled product rate plan using the Zuora UI

When subscribing to a rate plan, Demo Rate Plan 1, some extra steps are added to lookup the list price based on the pricing attribute values:

  1. Click Add Product after selecting Demo Rate Plan 1. The user will be prompted to enter values for external attributes and attributes mapped to Subscription Rate Plan object fields to lookup the list price from product catalog. 

      Add-1.png

  • For the attributes mapped to other Zuora objects (account, account.billto, account.soldto, payment method, subscription), their values are retrieved from those objects automatically and remain read-only during the order creation process. You must configure the values properly before creating an order. 

  • The effective date is automatically set to the order date. You can override this value to retrieve a list price that is effective from another specified date.

  1. Enter the pricing attribute values and save the changes. 

     Add-2.jpg     

  1. The Products and Charges page is displayed. The list price from the product catalog is displayed in the Original List Price column. Based on the pricing attribute values provided in the previous step, it matches the list price = $9 entry in the decision table. 

               Add-3.jpg     

The original list price is a read-only reference to determine the sales price.

  1. (Optional) For individual charges, you can update the values of external attributes and attributes mapped to the Subscription Rate Plan field by selecting the pencil (Pencil icon.png) icon next to the original list price. After you save the updated attribute values, Zuora refreshes the list price from the product catalog. If any charge uses the Subscription Rate Plan object field as the pricing attribute, updating one charge’s pricing attribute could refresh the list price and sales price of all charges under the same rate plan.      

     Additional Price Details.png

 If any charge uses the Subscription Rate Plan object field as the pricing attribute, updating one charge’s pricing attribute could refresh the list price and sales price of all charges under the same rate plan.

5. Click Review Order after configuring the correct price for the rate plans. In the Review Order page for the order actions that include Dynamic Pricing charges, you are not allowed to edit them to change the pricing attributes or other information again.

Add a dynamic pricing enabled product rate plan using the REST API

You can subscribe to rate plans with dynamic pricing enabled charges via REST API. 

Use the "Create an order" operation to create an order under an existing account:

  1. When subscribing to a rate plan with dynamic pricing charges, you can enter attribute values via the pricingAttributes tag at charge level to lookup list price from product catalog in the following order actions. 
  2. The attribute values will be used to lookup the charge’s list price and set it as the charge’s sales price if it is not specified.
  3. For the attributes mapped to a Zuora standard object, Zuora retrieves the attribute values from the existing Zuora objects automatically. For more information on understanding pricing attributes mapped to Zuora object fields, refer to this section.
  4. We recommend you not to include such attributes in the pricingAttributes tag in the Order payload. If you do include such attributes, in order to ensure data integrity, Zuora will validate it against the latest value in the Zuora objects and return an error if there is any discrepancy.
  5. If the effective date is not provided by the user via pricingAttributes tag, its value is set to the order date automatically.

There are some examples of Order API Request Payload.

Create New Subscriptions

To add a product to a new subscription by creating an order:

  1. Determine the values of the following variables and configure the dynamic pricing enabled charge in the product catalog accordingly:
    Variable Description
    $AccountNum The number of the account that will own the order and the  subscription. For example, A00000001.
    $productRatePlanId The ID of the product rate plan to add to the subscription. For example, edcad42fa5697665a4d767394f590000.
    $productRatePlanChargeId The ID of the product rate plan charge to use when adding the product rate plan. For example, 41137e9965e2445fbb57dae2daab7580.
    $Today Today's date. For example, 2025-06-16.
    $Site_Size The size of the site. For example, 33.

  2. Refer to the example payload to create a new order.  In this example, the user sets the value of pricing attributes: Site_Size and EffectiveDate directly in pricingAttributes. For the pricing attribute Subscription_RatePlan_Class that is mapped to the custom field RateClass__c, the value is set in customFields and automatically used by Zuora during list price lookup.

    Request POST /v1/orders/
    Request Body 
    
{
   "orderDate": "$Today",
   "existingAccountNumber": "$AccountNum",
   "subscriptions": [
       {
           "orderActions": [
               {
                   "type": "CreateSubscription",
                   "triggerDates": [
                       {
                           "name": "ContractEffective",
                           "triggerDate": "$Today"
                       },
                       {
                           "name": "ServiceActivation",
                           "triggerDate": "$Today"
                       },
                       {
                           "name": "CustomerAcceptance",
                           "triggerDate": "$Today"
                       }
                   ],
                   "createSubscription": {
                       "subscriptionOwnerAccountNumber": "$AccountNum",
                       "terms": {
                           "initialTerm": {
                               "startDate":"$Today",
                               "period": 12,
                               "periodType": "Month",
                               "termType": "TERMED"
                           },
                           "renewalTerms": [
                               {
                                   "period": 12,
                                   "periodType": "Month"
                               }
                           ],
                           "renewalSetting": "RENEW_WITH_SPECIFIC_TERM",
                           "autoRenew": true
                       },
                       "subscribeToRatePlans": [
                       {
                           "productRatePlanId":"$productRatePlanId",
                           "customFields": {
                               "RateClass__c": "High"
                           },
                           "chargeOverrides": [
                             {
                               
                          "productRatePlanChargeId":"$productRatePlanChargeId"                                               
                       "pricingAttributes": {
                                    "Site_Size": 33,
                                    "EffectiveDate": "2025-06-16"
                          }
                        }
                      ]
                    }
                  ]
                }      
              }
            ]
          }
        ]
      }

  3. After the subscription is created successfully, you can retrieve the price and pricingAttributes value of the charge via the GET subscription end point. This is an example response of pricingAttributes of a charge created from "$productRatePlanChargeId" in the previous step.

    "price": 12.000000000,

    "pricingAttributes": {

                           "Site_Size": 33,

                           "Account_Type": "VIP",

                           "EffectiveDate": "2025-06-16T00:00:00+08:00",

                           "Subscription_Renewal_Term": 12,

                           "Subscription_RatePlan_Class": "High"

                       }

    pricingAttributes includes all the pricing attribute values, including both external attributes and attributes mapped to the Zuora object fields.

  1.  Determine the values of the following variables and configure the dynamic pricing enabled charge in the product catalog accordingly: 
    Variable Description
    $AccountNum The number of the account that will own the order and the  subscription. For example, A00000001.
    $productRatePlanId The ID of the product rate plan to add to the subscription. For example, edcad42fa5697665a4d767394f590000.
    $productRatePlanChargeId The ID of the product rate plan charge to use when adding the product rate plan. For example, 41137e9965e2445fbb57dae2daab7580.
    $subscriptionNumber

    The number of the subscription that will own the rate plans. For example, A-S0000001.
    $Today Today's date. For example, 2025-06-20.

  2. Refer to the example payload to create a new order. In this example, the user sets the value of pricing attributes: Site_Size and EffectiveDate directly in pricingAttributes. For the pricing attribute Subscription_RatePlan_Class that is mapped to the custom field RateClass__c, its value is set in customFields and automatically used by Zuora during list price lookup.

     Assuming the subscription’s renewal term length = 12 months.

    Request POST /v1/orders/
    Request Body 
    
{
"orderDate": "$Today",
"existingAccountNumber": "$AccountNum",
"subscriptions": [
   {
     "subscriptionNumber": "$subscriptionNumber",
     "orderActions": [
       {
         "addProduct": {
           "productRatePlanId": "$productRatePlanId",
           "customFields": {
             "Channel__c": "Reseller",
             "RateClass__c": "Low"
        },
           "chargeOverrides": [
             {
               "productRatePlanChargeId": "$productRatePlanChargeId",
               "pricingAttributes": {
                   "EffectiveDate": "2025-06-20",
                   "Site_Size": 7
              }
           }
          ]
         },
         "triggerDates": [
           {
             "name": "ContractEffective",
             "triggerDate": "$Today"
           },
           {
             "name": "CustomerAcceptance",
             "triggerDate": "$Today"
           },
           {
             "name": "ServiceActivation",
             "triggerDate": "$Today"
           }
         ],
         "type": "AddProduct"
       }
     ]
   }
 ]
       }

  3. After the rate plan is subscribed successfully, you can retrieve the price and pricingAttributes value of the charge via the GET subscription end point. This is an example response of pricingAttributes of the charge created from "$productRatePlanChargeId" in the previous step.

    "price": 9.000000000,

    "pricingAttributes": {

                           "Site_Size": 7,

                           "Account_Type": "VIP",

                           "EffectiveDate": "2025-06-20T00:00:00+08:00",

                           "Subscription_Renewal_Term": 12,

                           "Subscription_RatePlan_Class": "Low"

                           }

     pricingAttributes includes all the pricing attribute values including both external attributes and attributes mapped to Zuora object fields.

To replace a product rate plan by creating an order:

  1. Determine the values of the following variables and configure the dynamic pricing enabled charge in the product catalog accordingly: 

    Variable Description
    $AccountNum The number of the account that will own the order and the  subscription. For example, A00000001.
    $productRatePlanId The ID of the product rate plan to add to the subscription. For example, 8a90876c84ae5ef70184bef2c94c7b2c.
    $productRatePlanChargeId The ID of the product rate plan charge to use when adding the product rate plan. For example, 41137e9965e2445fbb57dae2daab7580.
    $subscriptionNumber

    The number of the subscription that will own the rate plans. For example, A-S0000001.
    $subscriptionRatePlanId The ID of the subscription rate plan. For example, 8a90876c84ae5ef70184c2080c307343.
    $Today Today's date. For example, 2025-08-01.

  2. Refer to the example payload to create a new order. In this example, the user sets the value of pricing attributes: Site_Size and EffectiveDate directly in pricingAttributes. For pricing attribute Subscription_RatePlan_Class, that is mapped to the custom field RateClass__c, its value is set in customFields and automatically used by Zuora during list price lookup.

    Assuming that the subscription’s renewal term length = 12 months. 

    Request POST /v1/orders/
    Request Body 
    
{
   "existingAccountNumber": "$AccountNum",
   "orderDate": "$Today",
   "subscriptions": [
     {
       "subscriptionNumber": "$subscriptionNumber",
       "orderActions":[
         {
           "type":"ChangePlan",
           "triggerDates": [
             {
               "name": "ContractEffective",
               "triggerDate": "$Today"
             },
             {
               "name": "ServiceActivation",
               "triggerDate": "$Today"
              },
              {
               "name": "CustomerAcceptance",
               "triggerDate": "$Today"
              }
           ],
           "changePlan": {               
               "ratePlanId": "$subscriptionRatePlanId",
               "newProductRatePlan": {
                   "productRatePlanId":"$productRatePlanId",
                   "customFields": {
                       "Channel__c": "Reseller",
                       "RateClass__c": "Low"
                     },
                   "chargeOverrides": [
                     {
                       "productRatePlanChargeId": "$productRatePlanChargeId",
                       "pricingAttributes": 
                         {
                           "Site_Size": 20
                         }
                      }
                   ]
                } 
             }
          }
       ]
    }
  ]
}