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 compares a single billing metric against a threshold with a comparison operator. On each evaluation pass, every customer that satisfies the rule has a configured tag applied; customers that no longer satisfy it have the tag removed. Reference that tag from a promotion, an approval workflow, or a dunning policy to target the cohort.
Why this matters. Customer cohorts surface in too many places (promotions, dunning, approvals, analytics) to redefine inline each time - centralizing the rule is what keeps targeting consistent across teams. Kontorion's segment rules are metric-threshold rules evaluated on a schedule, and because they materialize membership onto an ordinary tag, every workflow that already understands tags can target the cohort without knowing how it was derived. The same primitive supports a high-spend cohort routed to manual approval workflows, a low-activity cohort eligible for a win-back promotion, and a tenured-customer cohort recognized in dunning.
When to use a segment
- Reusable targeting - one "high monthly spend" rule applies a tag that multiple promotions and notifications can reference
- Cohort-driven workflows - approval workflows that only apply to a specific customer tier
- Maintained membership - the scheduled pass keeps the tag in sync as customers cross the threshold; no manual re-tagging needed
For one-off targeting (a single promotion's eligibility), inline conditions on that object are fine. Segments pay off when the same cohort appears in three or more places.
Anatomy
A segment rule is a flat comparison: a metric, an operator, a numeric value, and the applied_tag_id to maintain on matching customers. An optional evaluation_schedule controls how often the rule runs, and is_active toggles it on or off.
Code
Metrics
A rule compares exactly one of these metrics:
| Metric | Meaning |
|---|---|
monthly_spend | Invoiced amount over the trailing month |
total_spend | Lifetime invoiced amount |
subscription_count | Number of active subscriptions |
active_days | Days since the customer was created |
Operators
| Operator | Meaning |
|---|---|
eq | Equals |
gt, gte | Greater than / greater than or equal |
lt, lte | Less than / less than or equal |
The metric value and the threshold value are both numeric; value is sent as a decimal string (for example "5000.00"). There are no membership, presence, regex, or range operators, and rules cannot be combined with boolean logic - each rule is a single comparison.
Creating a segment rule
Code
The response wraps the created SegmentRule in a data envelope.
Listing and managing rules
Code
The list endpoint returns the segment rules themselves, not their members. There is no membership endpoint - cohort membership is exposed through the applied tag, so to find matching customers query customers by that tag.
Scheduled evaluation
A segment rule does not compute membership on demand. A scheduled evaluation pass walks the active rules for each organization and, for every customer, compares the metric against the threshold:
- If the customer meets the rule and is not already tagged, the
applied_tag_idis applied. - If the customer no longer meets the rule and is currently tagged, the
applied_tag_idis removed.
Membership is therefore materialized onto the tag between passes - the tag reflects the customer's state as of the last evaluation, not the present moment. A workflow that reads the tag is reading that materialized snapshot. The evaluation_schedule on the rule controls how often the pass runs, and is_active: false removes a rule from the pass without deleting it.
Performance
Each pass loads the active rules and the customer set per organization, then queries the chosen metric per customer (trailing-month and lifetime spend from invoices, active subscription counts, or age in days). Cost scales with the number of customers times the number of active rules in an organization, so prefer fewer, well-targeted rules and a schedule no tighter than the cohort actually needs.
Next steps
- Promotions - target eligibility by the tag a segment rule applies
- Approval Workflows - tag-gated triggers
- API Reference - Tags - the tag a segment rule applies to matching customers
- API Reference - Segment Rules