Dynamic formula builder reference

Dynamic discount and points formula builder with full operator and operand reference

The dynamic formula builder defines how the values are calculated.

Instead of using a static value for discounts or loyalty points, you can create formulas with mathematical and logical operators and assign a dynamic value. Discounts or points will be calculated during redemption based on the provided formula and metadata values.

The formula builder requires a static fallback value in case the dynamic value cannot be calculated from the formula’s given parameters.

You can either use the Formula builder utility with step-by-step dialogs that you fill out to build the formula from element building blocks or the Expression output with operators and operands.

Application scope

The dynamic discount formula builder applies to the following discount types:

• Order discount
• Product discount
• Reward

It can be used when creating coupon campaigns, in-cart promotions, and referral codes.

The dynamic points formula builder applies to the following earning rules:

• Fixed
• Proportional

It can be used when creating loyalty programs.

Context specific

The operators and operands in the dynamic formula builder depend on the context of the formula, such as the discount effect and other factors. Some of the operators and operands will not be available based on the specific configuration.

Formula builder

You can use the Formula builder utility with step-by-step dialogs to build the formula from element building blocks.

1. Open formula builder

   Click the Formula button next to the discount value or points.

2. Build formula

   Build your formula using the formula builder by choosing a type of operand followed by an operator. Click the X button to delete a number or expression and the + button to add a number or expression.

3. Remove operator

   To remove an operator you have entered, click on it and click the Remove button.

4. Review expression

   To review your expression, choose Expression output.

5. Save

   Click Save once you have finished defining your dynamic discount formula.

To edit your existing formula, click the Formula button next to the discount value.

To remove a saved formula, click — button next to the Formula button.

Expression output

You can view and edit the dynamic formula through a mathematical expression using operands and operators.

Click Save once you have finished defining your dynamic formula.

Operand reference

You can see the discount values that you can create using different discount operands in the following table.

Metadata and base operands

Operand	Definition	Example
Number	Value is a Number.	2
Text	Value is a String.	Unique string of alphanumeric characters.
Order metadata	Value is an order metadata attribute of type Number or String.	ORDER_METADATA("day_of_week")
Voucher metadata	Value is a voucher metadata attribute of type Number or String. Available in dynamic discount formulas only.	REDEEMABLE_METADATA("active_on_calendar_month")
Customer metadata	Value is a customer metadata attribute of type Number or String.	CUSTOMER_METADATA("customer_life_time_value")
Redemption metadata	Value is a redemption metadata attribute of type Number or String. Available in dynamic discount formulas only.	REDEMPTION_METADATA("store_list")
Publication metadata	Value is a publication metadata attribute of type Number or String. Available in dynamic discount formulas only.	PUBLICATION_METADATA("year")
Promotion tier metadata	Value is an order metadata attribute of type Number or String. Available in dynamic discount formulas only (promotion).	REDEEMABLE_METADATA("membership_duration")

Expression functions

Operand	Definition	Example
Brackets	Groups expression elements together; i.e. adds parentheses to your formula.	(10 - ORDER_METADATA("number_of_store_visits"))
Min	Lowest value in a range	MIN(PUBLICATION_METADATA("year"); CUSTOMER_METADATA("customer_life_time_value"))
Max	Highest value in a range	MAX(PUBLICATION_METADATA("year"); CUSTOMER_METADATA("customer_life_time_value"))
Power	A number raised to a power; defines the base and exponent.	POW(ORDER_METADATA("number_of_store_visits");2)
Round	Round a number to a specified number of digits. Positive precision refers to a decimal place indicator. Negative precision indicates an integer place indicator.	ROUND(CUSTOMER_METADATA("customer_life_time_value");1)
Floor	Round down to a specified number of digits.	FLOOR(CUSTOMER_METADATA("customer_life_time_value");1)
Ceil	Round up to a specified number of digits.	CEIL(CUSTOMER_METADATA("customer_life_time_value");1)
If	Value based on a logical expression; defines the logical test value, value if expression is true and value if expression is false.	IF(ORDER_METADATA("number_of_store_visits") > 5;10;3)
Default to	Returns the first non-null value of range.	DEFAULT_TO(REDEMPTION_METADATA("store_list") / 2;5)

Order item operands (product discount only)

Operand	Definition
ORDER_ITEM_PRICE	Returns order item price.
ORDER_ITEM_AMOUNT	Returns order item amount; for stacked discounts, returns the original amount without any modifications due to other discounts.
ORDER_ITEM_SUBTOTAL	Returns order item subtotal; for stacked discounts, each additional discount is based on the result obtained after calculating the previous discount.
ORDER_ITEM_UNITS_QUANTITY	Returns order item quantity.
ORDER_ITEM_METADATA(“Size”)	Returns order item metadata.
ORDER_ITEM_PRODUCT_METADATA(“category”)	Returns order item product metadata.

Order-level operands

