Tiers

The Tiers API manages a workspace's loyalty tier system: the tier set (the container that defines evaluation conditions and downgrade rules), the individual tiers within it, client tier assignments and progress, dry-run previews, and bulk recalculation / resync jobs.

All endpoints are mounted under the /wallethero-api prefix and are workspace-scoped: the caller must authenticate with a Bearer token and be a member of the workspace in the URL path (enforced by createWorkspaceGuard).

Conventions:

A workspace has at most one tier set. Tier-set-dependent endpoints return 400 (InvalidPayloadError: "No tier set configured for this workspace") if none exists; the GET endpoints instead return { "data": null } or { "data": [] }.
Mutations that affect tier definitions (update tier set, update/delete/reorder tier) may enqueue an async resync job and return its id as resync_job_id (or null).
Tier condition_values is a map keyed by condition type (total_earned, total_spending, transaction_count) to a numeric threshold.

Get Tier Set

GET /wallethero-api/workspace/:workspaceId/tiers/set

Returns the workspace's tier set together with its tiers. Returns { "data": null } if no tier set is configured.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/set" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": {
    "id": "8f1c...",
    "workspace_id": "WORKSPACE_ID",
    "name": "Loyalty Program",
    "active": true,
    "conditions": [
      { "type": "total_earned" },
      { "type": "total_spending" }
    ],
    "downgrade_config": { "lookback_days": 365 },
    "tiers": [
      { "id": "a1...", "name": "Bronze", "sort_order": 0, "kind": "auto", "condition_values": { "total_spending": 0 } }
    ]
  }
}

SDK

typescript

const { data: tierSet } = await wh.tiers.getTierSet(workspaceId);

Create Tier Set

POST /wallethero-api/workspace/:workspaceId/tiers/set

Creates the tier set for the workspace.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Request Body

Field	Type	Required	Default	Description
`name`	`string` (1–255)	Yes	—	Tier set name
`active`	`boolean`	No	`true`	Whether the tier set is active
`conditions`	`array` of condition definitions	No	`[]`	Evaluation conditions (see below)
`downgrade_config`	`object`	No	`{}`	Downgrade rules

workspace_id is taken from the path and injected automatically; you do not need to send it.

Condition definition object:

Field	Type	Required	Description
`type`	`"total_earned" \| "total_spending" \| "transaction_count"`	Yes	Metric the condition measures
`wallet_type_code`	`string`	No	Only allowed when `type` is `total_earned`; scopes the metric to a specific wallet type

downgrade_config object:

Field	Type	Required	Description
`lookback_days`	`number` (int ≥ 0)	No	Rolling window used when evaluating downgrades

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/set" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loyalty Program",
    "active": true,
    "conditions": [{ "type": "total_earned" }, { "type": "total_spending" }],
    "downgrade_config": { "lookback_days": 365 }
  }'

Response (201)

json

{
  "data": {
    "id": "8f1c...",
    "workspace_id": "WORKSPACE_ID",
    "name": "Loyalty Program",
    "active": true,
    "conditions": [{ "type": "total_earned" }, { "type": "total_spending" }],
    "downgrade_config": { "lookback_days": 365 }
  }
}

SDK

typescript

const { data: tierSet } = await wh.tiers.createTierSet(workspaceId, {
  name: "Loyalty Program",
  active: true,
  conditions: [{ type: "total_earned" }, { type: "total_spending" }],
  downgrade_config: { lookback_days: 365 },
});

Update Tier Set

PATCH /wallethero-api/workspace/:workspaceId/tiers/set

Updates the workspace's tier set. Changing conditions may enqueue a resync job, whose id is returned as resync_job_id.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Request Body

All fields optional; send only what you want to change.

Field	Type	Description
`name`	`string` (1–255)	Tier set name
`active`	`boolean`	Whether the tier set is active
`conditions`	`array` of condition definitions	Replaces the condition list
`downgrade_config`	`object` (`lookback_days`)	Downgrade rules

