Rules engine

The rules engine is what risk and fraud teams use to change how transactions are approved or blocked, without touching application code. Each rule is a small expression that runs on every transaction Tracer validates — “block this MCC for this segment”, “send anything over R$ 50k to manual review”, “deny if the account is suspended”. What changes in your operation: rule changes ship through an API endpoint, not through a release. An analyst can publish a new rule in the morning and see it evaluating real transactions within seconds. Every match is recorded, so a denied customer call six months later can be traced back to the exact rule that fired. Trade-off to be honest about: you have to think in CEL (Common Expression Language) instead of Go, Python, or Java. The learning curve is short — most rules are one line — but the team writing them is no longer your application developers. The upside is no deploys, full audit, and the people closest to the policy own the policy.

Who is this guide for? Risk and fraud analysts who will write rules, developers integrating the validation call, and compliance officers reading the audit trail. The CEL examples get technical further down, but the lifecycle and decision logic are useful for anyone evaluating the product.

The Tracer rules engine evaluates validation logic written in — a type-safe expression language from Google. Expressions are compiled at rule creation and run during every transaction validation; you change behavior by updating rules through the API, without redeploying code.

Why use the rules engine

Flexibility: Create and modify rules without code deploys
Performance: Compiled expressions evaluate in under 1ms each
Type safety: Expression syntax validated at rule creation
No short-circuit: matching rules are evaluated together, so the audit trail records the rules that triggered, not just the winning category
Scope-based: Apply rules to specific segments, accounts, or transaction types

By the end of this guide, you will:

Understand rule engine concepts and evaluation flow
Create and test expression-based rules
Manage the rule lifecycle (DRAFT, ACTIVE, INACTIVE, DELETED)
Apply best practices for rule management

What is the rules engine

The rules engine is the Tracer component responsible for evaluating expressions during transaction validation. It enables fraud analysts and risk managers to configure business logic that executes in real time—without requiring code deployments or engineering support.

How it works

How the rules engine evaluates configured expressions against the transaction context during validation and returns a decision — Figure 1. Rules engine evaluation flow

In this flow:

Load rules fetches all active rules from cache (or database on cache miss)
Evaluate expressions runs the CEL expression of each rule whose scope matches the transaction
Collect matches gathers all rules that matched and determines the decision

Evaluation pattern

Rules whose scope matches the transaction are evaluated together. There is no priority ordering and no short-circuit evaluation. This ensures:

Complete audit trail (all matching rules recorded)
No information loss (analysts can see all triggers)
Simple logic (no priority conflicts)

Decision precedence (highest to lowest):

DENY — any matching DENY rule wins outright.
Limit exceeded — if no DENY rule matched but any applicable limit is exceeded, the decision is DENY (rule precedence applies first; limits come in only when no DENY rule matched).
REVIEW — if no DENY rule matched and no limit was exceeded, any matching REVIEW rule wins.
ALLOW — if only ALLOW rules matched, the decision is ALLOW.
Default — if no rule matched at all, Tracer returns the configured DEFAULT_DECISION_WHEN_NO_MATCH (ALLOW unless explicitly set to DENY for fail-closed deployments). Only ALLOW and DENY are accepted; REVIEW is deliberately not a valid no-match default, and any other value fails the service at boot.

matchedRuleIds in the response contains every rule that matched, regardless of the winning category, so audit consumers can see all triggers.

Why DENY beats REVIEW beats ALLOW. Precedence is fixed and not configurable, on purpose: it removes the “which DENY rule wins?” ambiguity at runtime and makes audit trivial — the response always identifies the strictest action that fired. The cost is that you can’t write “ALLOW rules that override DENYs”; if you need that pattern, the right answer is to make the DENY rule more specific instead.

Tracer returns decisions; it does not block transactions directly. Your system receives the decision and is responsible for taking the appropriate action (e.g., blocking, allowing, or queuing for review).