Operand	Definition
ORDER_AMOUNT	Returns the order total value, whole cart value.
ORDER_ITEMS_QUANTITY	Returns the item count.
ORDER_UNITS_QUANTITY	Returns the sum of the units ordered.

Cheapest order item operands

Operand	Definition
CHEAPEST_ORDER_ITEM_PRICE	Returns the price of the cheapest line item in the order.
CHEAPEST_ORDER_ITEM_AMOUNT	Returns the amount of the cheapest line items in the order; for stacked discounts, returns the original amount without any modifications due to other discounts.
CHEAPEST_ORDER_ITEM_SUBTOTAL	Returns the subtotal of the cheapest line items in the order; for stacked discounts, each additional discount is based on the result obtained after calculating the previous discount.
CHEAPEST_ORDER_ITEM_UNITS_QUANTITY	Returns total units of the cheapest order line items.
CHEAPEST_ORDER_ITEM_METADATA(“Size”)	Returns the cheapest order item metadata of type Number or String.
CHEAPEST_ORDER_ITEM_PRODUCT_METADATA(“category”)	Returns the cheapest order item product metadata.

Most expensive order item operands

Operand	Definition
MOST_EXPENSIVE_ORDER_ITEM_PRICE	Returns the price of the most expensive line item in the order.
MOST_EXPENSIVE_ORDER_ITEM_AMOUNT	Returns the amount of the most expensive line items in the order; for stacked discounts, returns the original amount without any modifications due to discounts.
MOST_EXPENSIVE_ORDER_ITEM_SUBTOTAL	Returns the subtotal of the most expensive line items in the order; for stacked discounts, each additional discount is based on the result obtained after calculating the previous discount.
MOST_EXPENSIVE_ORDER_ITEM_UNITS_QUANTITY	Returns the total units of the most expensive order line items.
MOST_EXPENSIVE_ORDER_ITEM_METADATA(“Size”)	Returns the most expensive order item metadata of type Number or String.
MOST_EXPENSIVE_ORDER_ITEM_PRODUCT_METADATA(“category”)	Returns the most expensive order item product metadata.

The Cheapest & Most Expensive Order Item

How are the cheapest and most expensive order items found if there are multiple items with the same price?

Cheapest order item

1. First, the formula tries to find the order item with the cheapest price. If there is one item, the formula returns this item. Otherwise, it proceeds to step 2.
2. If there are n items that have the same cheapest price, from this n, the formula finds the items with the lowest subtotal. If there is only one item, the formula returns this item. Otherwise, if there are many items, it proceeds to step 3.
3. Finally, it returns the first item from the list of the cheapest items with the lowest subtotal.

Most expensive order item

1. First, the formula tries to find the order item with the most expensive price. If there is one item, the formula returns this item. Otherwise, it proceeds to step 2.
2. If there are n items that have the same most expensive price, from this n, the formula finds the items with the lowest subtotal. If there is only one item, the formula returns this item. Otherwise, if there are many items, it proceeds to step 3.
3. Finally, it returns the first item from the list of the most expensive items with the lowest subtotal.

Operator reference

Number operators

Here are the discount formula operators you can choose from for properties of Number type.

Add (+)

Adds numbers or expressions.

Example with missing metadata property defaulting to fallback value:

CUSTOMER_METADATA("number_of_store_visits") + REDEEMABLE_METADATA("active_on_calendar_month")

Missing metadata property: number_of_store_visits
Fallback value: 10%

Subtract (-)

Subtracts numbers or expressions.

Give a customer a percent off for every year since they first became a customer.

PUBLICATION_METADATA("year") - CUSTOMER_METADATA("customer_life_time_value")

year: 2022
customer_life_time_value: 2012

Calculated dynamic discount value: 10%
Fallback value: 10%

Multiply (x)

Multiplies numbers or expressions.

Give a customer a discount proportional to the day of the week if the week is defined as:

Sunday - 0
Monday - 1
Tuesday - 2
Wednesday - 3
Thursday - 4
Friday - 5
Saturday - 6

ORDER_METADATA("day_of_week") x 2

day_of_week: 5

Calculated dynamic discount value: $10 Fallback value:$10

Divide (÷)

Divides numbers or expressions.

Give a customer an eighth for every month the customer was active.

CUSTOMER_METADATA("customer_months_active") ÷ 8

customer_months_active: 8

Calculated dynamic discount value: $10 Fallback value:$10

Modulo (%)

Returns the remainder after division.

Give a customer a certain number of free items based on a custom formula.

REDEEMABLE_METADATA("active_on_calendar_month") % REDEMPTION_METADATA("allowed_free_units")

active_on_calendar_month: 10
allowed_free_units: 9
remainder: 1

Calculated dynamic discount value: 1 Free item
Fallback value: 1 Free item

Greater than (>)

Logical operator returns the value if true when the left side is greater than the right side.

