Skip to main content

Price lookup in Attribute-based Pricing

Zuora

Price lookup in Attribute-based Pricing

  1. Last updated
  2. Save as PDF

With the Attribute-based Pricing feature, you can define a price lookup formula on the Product Rate Plan Charge object, which will be used to identify the correct and relevant charge definition based on the context. The price lookup formula is used during order preview to map the lookup attributes from the Account and Subscription objects to the Product Charge Definition object and assign a charge definition to the subscription rate plan charge.

The following graphic shows where to define the lookup formula in the UI. To define the price lookup formula for a product rate plan charge, use the Formula field in the Charge Amount section on the product rate plan charge detail page when you are creating a product rate plan charge.

charge-formula.png

Price lookup formula

The price lookup formula is defined in the following syntax:

lookup("field_name_on_charge_definition" = fieldLookup ("other_object_name", "field_name"))

where:

  • field_name_on_charge_definition is the field on the product charge definition object.
  • other_object_name is another object that can be supported by price lookup.
  • field_name is the field name on another object whose value will be mapped to the charge definition object.

You can define as many field lookups as you want and separate them by commas. For supported lookup fields by the formula, see Supported lookup fields.

When defining the lookup formula, keep the following things in mind to avoid syntax errors:

  • The field name used in the formula must exactly match the API field name.
  • For custom fields, remember to add the suffix __c (two underscores and the letter "c") at the end of the API name.
  • Use straight double quotes ("") to embrace the object and field names.
  • Use a comma and space as separators.
  • Remember to add a space before and after the equal sign (=).

Examples

The following formula defined for a product rate plan charge is a simple example. It indicates the state custom field on the Product Charge Definition object will be used to identify the target charge definition, and its value is mapped from the state field on the account object.

lookup("state__c" = fieldLookup("account", "state__c"))

The following formula is a more complex one. In this example, the market, variant, soldToRegion, termType, termPeriodType, and term fields on the Product Charge Definition object are used to identify the target charge definition. The field values are mapped either from the Account object or from the Subscription object.

lookup("market__c" = fieldLookup("account", "market__c"), "variant__c" = fieldLookup("subscription", "variant__c"), "soldToRegion__c" = fieldLookup("subscription", "soldToRegion__c"), "termType" = fieldLookup("subscription", "termType"), "termPeriodType" = fieldLookup("subscription", "initialTermPeriodType"), "term" = fieldLookup("subscription", "initialTerm"))

Based on the formula, the lookup function will map the lookup attributes from corresponding objects to the attributes for the charge definition to identify the target charge definition.

  • If the lookup function finds only one charge definition that matches all these lookup attributes, this charge definition will be assigned to the subscription rate plan charge.
  • If the lookup function finds no charge definition that matches all the lookup attributes, it returns an error.
  • If more than one charge definition matches the lookup attributes, the lookup function returns an error.

When the matching charge definition is successfully identified, it will be displayed in the subscription that you are creating. As shown in the following graphic of creating a subscription, the CD-00001210 charge definition is identified and applied.

charge-definition-in-sub.png

Price lookup flow

The following diagram explains how price is determined when you subscribe to a product rate plan for your end customer after the Attribute-based Pricing feature is enabled.

ABP_flow.png

The following things happen in sequence in Zuora Billing when you create a subscription for a customer account.

The charge override behavior in Step 5 below is applicable only when an order or order preview is submitted for subscribing to a rate plan.

  1. A subscription product rate plan is created by cloning the original product rate plan charge.
  2. The system checks whether there is any charge override.
    • If yes, the charge override is applied to the subscription product rate plan.
    • If no, skip to the next step.
  3. The system checks whether a price lookup formula is defined for the product rate plan charge for evaluation.
    • If yes, proceed to the next step.
    • If no, skip to Step 6 to finalize the subscription rate plan charge.
  4. The system collects all required information to evaluate the price lookup formula and identify the target product charge definition. 
    • If the target product charge definition is identified, proceed to the next step. 
    • If no target product charge definition can be identified or any error occurs, the whole process terminates with errors.
  5. Based on the following conditions, the system evaluates whether values provided in charge override in an order or order preview should be applied to the subscription rate plan charge.

    Condition 1

    Whether the attribute value is overridden by the target charge definition

    Condition 2

    Whether the attribute is present in the order charge override

    		 Evaluation result
    No Doesn’t matter Does not apply changes
    Yes Yes Does not apply changes 
    （It’s because order charge override has higher priority.)
    Yes No Apply changes
  6. The subscription product rate plan charge is finalized.

Supported lookup objects and fields

The following table lists the objects and fields you can use in the price lookup formula when you are creating a product rate plan charge. 

  • The fields on the Product Charge Definition object are to be used before the equal sign in the formula.
  • The fields on other supported objects are to be used after the equal sign in the formula.
Object Supported fields for price lookup
Product Charge Definition
  • billingCycleType
  • listPriceBase
  • specificBillingPeriod
  • specificListPriceBase
  • termType
  • taxable
  • taxModeOption
  • termPeriodType
  • term
  • tiers
  • Indexed custom fields on the Product Charge Definition object
Account
  • accountNumber
  • currency
  • Indexed custom fields on the Account object
Subscription
  • autoRenew
  • customerAcceptanceDate
  • contractEffectiveDate
  • currentTerm
  • currentTermPeriodType
  • initialTerm
  • initialTermPeriodType
  • renewalSetting
  • renewalTerm
  • renewalTermPeriodType
  • serviceActivationDate
  • subscriptionEndDate
  • subscriptionStartDate
  • termEndDate
  • termStartDate
  • termType
  • Indexed custom fields on the Subscription object