Core concepts

Before creating rules, understand the foundational elements.

Rules

A rule is a unit of business logic composed of:

Expression - A type-safe expression that evaluates to true or false
Action - What decision to return when the expression is true
Scopes - Which transactions the rule applies to
Status - The rule’s lifecycle state

Expressions

Expressions are written in CEL (Common Expression Language), a type-safe language that evaluates transaction context and returns a boolean value (true or false). CEL provides compile-time validation, so syntax errors are caught when you create the rule—not when transactions are being processed. Example expressions:

amount > 10000

segment.segmentId == "high-risk-segment-uuid" && amount > 5000

merchant["category"] == "7995"

(merchant.category is the 4-digit ISO 18245 MCC code — "7995" is the MCC for betting/casino. Both merchant.category and merchant["category"] are accepted; the production examples use bracket notation by convention. If you need to match on a string label like "gambling", store it in metadata and match on that instead.) Expressions read the validation request through ten variables. For the field types and formats behind each one, see the ValidationRequest schema in the API reference.

Variable	Type	What you typically match on
`amount`	number	The transaction value, in the same units you send in the request: `"1500.00"` reaches an expression as `1500`. Safe range is `±2^53`.
`transactionType`	string	One of `CARD`, `WIRE`, `PIX`, `CRYPTO`.
`subType`	string	Free-form, lower case (e.g., `"international"`, `"debit"`). Empty string when not provided.
`currency`	string	ISO 4217 code (e.g., `"BRL"`).
`transactionTimestamp`	int	Transaction time in Unix nanoseconds. Divide by `1000000000` for seconds.
`account`	map	`accountId`, `type`, `status`, `metadata`.
`segment`	map	`segmentId`, `name`, `metadata`.
`portfolio`	map	`portfolioId`, `name`, `metadata`.
`merchant`	map	`merchantId`, `name`, `category`, `country`, `metadata`.
`metadata`	map	Custom fields your integration passes in the request payload.

Field values worth knowing before you write a condition:

account.status accepts active, suspended, closed, and account.type accepts checking, savings, credit.
merchant.category takes a 4-digit ISO 18245 MCC code; merchant.country takes an ISO 3166-1 alpha-2 code.
Those four fields are optional on the request. A field the request omits reaches your expression as an empty string, so a condition that tests it for a specific value is false.
segment.segmentId, portfolio.portfolioId, account.accountId, and merchant.merchantId are UUID strings.

segmentId and portfolioId live on the top-level segment and portfolio variables, not on account. To match by segment, write segment.segmentId == "...", not account.segmentId == "...".A rule that reads a context field the request does not carry does not match, and the other rules still run — so you do not need a presence guard for that case. When presence itself is the condition you want, write size(segment) > 0 or "risk_score" in metadata.

Expression cost is bounded by CEL_COST_LIMIT (default 10000). The check runs at compile time — on create, on expression update, and again on activate — not only at activation: an expression whose worst-case estimated cost exceeds the limit is rejected with error code 0342 (cost limit exceeded) the first time you submit it. Syntax errors surface as 0340, type errors (including an expression that does not return a boolean) as 0341, and a failure to estimate cost at all as 0345.

Expression examples by use case

Here are practical examples organized by business scenario:

Amount-based rules

// Block transactions above a threshold
amount > 10000

// Block high-value international transfers
transactionType == "WIRE" && subType == "international" && amount > 50000

// Review large cryptocurrency transactions
transactionType == "CRYPTO" && amount > 5000

Merchant-based rules

// Block gambling merchants
merchant.category == "7995"

// Block high-risk merchant categories
merchant.category in ["7995", "5967", "5966"]

// Review transactions from new merchant countries
merchant.country != "BR" && amount > 1000

Account-based rules

// Block suspended accounts
account.status == "suspended"

// Review transactions from newly created accounts
metadata.accountAgeDays < 30 && amount > 500

