Ctrlk
HomepageCase studiesBook a demo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Using Expressions

Expressions in Open Loyalty campaigns allow you to build flexible and dynamic logic for controlling when effects are applied. One of the most powerful features is the ability to reference custom attributes of members to tailor campaign behavior based on specific data stored in their profiles.

🧩 What Are Member Custom Attributes?

Member custom attributes—also referred to as labels—are member-specific fields used to store additional information. These can be dates, numbers, or strings, such as:

  • post_date – a custom date stored for a member

  • posts_number – a count of submitted posts

  • membership_level – a string indicating tier

You can reference these values inside expressions using Open Loyalty’s expression syntax.

✅ Supported Data Types

Custom attributes support the following value types:

Type
Example

DateTime

"2022-12-20T14:15:22+01:00"

Number

"10.2"

String

"featured"

🛠️ How to Use Custom Attributes in Expressions

To retrieve and use custom attribute values inside campaign rules, you can use the agg(customer.labels).getFirstLabelValue('key') function. Here's how to apply this in practice:

1. Retrieve a Label Value

Returns the value of the label post_date as a string.

2. Parse a Label to a Date

Converts the string to a date format for further operations.

3. Compare with a Timestamp

Converts the value to a UNIX timestamp for time-based comparisons.

📌 Real Example: Reward Within 5 Days of a Custom Date

If you want to grant points only if the transaction happened within 5 days of a custom date, you can use the following condition:

Important: To ensure the campaign only runs if the attribute is present, always include a null-check condition:

🔢 Comparing Numeric Custom Attributes

When comparing numeric values stored as custom attributes, you do not need additional parsing—just ensure you use a dot (.) separator for decimals:

🔁 Rounding Point Values

When campaign expressions produce point values based on division or multiplication, the result is often a floating-point number (e.g. 1.053333333333). Open Loyalty provides two numeric functions to control this:

  • round_down(value) — rounds down to the nearest integer (floor)

  • round_up(value) — rounds up to the nearest integer (ceiling) These are particularly important in multiplier-based campaigns where fractional points would accumulate in wallets and cause precision issues.

🔽 Round Down — Award Whole Points Per Currency Spent

Use round_down() when you want members to earn only full points, never fractions. For example, to award 4 points per dollar spent, rounded down:

For a transaction of $101.23, this awards 404 points (based on $101, not $101.23).

This ensures members receive clean, discrete point values rather than fractional amounts like 404.92.

🔼 Round Up — Favour the Member

Use round_up() when you want to err in the member's favour — always awarding the next full point rather than truncating:

For a transaction of $10.33, this awards 16 points (10.33 * 1.5 = 15.495, rounded up to 16).

✨ Combine with Other Expressions

Custom attributes can be used in combination with other expression elements such as:

  • transaction.sku

  • customer.getWallet().activeUnits

  • transactionItemFilters

  • campaignContext

To learn more about general expression syntax, supported operators, and context, visit:

Expressions

🔍 Summary

Using custom attributes in campaign expressions allows you to:

  • Personalize reward logic

  • Set campaign conditions based on member behavior

  • Handle complex use cases like anniversary dates, member segmentation, or activity limits

Whether you're working with dates, numbers, or string attributes, Open Loyalty's expression engine helps you build sophisticated rules for smarter, more contextual campaigns.

Last updated

Was this helpful?