Example Request

bash

curl -X PATCH "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/set" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "downgrade_config": { "lookback_days": 180 } }'

Response (200)

json

{
  "data": {
    "id": "8f1c...",
    "name": "Loyalty Program",
    "active": true,
    "downgrade_config": { "lookback_days": 180 }
  },
  "resync_job_id": "job_abc123"
}

SDK

typescript

const { data: tierSet } = await wh.tiers.updateTierSet(workspaceId, {
  downgrade_config: { lookback_days: 180 },
});

Delete Tier Set

DELETE /wallethero-api/workspace/:workspaceId/tiers/set

Deletes the workspace's tier set (and its tiers).

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Example Request

bash

curl -X DELETE "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/set" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{ "message": "Tier set deleted successfully" }

SDK

No SDK method — call the REST endpoint directly.

List Tiers

GET /wallethero-api/workspace/:workspaceId/tiers

Lists the tiers in the workspace's tier set, ordered by sort_order. Returns { "data": [] } if no tier set exists.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": [
    {
      "id": "a1...",
      "tier_set_id": "8f1c...",
      "workspace_id": "WORKSPACE_ID",
      "name": "Bronze",
      "sort_order": 0,
      "kind": "auto",
      "condition_values": { "total_spending": 0 },
      "benefits": [],
      "color": "#cd7f32",
      "pass_sync_config": {}
    }
  ]
}

SDK

typescript

const { data: tiers } = await wh.tiers.listTiers(workspaceId);

List Tier Clients

GET /wallethero-api/workspace/:workspaceId/tiers/clients

Lists clients with their current tier assignment and per-condition values, with filtering, search, and pagination. Used to populate tier client lists in the UI.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Query Parameters

Parameter	Type	Required	Default	Description
`tier_id`	`string (UUID)` or `"untiered"` or `"loyalty_disabled"`	No	—	Filter by tier. `"untiered"` returns clients with no tier; `"loyalty_disabled"` returns clients with loyalty disabled
`search`	`string`	No	—	Name/email search
`limit`	`number`	No	—	Page size
`offset`	`number`	No	—	Pagination offset
`pass_template_id`	`string (UUID)`	No	—	Filter to clients on a specific pass template
`cf_<fieldName>`	`string`	No	—	Custom-field filter: any query param prefixed `cf_` filters by that custom field (e.g. `cf_city=Warsaw`)

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/clients?tier_id=a1...&limit=50&offset=0&search=jane" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": [
    {
      "client_id": "c1...",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "tier_id": "a1...",
      "tier_name": "Bronze",
      "tier_color": "#cd7f32",
      "promoted_at": "2026-01-10T12:00:00Z",
      "manually_assigned": false,
      "condition_values": { "total_spending": 120 }
    }
  ],
  "meta": { "total": 1 }
}

SDK

typescript

const result = await wh.tiers.listTierClients(workspaceId, {
  tier_id: "a1...",
  search: "jane",
  limit: 50,
  offset: 0,
  custom_field_filters: { city: "Warsaw" },
});

Tier Client Counts

GET /wallethero-api/workspace/:workspaceId/tiers/client-counts

Returns a map of client counts keyed by tier id (plus buckets such as untiered / loyalty-disabled), for badge/summary displays.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/client-counts" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": {
    "a1...": 42,
    "b2...": 17,
    "untiered": 8
  }
}

SDK

typescript

const { data: counts } = await wh.tiers.getTierClientCounts(workspaceId);

Get Tier

GET /wallethero-api/workspace/:workspaceId/tiers/:id

Returns a single tier by id. The tier is scoped to the workspace; a 400 (InvalidPayloadError: "Tier not found") is returned if the id does not belong to the workspace.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier
`id`	`string (UUID)`	Tier identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/TIER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": {
    "id": "a1...",
    "tier_set_id": "8f1c...",
    "workspace_id": "WORKSPACE_ID",
    "name": "Gold",
    "sort_order": 2,
    "kind": "auto",
    "condition_values": { "total_spending": 1000 },
    "benefits": [{ "id": "b1", "label": "Free shipping" }],
    "color": "#ffd700",
    "pass_sync_config": {}
  }
}