// Block closed accounts
account.status == "closed"

Combined conditions

// High-value transaction from high-risk segment
segment.segmentId == "high-risk-segment-uuid" && amount > 5000

// International Pix above threshold
transactionType == "PIX" && subType == "international" && amount > 10000

// Large card transaction to foreign merchant
transactionType == "CARD" && merchant.country != "BR" && amount > 3000

Time-based rules

// Review late-night card transactions above BRL 5,000
transactionType == "CARD" && amount > 5000 && timestamp(transactionTimestamp / 1000000000).getHours("UTC") >= 22

// Review weekend transactions above BRL 10,000
timestamp(transactionTimestamp / 1000000000).getDayOfWeek("UTC") in [0, 6] && amount > 10000

Using metadata

// Block transactions from untrusted devices
metadata.deviceTrust == "untrusted"

// Review first-time purchases above threshold
metadata.isFirstPurchase == true && amount > 1000

// Block transactions outside business hours (using metadata)
metadata.isBusinessHours == false && amount > 5000

// VIP customers bypass certain restrictions
metadata.customerTier == "vip" && amount < 50000

Metadata fields are provided by your integration. Design your payload to include the context your rules need.

Actions

Actions determine the decision when an expression evaluates to true:

Action	Description
`ALLOW`	Allow the transaction
`DENY`	Deny the transaction
`REVIEW`	Route to manual review

Scopes

Scopes define which transactions a rule applies to. A rule with no scopes is global and evaluates against every transaction. A rule with one or more scope objects evaluates only when the transaction matches at least one of them (OR semantics across scope objects). Within a single scope object, the supported fields are:

segmentId - Match transactions from a specific segment
portfolioId - Match transactions from a specific portfolio
accountId - Match transactions from a specific account
merchantId - Match transactions to a specific merchant
transactionType - Match specific transaction types (CARD, WIRE, PIX, CRYPTO)
subType - Match specific subtypes (debit, credit, instant, etc.)

Matching semantics:

Within one scope object: fields combine with AND. A field that is not specified is treated as a wildcard (matches any value). At least one field must be set — empty scope objects ({}) are rejected with error code 0358.
Across multiple scope objects on the same rule: they combine with OR. The rule matches if any scope object matches the transaction.

For example, a rule with two scopes — one targeting transactionType: CARD and another targeting transactionType: PIX — runs for both card and Pix transactions. A single scope with both segmentId AND accountId requires the transaction to match the segment AND the account.

Rule lifecycle

Rules progress through a defined lifecycle to ensure safe deployment.

Lifecycle of rules and limits in Tracer, showing the status transitions a definition moves through from creation to active enforcement — Figure 2. Rules lifecycle and status transitions

States

State	Description
`DRAFT`	Not evaluated; expression can be modified freely
`ACTIVE`	Evaluated during validations; expression is immutable
`INACTIVE`	Not evaluated; preserved for audit trail; can be reactivated. The expression is still immutable in this state — to edit it, move the rule back to DRAFT via `POST /v1/rules/{id}/draft`.
`DELETED`	Soft-deleted; not returned by listings and cannot be recovered through the API, but the row is preserved in the database for audit trail.

Transitions

Transition	From	To	Description
`activate`	DRAFT, INACTIVE	ACTIVE	Start evaluation (validates expression)
`deactivate`	ACTIVE	INACTIVE	Stop evaluation
`draft`	INACTIVE	DRAFT	Re-edit a previously deactivated rule before reactivating
`delete`	DRAFT, INACTIVE	DELETED	Permanent removal (cannot delete ACTIVE rules)

Active rules must be deactivated before deletion. This prevents accidental removal of rules that are currently being evaluated.

Create a rule

Create rules using POST /v1/rules. Rules are created in DRAFT status by default. A rule requires:

