Copy page

Customer Segments

Status: Roadmap. The conceptual model is documented here. Public REST endpoints described below are not yet wired into the API router (no handler is registered for these paths). The page describes the planned shape; treat any code samples as illustrative pending implementation.

A segment rule defines a predicate over customer attributes (and adjacent objects like subscriptions, invoices, wallets). The matching cohort is computed lazily - segments aren't materialized lists, they're queries. Reference a segment from a promotion, an approval workflow, or a dunning policy and the runtime evaluates the predicate at the moment it matters.

Why this matters. Customer cohorts surface in too many places (promotions, dunning, approvals, analytics) to redefine inline each time - centralizing the predicate is what keeps targeting consistent across teams. Kontorion's segment rules are predicate-driven and lazily evaluated, so membership stays correct as customer state changes without any batch refresh, and the same definition is reused across every workflow that needs it. The same primitive supports an EU enterprise cohort eligible for a regional promotion, a trial-ending cohort triggering a renewal email sequence, a high-spend cohort routed to manual approval workflows, and an analytics filter for slicing MRR by industry vertical.

When to use a segment

• Reusable targeting - the same "EU enterprise customers" cohort across multiple promotions and notifications
• Cohort-driven workflows - approval workflows that only apply to a specific customer tier
• Dynamic membership - membership recomputes as customers update; no batch refresh needed

For one-off targeting (a single promotion's eligibility), inline conditions on that object are fine. Segments pay off when the same predicate appears in three or more places.

Anatomy

A segment carries a name, a description, and a predicate - a tree of conditions over customer fields and joined objects:

Code
{
  "name": "EU enterprise active",
  "description": "Customers in the EU with a subscription on plan_enterprise and active status",
  "predicate": {
    "and": [
      { "field": "customer.billing_address.country_code", "operator": "in", "value": ["DE", "FR", "NL", "ES", "IT"] },
      { "field": "subscription.plan_id", "operator": "eq", "value": "plan_enterprise" },
      { "field": "subscription.status", "operator": "eq", "value": "ACTIVE" }
    ]
  }
}

Operators

Operator	Meaning
eq, neq	Equals / not equals
in, not_in	Membership
gt, gte, lt, lte	Numeric / temporal comparison
exists, not_exists	Field presence
matches	Regex (anchored)
between	Inclusive range

Predicates compose with and, or, not.

Joinable scopes

Segment predicates can reference fields on:

• The customer itself
• Their subscriptions (any active, all active)
• Their invoices (last N, in period)
• Their wallet balances
• Their custom field values
• Their verification statuses

For one-to-many relationships, qualify the join with any, all, count:

Code
{ "field": "subscription.status", "operator": "eq", "value": "ACTIVE", "join": "any" }

Creating a segment rule

Code
curl -X POST /v1/segment-rules \
  -d '{
    "name": "Trials started in early March",
    "predicate": {
      "and": [
        { "field": "subscription.created_at", "operator": "between", "value": ["2025-03-01", "2025-03-15"] },
        { "field": "subscription.status", "operator": "eq", "value": "TRIALING" }
      ]
    }
  }'

Querying membership

Code
GET /v1/segment-rules/{id}/members?limit=100

Returns the current matching customer IDs with cursor pagination. For very large segments, prefer streaming the export.

Live evaluation in workflows

Where a promotion or approval workflow references a segment, the runtime evaluates the predicate at the moment the action would apply (invoice generation, redemption attempt). A customer who falls out of the segment between configuration time and application time will not match. This means segments stay in sync without explicit refresh, but it also means cached membership is not the source of truth - always re-evaluate before relying on it.

Performance

Predicates are translated to indexed SQL where possible. Fields backed by indexes (status enums, country codes, plan IDs) evaluate in O(log n); regex matches and full-text fields fall back to scans. The dashboard surfaces evaluation cost per segment so you can spot slow predicates before they bite at runtime.

Next steps

• Promotions - segment-targeted eligibility
• Approval Workflows - segment-gated triggers
• Custom Fields - typed customer fields you can target with segments
• API Reference - Segment Rules