Variant Catalog

The Variant Catalog is a centralized library of reusable targeting rules. Instead of defining targeting rules individually on each content variant, create catalog entries that can be referenced across multiple records. When you update a catalog entry, all variants using it automatically get the updated rules.

Overview

The catalog solves a common problem: when multiple pages need the same targeting rules (e.g., “show to VIP customers”), defining those rules individually on each variant is tedious and error-prone. The catalog lets you define the rules once and reuse them everywhere.

How It Works

Create catalog entries with targeting rules (e.g., “VIP Customers”, “UK Mobile Users”)
Assign catalog entries to variants — the variant inherits the catalog’s targeting rules and priority
Update catalog entries — changes propagate to all variants using that entry


Variant Catalog
  -- "VIP Customers"  (Priority 30, rules: segment is VIP)
  -- "UK Mobile"      (Priority 20, rules: market = UK AND device = mobile)
  -- "Mobile Users"   (Priority 10, rules: device = mobile)
  -- "Default"        (Priority 0, no rules -- always matches)

Homepage
  -- Variant: "VIP Homepage"    -> uses catalog: "VIP Customers"
  -- Variant: "UK Mobile Home"  -> uses catalog: "UK Mobile"
  -- Variant: "Default"         -> uses catalog: "Default"

Product Listing
  -- Variant: "VIP Products"    -> uses catalog: "VIP Customers"  (same rules)
  -- Variant: "Default"         -> uses catalog: "Default"

Catalog Entry Properties

Property	Description
`key`	Unique identifier (lowercase, hyphens allowed). Cannot be changed after creation.
`name`	Display name
`description`	Optional description of what this entry targets
`targetingRules`	Expression-based targeting conditions
`priority`	Evaluation order — higher priority entries are checked first
`isDefault`	Whether this is the fallback entry (no rules, matches all)
`isActive`	Whether the entry is available for use

Catalog vs Custom Rules

When editing a variant’s targeting, you have two options:

Catalog Mode (recommended) — Select a catalog entry. Rules are centrally managed and changes propagate automatically. Use this when two or more variants need the same targeting.

Custom Rules Mode — Define rules directly on the variant. Rules are unique to that variant and not affected by catalog changes. Use this for one-off targeting requirements.

You can switch between modes at any time.

In the Admin

Creating a catalog entry

Go to Variant Catalog
Click Create Entry
Configure:
- Key: vip-customers (unique identifier)
- Name: “VIP Customers”
- Description: Optional explanation of the targeting intent
- Priority: Evaluation order (higher = checked first)
- Targeting Rules: Define conditions using the visual rule builder
Click Save

Using catalog entries in variants

Open a record and go to the Variants panel
Add or edit a variant
In the targeting section, choose From Catalog
Select the catalog entry to inherit its rules

Priority System

The variant resolution system uses priority-based, first-match-wins evaluation:

Variants are sorted by priority (highest first)
Each variant’s targeting rules are evaluated against the request context
The first variant whose rules match is returned
If no variants match, the default variant is returned

Recommended priority ranges

Priority	Use Case	Example
50+	Override/emergency	Temporary promotions, urgent updates
20-50	Specific targeting	VIP customers, combined conditions
10-20	General targeting	Market-specific, device-specific
0	Default/fallback	Standard content for everyone

Example priority setup


Priority 50: VIP UK Mobile Users        (most specific)
Priority 30: VIP Customers (any market)
Priority 20: UK Mobile Users
Priority 10: UK Users
Priority 5:  Mobile Users
Priority 0:  Default (fallback)

Higher priority means more specific targeting. The first match wins, so “VIP UK Mobile Users” at priority 50 is evaluated before “Mobile Users” at priority 5.

Default Catalog Entry

Every project has a default catalog entry that serves as the fallback when no other variant matches:

Key: default
Priority: 0
Rules: None (matches all requests)
Cannot be deleted

The default entry is automatically created for each project.

Via the CLI

List catalog entries


foir variant-catalog list

Get a catalog entry

By ID:


foir variant-catalog get vc_abc123

By key:


foir variant-catalog get vip-customers

Create a catalog entry


foir variant-catalog create --data '{
  "key": "vip-customers",
  "name": "VIP Customers",
  "description": "Targets customers in the VIP segment",
  "priority": 30,
  "targetingRules": {
    "operator": "AND",
    "conditions": [
      { "dimension": "segment", "operator": "equals", "value": "vip" }
    ]
  }
}'

Update a catalog entry


foir variant-catalog update vc_abc123 --data '{
  "name": "VIP Customers",
  "priority": 35
}'

Delete a catalog entry


foir variant-catalog delete vc_abc123

Best Practices

Use the catalog for any targeting rules shared by two or more variants. Central management prevents rules from drifting out of sync.
Use descriptive keys like vip-uk-mobile rather than generic names like rule-001.
Space priorities clearly (0, 10, 20, 30…) to leave room for future entries without renumbering.
Use custom rules sparingly. They are useful for one-off experiments but make it harder to maintain a consistent targeting strategy.
Add descriptions to each catalog entry explaining what it targets and why.
Deactivate entries you are no longer using instead of deleting them, in case you need them again.