Segments

Target campaigns at specific groups of members. A campaign with targetSegmentIds set will only fire for members who belong to at least one of those segments.

TypeMembers added byRefresh
STATICManual API callsOn demand
DYNAMICRule evaluation against member statsManual or scheduled (nightly)

Endpoints

GET
/tenants/{tenantId}/segments

List all segments (STATIC and DYNAMIC).

POST
/tenants/{tenantId}/segments

Create a segment. type: STATIC or DYNAMIC. DYNAMIC requires a rules tree.

POST
/tenants/{tenantId}/segments/preview

Dry-run rule evaluation — returns matchCount and sample member IDs without writing.

POST
/tenants/{tenantId}/segments/refresh

Refresh all DYNAMIC segments. Re-evaluates rules against current member stats.

GET
/tenants/{tenantId}/segments/{segmentId}

Get a segment by ID.

PATCH
/tenants/{tenantId}/segments/{segmentId}

Update segment name, description, or DYNAMIC rules.

DELETE
/tenants/{tenantId}/segments/{segmentId}

Delete a segment. Campaigns targeting this segment will skip the check.

GET
/tenants/{tenantId}/segments/{segmentId}/members

List segment members with their stats. Keyset paginated.

POST
/tenants/{tenantId}/segments/{segmentId}/members

Manually add a member to a STATIC segment.

DELETE
/tenants/{tenantId}/segments/{segmentId}/members/{id}

Remove a member from a STATIC segment.

POST
/tenants/{tenantId}/segments/{segmentId}/refresh

Refresh a single DYNAMIC segment.

DYNAMIC Rule Fields

Condition operators: eq neq gt gte lt lte. Rules support AND / OR operator nodes for complex logic.

fieldtypeDescription
statestringactive | suspended | anonymized
points_balanceintegerCurrent spendable balance
lifetime_pointsintegerCumulative points ever earned
total_transaction_countintegerTotal earn transactions
total_spend_centsintegerTotal basket spend in cents
avg_order_value_centsintegerAverage basket value
txn_count_30dintegerTransactions in last 30 days
spend_cents_30dintegerSpend in last 30 days (cents)
txn_count_90dintegerTransactions in last 90 days
spend_cents_90dintegerSpend in last 90 days (cents)
txn_count_365dintegerTransactions in last 365 days
spend_cents_365dintegerSpend in last 365 days (cents)
rfm_recency1–5RFM recency quintile (5 = most recent)
rfm_frequency1–5RFM frequency quintile (5 = most frequent)
rfm_monetary1–5RFM monetary quintile (5 = highest spend)

Create a dynamic segment

cURL
curl -X POST "https://loyalty-engine-production-e5cb.up.railway.app/v1/tenants/$TENANT_ID/segments" \
  -H "X-API-Key: sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active High-Spenders (30 days)",
    "type": "DYNAMIC",
    "rules": {
      "operator": "AND",
      "conditions": [
        { "field": "spend_cents_30d", "op": "gte", "value": 50000 },
        { "field": "txn_count_30d",   "op": "gte", "value": 3 }
      ]
    }
  }'

Target a campaign at the segment

cURL
curl -X PATCH "https://loyalty-engine-production-e5cb.up.railway.app/v1/tenants/$TENANT_ID/campaigns/$CAMPAIGN_ID" \
  -H "X-API-Key: sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetSegmentIds": ["segment-uuid-1", "segment-uuid-2"]
  }'
Segments — API Reference