SDK

typescript

const { data: tier } = await wh.tiers.getTier(workspaceId, tierId);

Create Tier

POST /wallethero-api/workspace/:workspaceId/tiers

Creates a tier inside the workspace's tier set.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Request Body

Field	Type	Required	Default	Description
`name`	`string` (1–255)	Yes	—	Tier name
`condition_values`	`object` (`Record<string, number>`)	Yes	—	Threshold per condition type, e.g. `{ "total_spending": 1000 }`
`description`	`string` (≤ 2000)	No	—	Tier description
`sort_order`	`number` (int ≥ 0)	No	`0`	Ordering / rank
`kind`	`"auto" \| "exclusive"`	No	`"auto"`	`auto` = threshold-based; `exclusive` = manually-assigned only
`benefits`	`array` of benefit objects	No	`[]`	Tier benefits (`{ id, label, value? }`)
`color`	`string` (`#RRGGBB`)	No	—	Hex color
`icon`	`string` (≤ 255)	No	—	Icon identifier
`pass_sync_config`	`object` (`field_name?`, `sync_value?`)	No	`{}`	Pass field sync config
`pass_template_id`	`string (UUID)` or `null`	No	—	Pass template to apply at this tier
`notification_config`	`object` or `null`	No	—	Promotion/demotion notification config (`send_on_promotion?`, `send_on_demotion?`, `promotion_body?` ≤ 2000, `demotion_body?` ≤ 2000)

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gold",
    "condition_values": { "total_spending": 1000 },
    "kind": "auto",
    "sort_order": 2,
    "color": "#ffd700",
    "benefits": [{ "id": "b1", "label": "Free shipping" }]
  }'

Response (201)

json

{
  "data": {
    "id": "a1...",
    "tier_set_id": "8f1c...",
    "workspace_id": "WORKSPACE_ID",
    "name": "Gold",
    "sort_order": 2,
    "kind": "auto",
    "condition_values": { "total_spending": 1000 },
    "benefits": [{ "id": "b1", "label": "Free shipping" }],
    "color": "#ffd700",
    "pass_sync_config": {}
  }
}

SDK

typescript

const { data: tier } = await wh.tiers.createTier(workspaceId, {
  name: "Gold",
  condition_values: { total_spending: 1000 },
  kind: "auto",
  sort_order: 2,
  color: "#ffd700",
  benefits: [{ id: "b1", label: "Free shipping" }],
});

Update Tier

PATCH /wallethero-api/workspace/:workspaceId/tiers/:id

Updates a tier. May enqueue a resync job, returned as resync_job_id.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier
`id`	`string (UUID)`	Tier identifier

Request Body

All fields optional; same shapes as Create Tier. Nullable fields (description, color, icon, pass_template_id, notification_config) may be set to null to clear them.

Field	Type	Description
`name`	`string` (1–255)	Tier name
`description`	`string` (≤ 2000) or `null`	Tier description
`sort_order`	`number` (int ≥ 0)	Ordering / rank
`kind`	`"auto" \| "exclusive"`	Assignment mode
`condition_values`	`object` (`Record<string, number>`)	Thresholds per condition type
`benefits`	`array` of benefit objects	Tier benefits
`color`	`string` (`#RRGGBB`) or `null`	Hex color
`icon`	`string` (≤ 255) or `null`	Icon identifier
`pass_sync_config`	`object`	Pass field sync config
`pass_template_id`	`string (UUID)` or `null`	Pass template to apply
`notification_config`	`object` or `null`	Promotion/demotion notification config

Example Request

bash

curl -X PATCH "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/TIER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "condition_values": { "total_spending": 1500 } }'

Response (200)

json

