Skip to main content

Price Formula Reference

Zuora

Price Formula Reference

  1. Last updated
  2. Save as PDF

The Multi-Attribute Pricing charge model is available to all customers. However, to use the Multi-Attribute Pricing charge model for usage charges, you must be a user of Zuora Advanced Billing.

When you create a product rate plan charge with the Multi-Attribute Pricing charge model, you have to specify a price formula in the Price Formula field. 

A price formula can consist of mathematical operations and functions that are combined to calculate the actual price for the charge or usage record (depending on the charge type). Typical mathematical operations ( +, -, /, * ) are supported in price formulas. Parentheses can be used to indicate precedence.

Functions used in price formulas

The following table lists the functions that can be used in price formulas.

Function Description Notes Examples
fieldLookup("<object>", "<field>") Returns the value of a field on a standard Zuora object.

Currently, only the Account and Subscription objects are supported. For usage charge type, Usage object is also available.

Supported Account fields include:

  • Standard Account object fields:
    • accountNumber
    • currency
  • All custom fields on the Account object

Supported Subscription fields include:

  • Standard Subscription object fields:
    • autoRenew
    • customerAcceptanceDate
    • contractEffectiveDate
    • currentTerm
    • currentTermPeriodType
    • initialTerm
    • initialTermPeriodType
    • renewalSetting
    • renewalTerm
    • renewalTermPeriodType
    • serviceActivationDate
    • subscriptionEndDate
    • subscriptionStartDate
    • termEndDate
    • termStartDate
    • termType
  • All custom fields on the Subscription object

Note: Usage fields are only available when you configure the Multi-Attribute Pricing charge model on a usage charge.

Supported Usage fields include:

  • Standard Usage object fields:
    • accountNumber
    • subscriptionNumber
    • chargeNumber
    • uom
    • startDateTime
  • All custom fields on the Usage object

Examples:

  • fieldLookup("account", "currency")
  • fieldLookup("subscription", "autoRenew")
  • fieldLookup("usage", "location__c")
max(<argument1>, <argument2>, … ) Returns the greatest numerical value out of the supplied arguments.

Each argument must be a numerical value or a function that returns a numerical value.

This function supports two or more arguments.

Examples:

  • max(1, 2, 3.4)
    This example returns 3.4.
  • max(100.23, usageQuantity()) 
    This example returns the greater value of the quantity on the current usage record, or 100.23.
  • 2 * max(0, usageQuantity() - 50) 
    This example returns the usage quantity above 50 multiplied by 2, or zero if the usage quantity is less than 50.
min(<argument1>, <argument2>, … ) Returns the smallest numerical value out of the supplied arguments.

Each argument must be a numerical value or a function that returns a numerical value.

This function supports two or more arguments

Example:

  • min(10, 9, 8, 7, 6, 5, 4)
    This example returns 4.
objectLookup("<customObject>", "<targetField>”, [ “<field>”=<value>, ...] )

Returns the value in the <targetField> of the specified <customObject>, performing the lookup by using all the provided <field> $op <value> criteria.

<field> must be on the specified <customObject>.

$op is an operator. Currently supported operators included: =, <, <=, >, and >=.

<value> can be a string, number, or any supported function (except for objectLookup()).

The provided criteria must uniquely identify one record in the specified custom object.

You can provide up-to the current limit of custom object filterable fields as the criteria, using a comma to separate the field/value pairs.

It is best practice not to nest objectLookup() functions within each other.

Example:

objectLookup(“myObject”, “price__c”, [

  “color__c” = “red”,
  “type__c” = 12,
  “level__c” = fieldLookup(“usage”,“my_level__c”)
])
This example returns the value in the "price__c" field of the "myObject" custom object, based on the three attribute criteria. Note the use of constant values "red" and 12. The last attribute is dynamically looked up based on data provided on the usage record.
 
usageQuantity(<argument>)

Returns the quantity on the usage record. This function can contain an optional argument.

  • <none>: Returns the quantity on the current usage record being rated.
  • RUNNING: Returns the sum of the quantity for the usage records already rated. This running total is exclusive of the current usage record.
  • TOTAL: Returns the sum of the quantities for the usage records already rated plus the current usage record being rated.

Note: This function applies to usage charges only.

The quantity totals will reflect all the usage records being considered for this charge and a date range. The date range is usually the billing period of the charge, unless changes are made to the charge via an Amendment or an Order.

 Examples:
  • 1.5 * usageQuantity()
    This example returns 1.5 times the quantity on the current usage record..
  • min(100, usageQuantity(RUNNING) + usageQuantity())
    This example returns the lowest value of 100 or the total usage rated so far..
  • min(100, usageQuantity(TOTAL))
    This example the same value as the previous example.

effectiveDate(<objectLookup>, "<effectiveDateField>")

effectiveDate(<objectLookup>, "<effectiveDateField>", <effectiveDate>)

Adds effective date semantics to the <objectLookup> function.

This function is intended for use in custom object lookups where you provide the name of an additional field on the custom object (<effectiveDateField>). The indicated custom object'seffectiveDateField field should contain a date value, for example, 2019-01-23, which indicates when that record becomes effective. 

The record with a date closest, but earlier than or equal to the effective date value, is used.

Note: The default effective date applies to usage charges only. In the first form, the function uses the start date of the usage record to compare with the <effectiveDateField>.

The second form allows the use of a value or function that returns a date or date string (in format yyyy-mm-dd).

Examples:

  • effectiveDate(objectLookup("pricecatalog__c","output__c", ["field1__c"="gold status"]),"catalog_date__c" )

This example works only for usage charges, where the start date of the usage record is compared to the "catalog_date__c" field on the custom object record, to find the appropriate row.

  • effectiveDate(objectLookup("pricecatalog__c", "output__c", ["field1__c"="gold status"]),"catalog_date__c", '2019-06-20' ) 

This example uses pricing as of June 20, 2019 in the custom object.
firstValue(<argument1>, <argument2>, …) Returns the first non-empty value from the arguments. Arguments might be a string, number, or any supported function.
This function supports 2 or more arguments.

Examples:

  • firstValue( fieldLookup("usage", "preratedAmount__c"), 20.50)  

This example returns the default value of 20.50 if the usage record does not have a defined pre-rated amount.

  • usageQuantity() * firstValue(objectLookup("myCarObj", "outputField__c",  ["make" = fieldLookup("usage", "make__c"), "model" = fieldLookup("usage", "model__c")]),              objectLookup("myRegionObj", "outputField__c", ["region" = fieldLookup("usage","region__c")]), 0.10)  

This example first attempts a lookup of the make and model, then a lookup of the region, and finally falls back to a hard-coded default value of 0.10.