# Expression syntax

The expressions used in [rules](/en/transactional/rules/) follow a lean syntax inspired by spreadsheet formulas. Each expression is composed of, at minimum, a **variable**, an **operation**, and a **value**.

```
$merchant_id == "XYZ"
```

The expression above is true when the merchant ID equals `"XYZ"`.

## Variables

Every variable starts with `$`. The available variables depend on the event type being evaluated.

| Variable                 | Content                                                                   | Type       | Example          |
|--------------------------|---------------------------------------------------------------------------|------------|------------------|
| `$amount`                | Total payment amount                                                      | Decimal    | `100.12`         |
| `$card_bin`              | First 6 to 8 digits of the PAN (BIN/IIN)                                  | Text       | `"44332211"`     |
| `$card_issuer_country`   | Card issuer country (ISO 3166-1 alpha-2)                                  | Text       | `"BR"`           |
| `$card_last_four`        | Last four digits of the card                                             | Text       | `"1234"`         |
| `$device_fingerprint_id` | Device fingerprint                                                        | Text       | `"xyz"`          |
| `$device_ip_address`     | Device IP address                                                         | IP address | `"200.123.10.2"` |
| `$device_user_agent`     | Device User-Agent                                                         | Text       | `"Mozilla/5.0"`  |
| `$merchant_id`           | Merchant ID                                                               | Text       | `"store-1234"`   |
| `$metadata_[key]`        | Metadata sent via API                                                     | Text       | `"value"`        |
| `$score`                 | Risk score calculated by the platform (0.00 to 1.00)                      | Decimal    | `0.75`           |
| `$user_email_domain`     | User's email domain                                                       | Text       | `"gmail.com"`    |
| `$user_id`               | User ID                                                                   | Text       | `"customer-1234"` |
| `$user_profiles`         | User's payment profiles (available only with the `count` function)        | Collection | N/A              |

## Operations

| Operation | Meaning                        |
|-----------|--------------------------------|
| `==`      | Equality                       |
| `!=`      | Inequality                     |
| `>`       | Greater than                   |
| `>=`      | Greater than or equal to       |
| `<`       | Less than                      |
| `<=`      | Less than or equal to          |
| `in`      | Belongs to a collection        |
| `not in`  | Does not belong to a collection |

## Values

The value compared against a variable can be text or a number:

- **Text**: always in double quotes, like `"XYZ"`. Single quotes and unquoted text are not accepted.
- **Number**: written without quotes, using a period as the decimal separator, like `1000` or `99.01`.

Since all text is double-quoted, values such as an IP, a date, or a word used in the syntax itself (for example, `in`) also need the quotes to be treated as text.

To check whether a variable is empty, compare it with `null` (without quotes) using `==` or `!=`:

```
$device_fingerprint_id == null
```

The expression above is true when the event has no device fingerprint. Use `!=` for the opposite case, when the variable has some value.

## Functions

### `concat`

The `concat` function joins several values into a single text, which can be compared against a value. Each argument is a variable (`$variable`) or fixed text, separated by commas:

```
concat($user_id, "-", $merchant_id) == "customer-1234-store-1234"
```

The expression above is true when the combination of the user ID and the merchant ID, joined by a hyphen, results in `"customer-1234-store-1234"`.

Considerations about the joined values:

- Variables without a value are treated as empty text.
- Numeric values are converted to text in their original form (for example, `99.01` and `0.9`).

## Combining expressions

Use `and` and `or` to combine expressions. `and` takes precedence over `or`: in a combination without parentheses, the parts joined by `and` are evaluated first. So `A and B or C` is equivalent to `(A and B) or C`.

Use parentheses to group expressions and change this precedence:

```
($amount > 1000 and $user_email_domain == "gmail.com") or $card_issuer_country != "BR"
```

## Lists

Lists configured under **Settings > Lists** are available as collections. For example, to check whether a customer is on a quarantine list:

```
$user_id in @quarantined_customers
```

You can also write the collection directly in the expression, in square brackets with the values separated by commas. For example, to check whether the card issuer country is not among the supported countries:

```
$card_issuer_country not in ["BR", "AR", "CL"]
```