{
  "data": {
    "id": "a1...",
    "name": "Gold",
    "condition_values": { "total_spending": 1500 }
  },
  "resync_job_id": "job_abc123"
}

SDK

typescript

const { data: tier } = await wh.tiers.updateTier(workspaceId, tierId, {
  condition_values: { total_spending: 1500 },
});

Delete Tier

DELETE /wallethero-api/workspace/:workspaceId/tiers/:id

Deletes a tier. May enqueue a resync job, returned as resync_job_id.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier
`id`	`string (UUID)`	Tier identifier

Example Request

bash

curl -X DELETE "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/TIER_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "message": "Tier deleted successfully",
  "resync_job_id": "job_abc123"
}

SDK

typescript

await wh.tiers.deleteTier(workspaceId, tierId);

Reorder Tiers

POST /wallethero-api/workspace/:workspaceId/tiers/reorder

Reorders the tiers in the tier set; the array order becomes the new sort_order. May enqueue a resync job.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Request Body

Field	Type	Required	Description
`tier_ids`	`string[] (UUID)` (min 1)	Yes	Tier ids in their new order

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/reorder" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tier_ids": ["a1...", "b2...", "c3..."] }'

Response (200)

json

{
  "data": [
    { "id": "a1...", "name": "Bronze", "sort_order": 0 },
    { "id": "b2...", "name": "Silver", "sort_order": 1 },
    { "id": "c3...", "name": "Gold", "sort_order": 2 }
  ],
  "resync_job_id": null
}

SDK

typescript

const { data: tiers } = await wh.tiers.reorderTiers(workspaceId, [
  "a1...", "b2...", "c3...",
]);

Preview Tier Assignments

POST /wallethero-api/workspace/:workspaceId/tiers/preview

Dry-run that evaluates clients against draft conditions and tiers without persisting anything. Returns, per client, their current vs. projected tier and whether it would change. Use this to preview the impact of a tier-set edit before saving.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Request Body

Field	Type	Required	Description
`conditions`	`array` of condition definitions	Yes	Draft condition list (`{ type, wallet_type_code? }`)
`tiers`	`array` of draft tiers	Yes	Draft tiers, each `{ id, name, sort_order, color?, kind?, condition_values }`
`tier_id`	`string (UUID)` or `"untiered"`	No	Filter previewed clients to a current tier (`"untiered"` → no tier)
`search`	`string`	No	Name/email search
`limit`	`number`	No	Page size (default 100, max 1000)
`offset`	`number`	No	Pagination offset
`lookback_days`	`number`	No	Override the downgrade lookback window for the preview
`active`	`boolean`	No	Restrict to active/inactive clients

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/preview" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": [{ "type": "total_spending" }],
    "tiers": [
      { "id": "a1", "name": "Bronze", "sort_order": 0, "condition_values": { "total_spending": 0 } },
      { "id": "b2", "name": "Gold", "sort_order": 1, "condition_values": { "total_spending": 1000 } }
    ],
    "limit": 100
  }'

Response (200)

json

{
  "data": [
    {
      "client_id": "c1...",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "current_tier_id": "a1",
      "projected_tier_id": "b2",
      "projected_tier_name": "Gold",
      "projected_tier_color": "#ffd700",
      "changed": true,
      "condition_values": { "total_spending": 1200 }
    }
  ],
  "counts": { "a1": 80, "b2": 20 },
  "meta": { "total": 100, "filtered": 100, "truncated": false }
}

SDK

typescript

const result = await wh.tiers.previewTierAssignments(workspaceId, {
  conditions: [{ type: "total_spending" }],
  tiers: [
    { id: "a1", name: "Bronze", sort_order: 0, condition_values: { total_spending: 0 } },
    { id: "b2", name: "Gold", sort_order: 1, condition_values: { total_spending: 1000 } },
  ],
  limit: 100,
});

Get Client Tier

GET /wallethero-api/workspace/:workspaceId/clients/:clientId/tier

