Segments

Segments let you group customers based on behavior, attributes, and rules. Use segments to target content variants, run experiments, and understand your audience.

Overview

A segment is a named group of customers defined by rules. Customers automatically enter or leave segments as their attributes and behavior change.

VIP Customers
  Rule: Total spend > $500
  Rule: Order count > 5
  Result: 142 customers match

Key Concepts

• Rules define who belongs to a segment using conditions on customer attributes and behavior
• Evaluation modes control whether membership is checked in realtime or in batch
• Manual membership lets you explicitly add or exclude customers
• Nested segments allow rules that reference other segments

In the Admin

Creating a Segment

1. Go to Settings > Segments
2. Click Create Segment
3. Configure:
   • Name: “VIP Customers”
   • Key: vip-customers (auto-generated from name)
   • Description: optional explanation
   • Rules: define matching conditions
   • Evaluation Mode: realtime or batch
4. Click Save

Building Rules

Segment rules use the same expression system as targeting rules. Combine conditions with AND/OR logic.

Customer Attributes

• Email, name, tags
• Total spend, order count
• Account creation date
• Email verification status

Behavioral Data

• Markets visited (UK, US, etc.)
• Devices used (mobile, desktop, tablet)
• Locales seen
• Pages and content viewed
• First seen / last seen dates

Synced External Data

Data from connected extensions (e.g., Shopify order history, total spend, tags) is available via synced.* context paths in rule conditions. Any extension that populates synced metadata is automatically available.

Manual Membership

Explicitly add customers to a segment via the admin UI. Combine manual members with rule-based evaluation:

Example Rules

High-Value Customers:

Total spend > $500 AND Order count > 5

Mobile-First Users:

Primary device = mobile AND Total resolutions > 10

Recent Visitors:

Last seen within 7 days AND Has visited path "/products"

Evaluation Modes

Using Segments

For Variant Targeting

Segments are commonly used in targeting rules to show different content to different customer groups:

Priority 20: Segment is "vip-customers"  ->  VIP variant
Priority 10: Device is mobile            ->  Mobile variant
Priority 0:  Default                     ->  Standard variant

For Experiments

Experiments can target specific segments — run an A/B test only on VIP customers, test a new layout for first-time customers, or experiment with content for a specific market segment.

Set the experiment’s targeting type to segment and reference the segment by key:

{
  "targeting": { "type": "segment", "segmentKey": "vip-customers" },
  ...
}

Segment membership is evaluated on every content resolution, so customers automatically enter and exit a segment-targeted experiment as their membership changes (e.g. when they cross a spending threshold). Anonymous visitors don’t match segment-targeted experiments — segments are customer-bound, so the visitor needs to be signed in. Use rule-based targeting if you want to gate on context (device, locale) for anonymous visitors.

Nested Segments

Segment rules can reference other segments. For example, “customer is in segment VIP AND NOT in segment Opted-Out.” Foir validates segment rules on save and rejects any configuration that would create a circular reference.

Customer Opt-Out

Customers can opt out of specific segments if your application supports it. When a customer opts out, they are excluded from that segment regardless of whether they match the rules.

Via the CLI

# List all segments
foir segments list
 
# Get a segment by ID or key
foir segments get <id>
foir segments get vip-customers
 
# Create a segment
foir segments create --data '{
  "name": "VIP Customers",
  "key": "vip-customers",
  "rules": {
    "type": "and",
    "conditions": [
      { "path": "totalSpend", "operator": "greaterThan", "value": 500 },
      { "path": "orderCount", "operator": "greaterThan", "value": 5 }
    ]
  },
  "evaluationMode": "realtime"
}'
 
# Update a segment
foir segments update <id> --data '{"name": "Premium Customers"}'
 
# Delete a segment
foir segments delete <id>
 
# Preview which customers match a set of rules (without saving)
foir segments preview --data '{
  "rules": {
    "type": "and",
    "conditions": [
      { "path": "totalSpend", "operator": "greaterThan", "value": 1000 }
    ]
  }
}'
 
# Test whether a specific customer matches a segment
foir segments test <segmentId> <customerId>

Via the API

Querying Segment Information

query GetSegment {
  segmentByKey(key: "vip-customers") {
    id
    key
    name
    description
    memberCount
    evaluationMode
    isActive
  }
}

Using Segments in Content Resolution

Segments feed into targeting rules. When resolving content, segment membership is evaluated as part of the targeting context. See Targeting & Context for how context values are passed and resolved.

Best Practices

• Start simple — begin with a few key segments before building complex rules.
• Use meaningful keys — vip-customers is clearer than seg-001.
• Monitor membership — check that segment sizes match your expectations in the admin dashboard.
• Choose evaluation mode carefully — use realtime for critical targeting, batch for large segments.
• Document your segments — add descriptions so your team understands each segment’s purpose.
• Combine with targeting — segments are most powerful when used in variant targeting and experiments.