Skip to main content

Apply charge definition lookup to subscriptions

Zuora

Apply charge definition lookup to subscriptions

Charge definition lookup is supported in API and UI. This article demonstrates how to apply charge definition lookup to subscriptions through UI. If you subscribe to the product rate plan through API as usual after defining the price lookup formula, the charge definition lookup is automatically processed. For more information, see Overview of Attribute-based Pricing.

The charge definition lookup is only available when the Attribute-based Pricing feature is enabled in the Orders Harmonization and Orders tenants.

By supporting this function, you can view the actual price of a charge based on the matching charge definition when subscribing this charge to a subscription through the Create Subscription or Add Product order action.

A price lookup formula must be created for a product rate plan charge in the product catalog to enable the charge definition lookup. The charge definitions are looked up based on attributes or custom fields defined in the formula. A successful charge definition lookup is based on the following rule: the values of the attributes or custom fields in the subscription and account during the Create Subscription or Add Product order action exactly match those values in charge definitions.

In this article, only one subscription custom field is used as a simple example to demonstrate how looking up charge definition works. For complex use cases using multiple fields for lookup, see Price lookup in Attribute-based Pricing.

To enable charge definition lookup, perform the following steps:

  1. Add a custom field on the subscription object. For more information, see Manage custom fields.

    Custom field setting for ABP.png

    In this example, you created the soldToRegion custom field and the corresponding API Name value soldToRegion__c for looking up charge definitions during the order action. You configured two values InRegion and Overseas for this custom field.

  2. Enable the Attribute-based Pricing feature.
  3. For the charge, create the charge definitions and price lookup formula in the Charge Amount section of the charge in the product catalog.

    In this example, the following two charge definitions are defined for the charge.

     charge definiations.png

    The formula is as follows:

    lookup("soldToRegion__c" = fieldLookup("subscription", "soldToRegion__c"))
    

    To avoid lookup failures caused by formula syntax errors, you are recommended to copy our formula example and replace soldToRegion__c with your custom field API Name. For more information, see Price lookup in Attribute-based Pricing.

  4. Perform Create Subscription or Add Product order action. In this example, the custom field value InRegion is used. 

    • For the Create Subscription order action, specify this value before adding the product rate plan charge. Specify this value in the soldToRegion custom field in the Custom Fields section on the Create a New Subscription page.

    • For the Add Product order action, update this value in the existing subscription before performing the order action. Update this value in the Additional Information section on the subscription details page.

  5. When you add a product rate plan during the order action, you can identify whether the lookup succeeds or fails.
    • The following picture indicates a successful lookup. Since you specified the custom field value in this subscription as InRegion and the charge definition CD-00001210 has the same custom field value, this charge definition is successfully looked up based on the error-free formula. In this case, you can perform one of the following steps:

      ABP with formula in orders UI.png

      • Update the subscription rate plan charge price in the Price field
      • Click the link of the product charge definition number to view and update the product charge definition. If you update the List price field in the product charge definition, the subscription rate plan charge price in the Price field will not be synchronized during the order action. 
      • Click the attribute list icon to check based on which custom field in the formula the lookup is processed. In this example, "subscription", "#soldToRegion__c"is displayed in the attribute list.
    • The following picture indicates a failed lookup. Identify and resolve the issue by yourself or contact your product catalog manager.  

      CD lookkup failed.png

  6. Review your order and activate the order. 

Identify and resolve the issue by yourself

Many reasons can cause a failed lookup. Perform one of the following steps to identify and resolve your failure reason:

  • Formula syntax errors: open the charge in the product catalog, correct your formula, and perform the order action again. For more information, see Price lookup in Attribute-based Pricing.

  • The custom field value InRegion in the subscription is not specified: perform the order action again and make sure this value is specified. 

  • The custom field value InRegion in the subscription is specified. However, none of the charge definitions has this value specified: open another web session to check charge definitions of the charges, and update any charge definition to have the custom field value InRegion. Click Re-Lookup to reinitiate the lookup process.

  • The custom field value InRegion in the subscription is specified. However, more than one charge definition has this value: update charge definitions to make only one charge definition left with this value.