Entity Dimension Filters

Purpose

Most Entity types, such as Offers, Forms, Lists etc allow you to specify Dimension Filters. Those Dimension Filters are verified against the passed in Dimension values to make sure they match.

They have three purposes:

1. To allow websites and other API applications to only list the Entities that are relevant to them. For example a company's English website may not want to display the Offers that apply to their German website.
2. To validate during a POST/PUT operation that the Entity is applicable to the specified dimensions. For example trying to claim a campaign offer for the wrong campaign will give an error.
3. To carry out different tasks based on the passed in dimensions. For example triggers would not fire unless the triggered Entity's Dimension Filter matches the passed in Dimension.

Syntax

Dimension Filters can be based on one or more Dimensions. For each Dimension, the filter value can contain one of the following types of expressions:

• Exact value. For example 'UK'. Requires the passed in Dimension value to match exactly (SQL =)
• List of exact values. For example 'UK,US'. The passed-in Dimension Value must have one of those values (SQL IN)
• Wildcard value. For example 'summer*'. The passed in Dimension Value must begin with summer, but can contain any characters afterwards. (SQL LIKE)
• Interval. For example 'A-ZZZZ'. The passed in Dimension Value must start with a character in the interval. (SQL BETWEEN). Note that the last value of the interval must cover all characters, as in the example above. Digits are treated as strings, so 2 is greater than 11.
• To just make the Dimension Value mandatory, give the value '*' (SQL NOT NULL)
• To just say that the Dimension Value is not allowed, give the value '.' (SQL NULL)
• Any of the above can be negated by starting the expression with '!', for example '!summer*' (SQL NOT LIKE)

Example

For the purpose of these examples we assume that the passed-in Dimensions are: country:US;campaign:summer2022;abtest:AA.

A website is trying to display all available Offers by calling the Loyalty API's GET .../offers endpoint.

📘

How Dimension Values are passed in

Every call to the Loyalty API allows you to pass in the Dimensions that represent who you are and what the call is regarding. This is done in the dim request parameter, for example: GET .../offers?dim=country:US;campaign:summer2022;abtest:AA

There may be several active Offer Entities in the system, but some of them have Dimension Filters. Here's a list with examples of different Dimension Filters

Dimension Filter
(no Dimension Filter)	Displayed
country=*	Displayed
country=*;market=US	Not displayed, since the market was not passed in
country=US,CA	Displayed, since US is one of the values
country=!UK,CA	Displayed, since US is not in the list of forbidden countries
campaign=*2022	Displayed
abtest=A-AZ;campaign=*	Displayed, since campaign is filled in and the abtest is within the specified value range
abtest=A-AZ;market=*	Not displayed, since the market is not passed in
country=US,UK;market=.	Displayed, since market is not passed in