Routing rules

Routing rules

By default, every event you ingest is fanned out to every platform you've connected. That's the right behavior for most events — page_view and view_item are cheap signal everywhere. But some events don't belong everywhere. Purchases sent to LinkedIn pollute your ROAS math. Leads sent to Pinterest don't match any optimization goal.

Rules let you override fan-out for specific (event_name, platforms[]) pairs.

Mental model

Think of rules as an allowlist keyed by event name. When an event arrives, the consumer worker runs this check:

1. Load all rules for (merchant_id, event_name, enabled=true).
2. If zero rules match → fan out to every connected platform (default behavior, unchanged).
3. If one or more rules match → union all their platforms[] arrays and fan out only to that set. Platforms in the rule that aren't connected are silently skipped.

Multiple rules for the same event are additive. A rule for purchase → [meta, google_ads] plus another for purchase → [ga4] is equivalent to one rule for purchase → [meta, google_ads, ga4].

Creating a rule

1. Open Rules in the dashboard sidebar.
2. Click + NEW RULE.
3. Give it a name you'll recognize ("High-value purchases — Meta only"), pick an event name from the dropdown or type a custom name, and check the platforms it should allow.
4. Click CREATE RULE.

The rule activates immediately. Events arriving at the consumer within the next few seconds use it.

Example — paid-platform-only purchases

You run paid Meta + Google Ads acquisition and use GA4 for reporting. You don't want purchase events flooding your email/affiliate platforms.

Rule name: Purchases to paid platforms only
Event:     purchase
Platforms: [meta, google_ads, ga4]
Enabled:   true

After saving: every purchase event that hits the ingestion worker will only fan out to Meta, Google Ads, and GA4. Your Klaviyo, Awin, Criteo integrations won't receive it. All other event types (view_item, add_to_cart, etc.) still fan out to every connected platform.

Enabling and disabling

The ENABLED / DISABLED toggle on each row does an optimistic update — the UI reflects the new state instantly, then the server confirms. If the server rejects the change (network error, etc.), the toggle reverts and an error banner appears.

Disabled rules don't apply. The consumer only loads rules with enabled = true.

Deleting

The DELETE button prompts for confirmation, then removes the rule permanently. Events in flight when you delete a rule use whichever state was active when the event entered the queue.

Limits

• Up to 200 rules per merchant (soft limit; contact support if you hit it).
• Platforms in a rule are matched by string equality against the 12 canonical IDs: meta, tiktok, google_ads, ga4, pinterest, snapchat, linkedin, reddit, criteo, awin, taboola, outbrain.
• Event names in a rule are matched exactly. Use the canonical name the classifier settles on (e.g. add_to_cart, not AddToCart — the pixel normalizes on ingest, but the rule matches post-normalization).

Audit trail

Every event processed by the consumer stores the matching rule IDs in custom_data._rule_ids. If you export events to a warehouse (Scale tier), you can trace any delivery decision back to the rule that shaped it.

Next steps

• Replay a filtered event — the REPLAY action in the event detail rail re-enqueues through the same rule engine
• Event classifier reference — how non-canonical event names get mapped to canonical ones before rules match