Give a customer 20% off every time they make a purchase after their 10th store visit. Otherwise, the customer receives a standard 3% discount.

IF(CUSTOMER_METADATA("number_of_store_visits") > 10;20;3)

Less than (<)

Logical operator returns the value if true when the left side is less than the right side.

Give a customer 3% off each store visit until their 9th store visit. Beginning from their 10th visit, give the customer a 20% discount.

IF(CUSTOMER_METADATA("number_of_store_visits") < 10;3;20)

Equal to (=)

Logical operator returns the value if true when both sides are equal.

Give a customer 50% off on their 50th store visit.

IF(CUSTOMER_METADATA("number_of_store_visits") = 50;50;0)

In array

Logical operator returns true if the value is one of the provided values.

Give a customer a $10 discount if the number of units in an order is 3, 6, 9, 12, or 15.

IF(ORDER_UNITS_QUANTITY IN_ARRAY "3, 6, 9, 12, 15";10;5)

Not in array

Logical operator returns true if the value is NOT one of the provided values.

IF(ORDER_UNITS_QUANTITY NOT_IN_ARRAY "1, 2, 3, 4";10;5)

String operators

Here are the operators you can choose from for properties of String type.

Is

Returns true if strings are equal.

IF(CUSTOMER_METADATA("acquisition_channel") is "Facebook";20;CUSTOMER_METADATA("age"))

Is not

Returns true if strings are NOT equal.

IF(CUSTOMER_METADATA("acquisition_channel") isNot "Twitter";10;3)

Contains

Returns true if the value contains the provided string.

IF(CUSTOMER_METADATA("location") contains "California";3;0)

Starts with

Returns true if the value starts with the provided string.

IF(REDEMPTION_METADATA("location_id") startsWith "Jersey_Shoreline_store_";15;0)

Ends with

Returns true if the value ends with the provided string.

IF(PUBLICATION_METADATA("publication_method") endsWith "_sms";50;35)

In array

IF(ORDER_METADATA("region") IN_ARRAY "EU, EMEA";10;5)

Not in array

IF(ORDER_METADATA("region") NOT_IN_ARRAY "EU, EMEA";10;5)

Date operators

Here are the operators for properties of Date type.

Days since

Returns number of days from the start date to today (excluding end date).

IF(DAYS_SINCE(CUSTOMER_METADATA("date_last_purchase")) < 31;30 / DAYS_SINCE(CUSTOMER_METADATA("date_last_purchase"));0)

Months since

Returns number of months from the start date to today (excluding end date).

IF(MONTHS_SINCE(CUSTOMER_METADATA("date_subscribed")) > 12;20;10)

Years since

Returns number of years from the start date to today.

YEARS_SINCE(CUSTOMER_METADATA("acquisition_date"))

Get a discount equal to your age:

YEARS_SINCE(CUSTOMER_BIRTHDATE)

Days until

Returns number of days from today to the future date.

Early bird example:

DAYS_UNTIL(VOUCHER_EXPIRATION_DATE) * 2

Months until

IF(MONTHS_UNTIL(VOUCHER_EXPIRATION_DATE) > 6;15;5)

Day of month

Customer’s whose birthday falls on the 6th of the month get a 10% discount.

IF(DAY_OF_MONTH(CUSTOMER_BIRTHDATE) = 6;10;5)

Month

Incentivize customers to make orders through the year.

MONTH(TODAY) * 2

Year

Give higher discounts for younger customers.

YEAR(CUSTOMER_BIRTHDATE) / 100

Date

Incentivize customers to buy on release date.

IF(DATE("2023-08-17");10;5)

Date time

Buy within 5 days since release date and time.

IF(DAYS_SINCE(DATE_TIME("2023-08-17T14:05:00.000Z")) < 5;10;5)

Date equality

IF(TODAY DATE_IS DATE("2023-08-22");10;5)

Date inequality

IF(TODAY DATE_IS_NOT DATE("2023-08-22");10;5)

Is after

IF(TODAY IS_AFTER DATE("2023-08-22");10;5)

Is before

IF(NOW IS_BEFORE DATE("2023-08-22");10;5)

Complex expression operators

AND

All components must be true.

IF(CUSTOMER_METADATA("number_of_store_visits") > 10 AND ORDER_METADATA("day_of_week") = 5;20;3)

OR

At least one component must be true.

IF(CUSTOMER_METADATA("number_of_store_visits") > 10 OR ORDER_METADATA("day_of_week") = 5;20;3)

Nested formulas

You can create nested expressions by embedding IF statements.

IF(ORDER_ITEMS_QUANTITY > 4;IF(ORDER_AMOUNT > 200;25;15);10)

Switch function

You can create expressions using the switch function to create different discount rates.

SWITCH(ORDER_METADATA("store_city");
  SWITCH_CASE("Boston";10)
  SWITCH_CASE("New York";15);
5)