name: A descriptive name, unique within its context. The context is derived from the rule’s scopes (the lowest segmentId across them); rules with no scope share a single global context. So the same rule name can coexist across two different segments, but not twice inside one. Comparison is case-insensitive and ignores repeated whitespace; a collision returns 409 Conflict with error code 0441. Tracer keeps the name in a normalized form, so the name it returns can differ from the string you sent — reference the rule by the ruleId in the response.
expression: A CEL expression that evaluates to true or false
action: The decision to return when the expression matches (ALLOW, DENY, or REVIEW)
scopes (optional): Limit which transactions the rule applies to

For complete payload structure and field details, see the API reference.

Activate and deactivate rules

After creating a rule, activate it to start evaluation. Deactivate rules to stop evaluation without deleting them.

Operation	Endpoint	Description
Activate	`POST /v1/rules/{id}/activate`	Start evaluating this rule
Deactivate	`POST /v1/rules/{id}/deactivate`	Stop evaluating (preserves for audit)

Deactivating a rule preserves it for audit purposes. Use delete only when you want to permanently remove a rule.

List and query rules

Query rules for management and auditing using GET /v1/rules.

Query parameters

Parameter	Type	Description
`name`	string	Filter by name (case-insensitive partial match)
`status`	string	Filter by status (DRAFT, ACTIVE, INACTIVE). `DELETED` is not a valid filter value.
`action`	string	Filter by action (ALLOW, DENY, REVIEW)
`account_id`	UUID	Filter by scope: account ID
`segment_id`	UUID	Filter by scope: segment ID
`portfolio_id`	UUID	Filter by scope: portfolio ID
`merchant_id`	UUID	Filter by scope: merchant ID
`transaction_type`	string	Filter by scope: transaction type (CARD, WIRE, PIX, CRYPTO)
`sub_type`	string	Filter by scope: subtype (e.g., debit, credit)
`limit`	integer	Items per page (default: 10, max: 100)
`cursor`	string	Pagination cursor from previous response
`sort_by`	string	Sort field: `created_at`, `updated_at`, `name`, `status` (default: `created_at`)
`sort_order`	string	Sort direction: `ASC`, `DESC` (default: `DESC`)

Get a specific rule

Use GET /v1/rules/{id} to retrieve the full rule definition including expression and scopes.

Update a rule

Update rules using PATCH /v1/rules/{id}. Rules can be updated in any status, with one important restriction:

The expression field is immutable in ACTIVE and INACTIVE states — deactivating a rule is not enough. To edit an expression, move the rule from ACTIVE → INACTIVE (POST /v1/rules/{id}/deactivate), then from INACTIVE → DRAFT (POST /v1/rules/{id}/draft). Only DRAFT rules accept expression updates. Once edited, reactivate with POST /v1/rules/{id}/activate.

Delete a rule

Delete rules that are no longer needed. Only DRAFT and INACTIVE rules can be deleted. ACTIVE rules must be deactivated first.

DELETE /v1/rules/{id}
X-API-Key: {api_key}

Deletion is permanent. Deleted rules cannot be recovered and do not appear in any listings.

Best practices

Follow these practices for effective, maintainable rules.

Naming

Use descriptive names - The name should clearly state what the rule does
Include context - Mention the scenario or transaction type
Avoid abbreviations - Prefer clarity over brevity

Less clear	More clear
`Rule 1`	`Block night transactions above BRL 5,000`
`Block high`	`Deny high-value weekend transactions`
`Pix rule`	`Review Pix transfers to new recipients`

Expression design

Keep expressions simple - Complex logic is harder to maintain
Use scopes for filtering - Don’t repeat scope conditions in expressions
Test edge cases - Consider boundary values and null fields

Lifecycle management

Start in DRAFT - Test before activating
Return to DRAFT before editing the expression - The expression is immutable in ACTIVE and INACTIVE; move the rule to DRAFT via POST /v1/rules/{id}/draft to edit, then reactivate
Archive unused rules - Keep audit trail intact
Delete only when certain - Deletion is permanent

