Segments

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

Segments are now context dimensions with sourceType: 'segment'. Membership is a rule (evaluationRules) evaluated fresh on every request into segment.<key> — there is no precomputed membership table or evaluation mode. Author them in the admin Context Dimensions editor or as code with contextDimensions:.

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

Segment membership is evaluated on every content resolution, so customers automatically enter and exit segment-targeted variants as their membership changes (e.g. when they cross a spending threshold). Anonymous visitors never match segment rules — segments are customer-bound, so the visitor must be signed in. Use context-based targeting (device, locale) to differentiate anonymous traffic.

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": "group",
    "logicalOperator": "AND",
    "conditions": [
      {
        "type": "condition",
        "left": { "type": "field", "path": "totalSpend" },
        "operator": "greater_than",
        "right": { "type": "literal", "value": 500 }
      },
      {
        "type": "condition",
        "left": { "type": "field", "path": "orderCount" },
        "operator": "greater_than",
        "right": { "type": "literal", "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": "group",
    "logicalOperator": "AND",
    "conditions": [
      {
        "type": "condition",
        "left": { "type": "field", "path": "totalSpend" },
        "operator": "greater_than",
        "right": { "type": "literal", "value": 1000 }
      }
    ]
  }
}'
 
# Test whether a specific customer matches a segment
foir segments test <segmentId> <customerId>

Segments and the public API

Segments are defined and managed through the admin app and CLI — there is no public GraphQL query for creating or editing them. There is, however, a read-only query for membership: customerSegmentMemberships(customerId: String!) returns the list of segment keys a given customer currently belongs to.

query {
  customerSegmentMemberships(customerId: "cust_123")
}

Segments feed into targeting rules: when content is resolved, segment membership is evaluated as part of the targeting context, and the matching variant is returned. 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.
• Test membership — use foir segments test <segmentId> <customerId> to confirm a specific customer resolves into a segment before you rely on it in targeting.
• 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.