Returns a client's tier progress: their current and next tier, per-condition progress, overall progress, and effective benefits. Returns { "data": null } if no tier set exists. (Identical payload to the progress endpoint below.)

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier
`clientId`	`string (UUID)`	Client identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/clients/CLIENT_ID/tier" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": {
    "client_id": "CLIENT_ID",
    "current_tier": { "id": "a1...", "name": "Bronze" },
    "next_tier": { "id": "b2...", "name": "Gold" },
    "conditions": [
      { "type": "total_spending", "current_value": 600, "target_value": 1000, "progress": 0.6, "met": false }
    ],
    "overall_progress": 0.6,
    "effective_benefits": [{ "id": "b1", "label": "Free shipping" }],
    "manually_assigned": false
  }
}

SDK

typescript

const { data: tier } = await wh.tiers.getClientTier(workspaceId, clientId);

Get Client Tier Progress

GET /wallethero-api/workspace/:workspaceId/clients/:clientId/tier/progress

Returns the same tier progress payload as Get Client Tier. Returns { "data": null } if no tier set exists.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier
`clientId`	`string (UUID)`	Client identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/clients/CLIENT_ID/tier/progress" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": {
    "client_id": "CLIENT_ID",
    "current_tier": { "id": "a1...", "name": "Bronze" },
    "next_tier": { "id": "b2...", "name": "Gold" },
    "conditions": [
      { "type": "total_spending", "current_value": 600, "target_value": 1000, "progress": 0.6, "met": false }
    ],
    "overall_progress": 0.6,
    "effective_benefits": [{ "id": "b1", "label": "Free shipping" }],
    "manually_assigned": false
  }
}

SDK

typescript

const { data: progress } = await wh.tiers.getClientProgress(workspaceId, clientId);

Assign Client Tier

POST /wallethero-api/workspace/:workspaceId/tiers/assign

Assigns a client to a tier (or clears their tier with tier_id: null). By default the assignment is marked manual, which pins the client and exempts them from automatic recalculation.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Request Body

Field	Type	Required	Default	Description
`client_id`	`string (UUID)`	Yes	—	Client to assign
`tier_id`	`string (UUID)` or `null`	Yes	—	Target tier; `null` clears the tier
`manually_assigned`	`boolean`	No	`true`	Whether this counts as a manual (pinned) assignment

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/assign" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "client_id": "CLIENT_ID", "tier_id": "a1...", "manually_assigned": true }'

Response (200)

json

{
  "data": {
    "id": "ct1...",
    "client_id": "CLIENT_ID",
    "tier_set_id": "8f1c...",
    "tier_id": "a1...",
    "workspace_id": "WORKSPACE_ID",
    "promoted_at": "2026-06-16T10:00:00Z",
    "manually_assigned": true
  }
}

SDK

typescript

const { data: clientTier } = await wh.tiers.assignTier(workspaceId, {
  client_id: clientId,
  tier_id: "a1...",
  manually_assigned: true,
});

Recalculate Client Tier

POST /wallethero-api/workspace/:workspaceId/clients/:clientId/tier/recalculate

Re-evaluates a single client against the tier set and applies any promotion or downgrade. Returns the change result.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier
`clientId`	`string (UUID)`	Client identifier

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/clients/CLIENT_ID/tier/recalculate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response (200)

json

{
  "data": {
    "changed": true,
    "previous_tier": { "id": "a1...", "name": "Bronze" },
    "new_tier": { "id": "b2...", "name": "Gold" },
    "client_tier": {
      "id": "ct1...",
      "client_id": "CLIENT_ID",
      "tier_id": "b2...",
      "manually_assigned": false
    }
  }
}

SDK

typescript

const { data: result } = await wh.tiers.recalculateClient(workspaceId, clientId);

Recalculate All

POST /wallethero-api/workspace/:workspaceId/tiers/recalculate-all

