Segments

Segments define audiences from pass attributes, custom fields, and user behavior. They are evaluated on demand (no stored membership) and are the primary way to target campaigns.

Auth: All segment endpoints require a Bearer token. Workspace-scoped routes (/workspace/:workspaceId/segments) and entity routes (/segments/:id/...) require the caller to be a member of the owning workspace. The custom-field helper routes resolve the workspace from the workspace_id query parameter; the filter-test and union routes resolve it from the request body.

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Segment Structure

interface Segment {
  id: string;
  workspace_id: string;
  name: string;
  description?: string;
  filters: SegmentFilter[];
}

interface SegmentFilter {
  id?: string;
  filter_type:
    | 'all'
    | 'template'
    | 'project'
    | 'custom_field'
    | 'client_custom_field'
    | 'wallet_balance'
    | 'tier'
    | 'event_count'
    | 'event_sum'
    | 'field_sum'
    | 'event_recency';
  filter_config: Record<string, any>;
}

Multiple filters on a segment are combined with AND logic. See Filters for each filter_type's config.

Reference Pages

• CRUD & evaluation — list, create, get, update, delete, duplicate, preview, passes, clients, calculate, client-count
• Filters & helpers — filter types, test-filters, union, custom-field name/value discovery

Endpoint Index

Method	Endpoint	Page
GET	/wallethero-api/workspace/:workspaceId/segments	crud
POST	/wallethero-api/workspace/:workspaceId/segments	crud
GET	/wallethero-api/segments/:id	crud
PATCH	/wallethero-api/segments/:id	crud
DELETE	/wallethero-api/segments/:id	crud
POST	/wallethero-api/segments/:id/duplicate	crud
POST	/wallethero-api/segments/:id/calculate	crud
GET	/wallethero-api/segments/:id/preview	crud
GET	/wallethero-api/segments/:id/passes	crud
GET	/wallethero-api/segments/:id/clients	crud
GET	/wallethero-api/segments/:id/client-count	crud
POST	/wallethero-api/segments/test-filters	filters
POST	/wallethero-api/segments/union/client-ids	filters
GET	/wallethero-api/passes/custom-fields	filters
GET	/wallethero-api/passes/custom-fields/:fieldName/values	filters

SDK Example

import { WalletHero } from "@wallethero/sdk";
const wh = new WalletHero({ apiToken: "YOUR_TOKEN" });

const { data: segment } = await wh.segments.create({
  workspace_id: "WORKSPACE_ID",
  name: "High Value VIPs",
  filters: [
    {
      filter_type: "custom_field",
      filter_config: {
        custom_field_filters: {
          tier: { operator: "_in", value: ["Gold", "Platinum"] },
        },
      },
    },
  ],
});

const size = await wh.segments.calculateSize(segment.id);
console.log(`Segment has ${size.total} clients`);