Monitoring

Review matched rules - Check which rules are triggering
Monitor DENY rates - High deny rates may indicate overly aggressive rules
Audit regularly - Ensure rules still align with business requirements

Common pitfalls when working with rules:

“I edited the expression but the change didn’t take effect.” The expression is immutable in ACTIVE and INACTIVE states. Move the rule back to DRAFT via POST /v1/rules/{id}/draft, edit, then reactivate. INACTIVE alone is not enough.
“My rule is ACTIVE but another Tracer instance isn’t evaluating it yet.” Activation takes effect right away on the instance that served the activate call. When you run several instances behind a load balancer, the others pick the change up on their next rule sync (RULE_SYNC_POLL_INTERVAL_SECONDS, default 10). Deactivation propagates the same way. Plan integration tests around that gap when the calls can land on different instances.
“I want to delete an ACTIVE rule.” You can’t — POST /v1/rules/{id}/deactivate first, then DELETE /v1/rules/{id}. This forces a visible step where the rule stops affecting traffic before it disappears from listings.
“My empty scope {} is being rejected with error code 0358.” Every scope object must have at least one field set. To run a rule globally (against every transaction), omit the scopes array entirely — don’t pass {}.

Quick reference

Key endpoints, actions, and status information.

Endpoints

Operation	Method	Endpoint
Create rule	POST	`/v1/rules`
List rules	GET	`/v1/rules`
Get rule	GET	`/v1/rules/{id}`
Update rule	PATCH	`/v1/rules/{id}`
Delete rule	DELETE	`/v1/rules/{id}`
Activate rule	POST	`/v1/rules/{id}/activate`
Deactivate rule	POST	`/v1/rules/{id}/deactivate`
Draft rule	POST	`/v1/rules/{id}/draft`

Statuses

Status	Evaluated	Editable	Can delete
`DRAFT`	No	Yes	Yes
`ACTIVE`	Yes	Partial (expression immutable)	No (deactivate first)
`INACTIVE`	No	Partial (expression immutable; return to DRAFT first)	Yes
`DELETED`	No	No	N/A

Overview

Guides

Console

Operations

Why use the rules engine

What is the rules engine

How it works

Evaluation pattern

Core concepts

Rules

Expressions

Expression examples by use case

Amount-based rules

Merchant-based rules

Account-based rules

Combined conditions

Time-based rules

Using metadata

Actions

Scopes

Rule lifecycle

States

Transitions

Create a rule

Activate and deactivate rules

List and query rules

Query parameters

Get a specific rule

Update a rule

Delete a rule

Best practices

Naming

Expression design

Lifecycle management

Monitoring

Quick reference

Endpoints

Statuses

​Why use the rules engine

​What is the rules engine

​How it works

​Evaluation pattern

​Core concepts

​Rules

​Expressions

​Expression examples by use case

​Amount-based rules

​Merchant-based rules

​Account-based rules

​Combined conditions

​Time-based rules

​Using metadata

​Actions

​Scopes

​Rule lifecycle

​States

​Transitions

​Create a rule

​Activate and deactivate rules

​List and query rules

​Query parameters

​Get a specific rule

​Update a rule

​Delete a rule

​Best practices

​Naming

​Expression design

​Lifecycle management

​Monitoring

​Quick reference

​Endpoints

​Statuses

Why use the rules engine

What is the rules engine

How it works

Evaluation pattern

Core concepts

Rules

Expressions

Expression examples by use case

Amount-based rules

Merchant-based rules

Account-based rules

Combined conditions

Time-based rules

Using metadata

Actions

Scopes

Rule lifecycle

States

Transitions

Create a rule

Activate and deactivate rules

List and query rules

Query parameters

Get a specific rule

Update a rule

Delete a rule

Best practices

Naming

Expression design

Lifecycle management

Monitoring

Quick reference

Endpoints

Statuses