Enqueues an async job that recalculates tiers for all clients in the workspace. Returns the job id and status; poll the resync-job endpoint for progress.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/recalculate-all" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response (200)

json

{ "data": { "job_id": "job_abc123", "status": "pending" } }

SDK

typescript

const { data: job } = await wh.tiers.recalculateAll(workspaceId);
// job.job_id, job.status

Resync All

POST /wallethero-api/workspace/:workspaceId/tiers/resync

Enqueues an async job that recalculates tiers and re-pushes pass templates, pass-field syncs, and wallet refreshes — even for clients whose tier did not change. Returns the job id and status.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tiers/resync" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response (200)

json

{ "data": { "job_id": "job_abc123", "status": "pending" } }

SDK

typescript

const { data: job } = await wh.tiers.resyncAll(workspaceId);

Get Tier Resync Job

GET /wallethero-api/workspace/:workspaceId/tier-resync-jobs/:id

Fetches the status and progress of a tier resync / recalculate job. Returns 404 if the job is not found in the workspace.

Auth: Bearer token — workspace member

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Workspace identifier
`id`	`string (UUID)`	Job identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/tier-resync-jobs/JOB_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": {
    "id": "job_abc123",
    "workspace_id": "WORKSPACE_ID",
    "tier_set_id": "8f1c...",
    "kind": "resync",
    "status": "running",
    "triggered_by": "user_uuid",
    "total_clients": 500,
    "processed_count": 120,
    "failed_count": 0,
    "last_error": null,
    "cancel_requested": false,
    "started_at": "2026-06-16T10:00:00Z",
    "completed_at": null,
    "date_created": "2026-06-16T09:59:00Z",
    "date_updated": "2026-06-16T10:01:00Z"
  }
}

kind is "recalculate" or "resync"; status is one of pending, running, completed, failed, cancelled.

Response (404)

json

{ "errors": [{ "message": "Job not found" }] }

SDK

typescript

const { data: job } = await wh.tiers.getTierResyncJob(workspaceId, jobId);

Tiers ​

Get Tier Set ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Create Tier Set ​

Path Parameters ​

Request Body ​

Example Request ​

Response (201) ​

SDK ​

Update Tier Set ​

Path Parameters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Delete Tier Set ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

List Tiers ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

List Tier Clients ​

Path Parameters ​

Query Parameters ​

Example Request ​

Response (200) ​

SDK ​

Tier Client Counts ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Get Tier ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Create Tier ​

Path Parameters ​

Request Body ​

Example Request ​

Response (201) ​

SDK ​

Update Tier ​

Path Parameters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Delete Tier ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Reorder Tiers ​

Path Parameters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Preview Tier Assignments ​

Path Parameters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Get Client Tier ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Get Client Tier Progress ​

Path Parameters ​

Tiers

Get Tier Set

Path Parameters

Example Request

Response (200)

SDK

Create Tier Set

Path Parameters

Request Body

Example Request

Response (201)

SDK

Update Tier Set

Path Parameters

Request Body

Example Request

Response (200)

SDK

Delete Tier Set

Path Parameters

Example Request

Response (200)

SDK

List Tiers

Path Parameters

Example Request

Response (200)

SDK

List Tier Clients

Path Parameters

Query Parameters

Example Request

Response (200)

SDK

Tier Client Counts

Path Parameters

Example Request

Response (200)

SDK

Get Tier

Path Parameters

Example Request

Response (200)

SDK

Create Tier

Path Parameters

Request Body

Example Request

Response (201)

SDK

Update Tier

Path Parameters

Request Body

Example Request

Response (200)

SDK

Delete Tier

Path Parameters

Example Request

Response (200)

SDK

Reorder Tiers

Path Parameters

Request Body

Example Request

Response (200)

SDK

Preview Tier Assignments

Path Parameters

Request Body

Example Request

Response (200)

SDK

Get Client Tier

Path Parameters

Example Request

Response (200)

SDK

Get Client Tier Progress

Path Parameters