Mobile App — Config & Runtime

Endpoints for the in-store staff/POS mobile app, split into two auth scopes:

Configuration & action management (the web dashboard) — GET/POST/PATCH/DELETE /workspace/:workspaceId/mobile-app-config and the action CRUD/reorder routes. These use a Bearer token belonging to a member of the workspace (createWorkspaceGuard). The two action-mutation routes keyed by action id (PATCH/DELETE /mobile-app-actions/:id) resolve the workspace by joining the action to its config, then apply the same workspace-member guard.
In-app runtime (the paired mobile device) — GET /workspace/:workspaceId/mobile-app, action execution, and every /mobile-app/passes/... and /mobile-app/receipt-scan route. These use a mobile session via the X-Mobile-Token header (mobileAppAccountabilityMiddleware); see Authentication. The middleware rejects any request whose :workspaceId differs from the session's workspace.

Each workspace has at most one mobile app config (enforced by a unique constraint). A config owns an ordered list of actions (add_points, remove_points, add_transaction, redeem_reward, grant_reward, update_client_data, change_tier), each with its own action_config and optional UI form_fields. Runtime pass endpoints require the config to be enabled.

Config/action SDK methods live on wh.mobileAppConfig (MobileAppConfigService). The runtime pass-query endpoints (history/loyalty/transactions/ledger/rewards/redemptions and receipt-scan) have no SDK wrapper — call them directly with the X-Mobile-Token header.

Get mobile app config

GET /wallethero-api/workspace/:workspaceId/mobile-app-config

Returns the workspace's mobile app config together with all of its actions (ordered by sort_order). Returns data: null if no config 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/mobile-app-config" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

json

{
  "data": {
    "id": "cfg1...",
    "workspace_id": "WORKSPACE_ID",
    "is_enabled": true,
    "project_ids": null,
    "allowed_role_ids": null,
    "hidden_fields": null,
    "app_config": { "enable_pass_history": true },
    "actions": [
      { "id": "act1...", "name": "Add Points", "action_type": "add_points", "sort_order": 0, "is_enabled": true }
    ]
  }
}

SDK

typescript

const res = await wh.mobileAppConfig.getConfig(workspaceId);

Create mobile app config

POST /wallethero-api/workspace/:workspaceId/mobile-app-config

Creates the workspace's mobile app config. The workspace_id is taken from the path. A set of four default actions (Add Points, Remove Points, Redeem Reward, Update Client Data) is created automatically. Fails with 400 if a config already exists 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
`is_enabled`	`boolean`	No	`true`	Whether the mobile app is enabled
`project_ids`	`string[] (UUID)`	No	—	Restrict passes/actions to these projects
`allowed_role_ids`	`string[] (UUID)`	No	—	Restrict app access to these workspace roles
`hidden_fields`	`string[]`	No	—	Custom-field names hidden from pass results
`app_config`	`object`	No	`{}`	Branding/feature flags (see below)

app_config fields: primary_color (string), logo_url (URL), welcome_message (string ≤500), enable_pass_history (boolean).

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-config" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "is_enabled": true, "app_config": { "enable_pass_history": true } }'

Response (201)

json

{
  "data": {
    "id": "cfg1...",
    "workspace_id": "WORKSPACE_ID",
    "is_enabled": true,
    "app_config": { "enable_pass_history": true }
  }
}

SDK

typescript

const res = await wh.mobileAppConfig.createConfig(workspaceId, {
  is_enabled: true,
  app_config: { enable_pass_history: true },
});

Update mobile app config

PATCH /wallethero-api/workspace/:workspaceId/mobile-app-config

Updates the workspace's mobile app config. All fields optional; only provided fields are changed. project_ids, allowed_role_ids, and hidden_fields accept null to clear.

Auth: Bearer token — workspace member.

Path Parameters

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

Request Body

Field	Type	Required	Description
`is_enabled`	`boolean`	No	Enable/disable the mobile app
`project_ids`	`string[] (UUID) \| null`	No	Project restriction (or `null` to clear)
`allowed_role_ids`	`string[] (UUID) \| null`	No	Role restriction (or `null` to clear)
`hidden_fields`	`string[] \| null`	No	Hidden custom-field names (or `null` to clear)
`app_config`	`object`	No	Branding/feature flags

Example Request

bash

curl -X PATCH "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-config" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "is_enabled": false }'

Response (200)

json

{ "data": { "id": "cfg1...", "is_enabled": false } }

SDK

typescript

const res = await wh.mobileAppConfig.updateConfig(workspaceId, { is_enabled: false });

Delete mobile app config

DELETE /wallethero-api/workspace/:workspaceId/mobile-app-config

Deletes the workspace's mobile app config (and its actions). Returns 204 No Content.

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/mobile-app-config" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

204 No Content

SDK

typescript

await wh.mobileAppConfig.deleteConfig(workspaceId);

Create an action

POST /wallethero-api/workspace/:workspaceId/mobile-app-config/actions

Adds an action to the workspace's mobile app config. action_config is validated against the schema for the given action_type. If sort_order is omitted, the action is appended.

Auth: Bearer token — workspace member.

Path Parameters

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

Request Body

Field	Type	Required	Default	Description
`name`	`string`	Yes	—	Action display name
`action_type`	`string`	Yes	—	`add_transaction` \| `add_points` \| `remove_points` \| `redeem_reward` \| `grant_reward` \| `update_client_data` \| `change_tier`
`description`	`string`	No	—	Description (≤1000)
`icon`	`string`	No	—	Icon key (≤100)
`action_config`	`object`	No	`{}`	Type-specific config (see below)
`form_fields`	`FormField[]`	No	`[]`	UI form-field definitions
`is_enabled`	`boolean`	No	`true`	Whether the action is enabled
`sort_order`	`number`	No	appended	Position in the action list
`allowed_role_ids`	`string[] (UUID)`	No	—	Restrict execution to these roles

action_config by type:

add_points / remove_points — wallet_type_codes (string[]), default_points (≥0), max_points (>0), default_note (string).
add_transaction — transaction_type (string), default_amount (≥0), require_description (boolean).
update_client_data — allowed_fields (string[]).
redeem_reward / grant_reward — {} (no config). Creating either requires the workspace to have at least one active reward.
change_tier — excluded_tier_ids (UUID[]; exclusive tiers hidden from the picker), allow_duration (boolean; let staff set a temporary duration at execution time), default_duration_days (positive integer ≤3650 or null for permanent). Creating this action requires the workspace to have at least one exclusive tier — only exclusive tiers are manually assignable (auto tiers are recomputed by the tier cron), and every id in excluded_tier_ids must belong to the workspace.

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-config/actions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add Points",
    "action_type": "add_points",
    "icon": "coins",
    "action_config": { "wallet_type_codes": ["POINTS"], "max_points": 1000 }
  }'

Response (201)

json

{
  "data": {
    "id": "act1...",
    "mobile_app_config_id": "cfg1...",
    "name": "Add Points",
    "action_type": "add_points",
    "action_config": { "wallet_type_codes": ["POINTS"], "max_points": 1000 },
    "is_enabled": true,
    "sort_order": 4
  }
}

SDK

typescript

const res = await wh.mobileAppConfig.createAction(workspaceId, {
  name: "Add Points",
  action_type: "add_points",
  action_config: { wallet_type_codes: ["POINTS"], max_points: 1000 },
});
// Convenience: wh.mobileAppConfig.createAddPointsAction(workspaceId, { name, wallet_type_codes, max_points })

Update an action

PATCH /wallethero-api/mobile-app-actions/:id

Updates an action. The workspace is resolved by joining the action to its config; the caller must be a member of that workspace. All fields optional; action_config is re-validated against the (possibly new) action_type.

Auth: Bearer token — workspace member (resolved via the action's config).

Path Parameters

Parameter	Type	Description
`id`	`string (UUID)`	Action identifier

Request Body

Same fields as Create an action (all optional). description, icon, and allowed_role_ids accept null to clear.

Example Request

bash

curl -X PATCH "https://api.wallethero.app/wallethero-api/mobile-app-actions/ACTION_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "is_enabled": false }'

Response (200)

json

{ "data": { "id": "ACTION_ID", "is_enabled": false } }

SDK

typescript

const res = await wh.mobileAppConfig.updateAction(actionId, { is_enabled: false });

Delete an action

DELETE /wallethero-api/mobile-app-actions/:id

Deletes an action. The workspace is resolved via the action's config; the caller must be a member. Returns 204 No Content.

Auth: Bearer token — workspace member (resolved via the action's config).

Path Parameters

Parameter	Type	Description
`id`	`string (UUID)`	Action identifier

Example Request

bash

curl -X DELETE "https://api.wallethero.app/wallethero-api/mobile-app-actions/ACTION_ID" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

204 No Content

SDK

typescript

await wh.mobileAppConfig.deleteAction(actionId);

Reorder actions

POST /wallethero-api/workspace/:workspaceId/mobile-app-config/actions/reorder

Sets the sort_order of the config's actions to the order of the provided id array. The array must include all actions for the config exactly once. Returns the reordered actions.

Auth: Bearer token — workspace member.

Path Parameters

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

Request Body

Field	Type	Required	Description
`action_ids`	`string[] (UUID)`	Yes	Full set of action ids in the desired order

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app-config/actions/reorder" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action_ids": ["act2...", "act1...", "act3..."] }'

Response (200)

json

{ "data": [ { "id": "act2...", "sort_order": 0 }, { "id": "act1...", "sort_order": 1 } ] }

SDK

typescript

const res = await wh.mobileAppConfig.reorderActions(workspaceId, ["act2...", "act1...", "act3..."]);

Get mobile app (runtime view)

GET /wallethero-api/workspace/:workspaceId/mobile-app

The mobile device's view of the app: the enabled config, the enabled actions filtered by the user's workspace role, the workspace data-model fields, and active wallet types. Returns data: null if no enabled config exists. Enforces allowed_role_ids on both the config and individual actions.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app" \
  -H "X-Mobile-Token: ACCESS_TOKEN"

Response (200)

json

{
  "data": {
    "config": { "id": "cfg1...", "is_enabled": true, "app_config": { "enable_pass_history": true } },
    "actions": [ { "id": "act1...", "name": "Add Points", "action_type": "add_points" } ],
    "data_model": [
      { "field_name": "loyalty_id", "field_label": "Loyalty ID", "field_type": "text", "is_required": false, "is_system": false, "sort_order": 0 }
    ],
    "wallet_types": [ { "code": "POINTS", "name": "Points", "unit_singular_name": "point", "unit_plural_name": "points" } ]
  }
}

SDK

typescript

const res = await wh.mobileAppConfig.getMobileApp(workspaceId);

Execute an action on a pass

POST /wallethero-api/mobile-app-actions/:id/execute

Runs an action against a pass. Behavior depends on the action's action_type: add/remove points, add a transaction, update client data, or redeem a reward. The action must be enabled and belong to the session's workspace, the pass must belong to the workspace (and an allowed project), and the caller's role must be permitted.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`id`	`string (UUID)`	Action identifier

Request Body

Field	Type	Required	Description
`pass_id`	`string (UUID)`	Yes	Target pass
`data`	`object`	No	Action-type-specific payload

data by action type:

add_points / remove_points — points (number, defaults to default_points), wallet_type_code (required when multiple wallets are configured), note (string).
add_transaction — amount (number), description (string; required if require_description), plus optional rich transaction fields (currency, transaction_timestamp, location, subtotal_amount, discount_amount, line_items, payment_info, metadata).
update_client_data — fields (object of field→value; filtered to allowed_fields when configured).
redeem_reward / grant_reward — reward_id (UUID, required), optional metadata.
change_tier — tier_id (UUID, required; must be an exclusive tier of the workspace, not listed in excluded_tier_ids), duration_days (positive integer; honored only when allow_duration is set, otherwise default_duration_days applies; permanent when neither is set). Assignment goes through the shared tier-assignment path, so tier-change side effects fire.

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/mobile-app-actions/ACTION_ID/execute" \
  -H "X-Mobile-Token: ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "pass_id": "PASS_ID", "data": { "points": 50, "note": "In-store visit" } }'

Response (200)

json

{
  "data": {
    "success": true,
    "message": "Added 50 points",
    "data": { "added_points": 50, "ledger_entry_id": "led1..." }
  }
}

SDK

typescript

const res = await wh.mobileAppConfig.executeAction(actionId, {
  pass_id: passId,
  data: { points: 50, note: "In-store visit" },
});
// Convenience: wh.mobileAppConfig.addPoints / removePoints / addTransaction / updateClientData / redeemReward

Search passes

GET /wallethero-api/workspace/:workspaceId/mobile-app/passes/search

Searches passes by holder first/last name, email, or barcode value. Results are restricted to the config's allowed projects and have custom fields filtered by the workspace data model and the config's hidden_fields.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace

Query Parameters

Parameter	Type	Required	Default	Description
`query`	`string`	Yes	—	Search term (1–255 chars)
`project_id`	`string (UUID)`	No	—	Filter to a single project
`limit`	`number`	No	`20`	Max items (1–100)
`offset`	`number`	No	`0`	Pagination offset

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app/passes/search?query=taylor&limit=20" \
  -H "X-Mobile-Token: ACCESS_TOKEN"

Response (200)

json

{
  "data": [
    {
      "id": "PASS_ID",
      "client_id": "cli1...",
      "holder_first_name": "Sam",
      "holder_last_name": "Taylor",
      "holder_email": "[email protected]",
      "barcode_value": "123456789",
      "custom_fields": { "loyalty_id": "ABC" },
      "project_id": "prj1...",
      "project_name": "Main Store",
      "template_name": "Loyalty Card",
      "date_created": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": { "total_count": 1, "returned_count": 1, "offset": 0 }
}

SDK

typescript

const res = await wh.mobileAppConfig.searchPasses(workspaceId, "taylor", { limit: 20 });

Lookup pass by barcode

GET /wallethero-api/workspace/:workspaceId/mobile-app/passes/lookup

Looks up a single pass by its exact barcode value (scanned). Returns data: null if not found or outside the config's allowed projects.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace

Query Parameters

Parameter	Type	Required	Description
`barcode_value`	`string`	Yes*	Barcode value to look up
`barcode`	`string`	Yes*	Alias for `barcode_value`

* One of barcode_value or barcode is required.

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app/passes/lookup?barcode_value=123456789" \
  -H "X-Mobile-Token: ACCESS_TOKEN"

Response (200)

json

{ "data": { "id": "PASS_ID", "holder_first_name": "Sam", "barcode_value": "123456789", "custom_fields": {} } }

SDK

typescript

const res = await wh.mobileAppConfig.lookupPass(workspaceId, "123456789");

Get pass history

GET /wallethero-api/workspace/:workspaceId/mobile-app/passes/:passId/history

Returns the pass's event history. Requires app_config.enable_pass_history to be true on the config; otherwise returns 403.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace
`passId`	`string (UUID)`	Pass identifier

Query Parameters

Parameter	Type	Required	Default	Description
`event_category`	`string`	No	—	`field_change` \| `transaction` \| `activity`
`limit`	`number`	No	`50`	Max items (1–100)
`offset`	`number`	No	`0`	Pagination offset

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app/passes/PASS_ID/history" \
  -H "X-Mobile-Token: ACCESS_TOKEN"

Response (200)

json

{
  "data": [
    { "id": "evt1...", "pass_id": "PASS_ID", "event_category": "transaction", "event_timestamp": "2026-06-16T09:00:00.000Z" }
  ],
  "meta": { "total_count": 1, "returned_count": 1, "offset": 0 }
}

SDK

No SDK method — call the REST endpoint directly with the X-Mobile-Token header.

Get pass loyalty

GET /wallethero-api/workspace/:workspaceId/mobile-app/passes/:passId/loyalty

Returns the pass holder's loyalty snapshot: wallet balances and tier progress.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace
`passId`	`string (UUID)`	Pass identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app/passes/PASS_ID/loyalty" \
  -H "X-Mobile-Token: ACCESS_TOKEN"

Response (200)

json

{
  "data": {
    "wallets": [ { "wallet_type_code": "POINTS", "balance": 1200 } ],
    "tier": { "current_tier": "Gold", "progress": 0.6 }
  }
}

SDK

No SDK method — call the REST endpoint directly with the X-Mobile-Token header.

Get pass transactions

GET /wallethero-api/workspace/:workspaceId/mobile-app/passes/:passId/transactions

Lists the transactions of the pass holder's client.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace
`passId`	`string (UUID)`	Pass identifier

Query Parameters

Parameter	Type	Required	Default	Description
`limit`	`number`	No	`20`	Max items (1–100)
`offset`	`number`	No	`0`	Pagination offset

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app/passes/PASS_ID/transactions" \
  -H "X-Mobile-Token: ACCESS_TOKEN"

Response (200)

json

{
  "data": [ { "id": "txn1...", "amount": 49.9, "currency": "USD", "transaction_timestamp": "2026-06-16T09:00:00.000Z" } ],
  "meta": { "total_count": 1, "returned_count": 1, "offset": 0 }
}

SDK

No SDK method — call the REST endpoint directly with the X-Mobile-Token header.

Create a pass transaction

POST /wallethero-api/workspace/:workspaceId/mobile-app/passes/:passId/transactions

Records a transaction for the pass holder's client (mobile transaction scanner). Only the whitelisted fields below may be set; loyalty fields (points, applied rewards, etc.) are not settable from mobile. source is forced to mobile_app.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace
`passId`	`string (UUID)`	Pass identifier

Request Body

Field	Type	Required	Description
`amount`	`number`	Yes	Positive transaction amount
`description`	`string`	No	Free text (≤500)
`currency`	`string`	No	Currency code (1–10 chars)
`transaction_timestamp`	`string (ISO 8601)`	No	When the transaction occurred
`location`	`string`	No	Location label (≤255)
`subtotal_amount`	`number`	No	Subtotal
`discount_amount`	`number`	No	Discount (≥0)
`line_items`	`LineItem[]`	No	Up to 100 line items
`payment_info`	`object`	No	Payment details
`metadata`	`object`	No	Arbitrary metadata

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app/passes/PASS_ID/transactions" \
  -H "X-Mobile-Token: ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 49.9, "currency": "USD", "description": "In-store purchase" }'

Response (200)

json

{ "data": { "id": "txn1...", "amount": 49.9, "currency": "USD", "source": "mobile_app" } }

SDK

No SDK method — call the REST endpoint directly with the X-Mobile-Token header.

Scan a receipt

POST /wallethero-api/workspace/:workspaceId/mobile-app/receipt-scan

Uploads a receipt photo, runs AI extraction, and returns the structured transaction data (merchant, totals, line items, etc.) for review before creating a transaction. Requires the session's workspace to match and an enabled config.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace

Request Body

Field	Type	Required	Description
`image_base64`	`string`	Yes	Base64-encoded image (~8MB binary ceiling)
`media_type`	`string`	Yes	`image/jpeg` \| `image/png` \| `image/webp`

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app/receipt-scan" \
  -H "X-Mobile-Token: ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "image_base64": "<BASE64>", "media_type": "image/jpeg" }'

Response (200)

json

{
  "data": {
    "receipt_file_id": "file1...",
    "extracted": {
      "merchant_name": "Acme Store",
      "total_amount": 49.9,
      "subtotal_amount": 45.0,
      "discount_amount": 0,
      "currency": "USD",
      "transaction_date": "2026-06-16",
      "transaction_time": "09:00",
      "location": "Main St",
      "payment_method": "card",
      "payment_reference": null,
      "line_items": [ { "name": "Coffee", "quantity": 2, "unit_price": 3.5, "total": 7.0 } ],
      "notes": null
    }
  }
}

Errors

Returns a structured error with error_code and (where applicable) receipt_file_id:

receipt_scanner_not_configured, receipt_scanner_busy, receipt_image_invalid, receipt_unreadable.

SDK

No SDK method — call the REST endpoint directly with the X-Mobile-Token header.

Get pass points ledger

GET /wallethero-api/workspace/:workspaceId/mobile-app/passes/:passId/ledger

Returns the points-ledger entries for the pass holder's client.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace
`passId`	`string (UUID)`	Pass identifier

Query Parameters

Parameter	Type	Required	Default	Description
`type`	`string`	No	—	One of `earn`, `spend`, `expire`, `cancel`, `transfer_in`, `transfer_out`, `adjust`, `lock`, `unlock`
`limit`	`number`	No	`20`	Max items (1–100)
`offset`	`number`	No	`0`	Pagination offset

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app/passes/PASS_ID/ledger?type=earn" \
  -H "X-Mobile-Token: ACCESS_TOKEN"

Response (200)

json

{
  "data": [ { "id": "led1...", "type": "earn", "amount": 50, "wallet_type_code": "POINTS" } ],
  "meta": { "total_count": 1, "returned_count": 1, "offset": 0 }
}

SDK

No SDK method — call the REST endpoint directly with the X-Mobile-Token header.

Get available rewards

GET /wallethero-api/workspace/:workspaceId/mobile-app/passes/:passId/rewards

Returns rewards currently available to the pass holder's client.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace
`passId`	`string (UUID)`	Pass identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app/passes/PASS_ID/rewards" \
  -H "X-Mobile-Token: ACCESS_TOKEN"

Response (200)

json

{ "data": [ { "id": "rwd1...", "name": "Free Coffee", "cost": 100 } ] }

SDK

No SDK method — call the REST endpoint directly with the X-Mobile-Token header.

Get active redemptions

GET /wallethero-api/workspace/:workspaceId/mobile-app/passes/:passId/redemptions

Returns the pass holder's redemptions, enriched with reward name and coupon code/status.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace
`passId`	`string (UUID)`	Pass identifier

Example Request

bash

curl "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app/passes/PASS_ID/redemptions" \
  -H "X-Mobile-Token: ACCESS_TOKEN"

Response (200)

json

{
  "data": [
    {
      "id": "rdm1...",
      "reward_id": "rwd1...",
      "reward_name": "Free Coffee",
      "coupon_id": "cpn1...",
      "coupon_code": "ABC123",
      "coupon_status": "active"
    }
  ]
}

SDK

No SDK method — call the REST endpoint directly with the X-Mobile-Token header.

Mark a redemption coupon as used

POST /wallethero-api/workspace/:workspaceId/mobile-app/passes/:passId/redemptions/:redemptionId/use

Marks the redemption's coupon as used. The redemption must belong to the session's workspace and to the pass holder's client.

Auth: Mobile session — X-Mobile-Token.

Path Parameters

Parameter	Type	Description
`workspaceId`	`string (UUID)`	Must match the session's workspace
`passId`	`string (UUID)`	Pass identifier
`redemptionId`	`string (UUID)`	Redemption identifier

Example Request

bash

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/mobile-app/passes/PASS_ID/redemptions/REDEMPTION_ID/use" \
  -H "X-Mobile-Token: ACCESS_TOKEN"

Response (200)

json

{ "data": { "id": "REDEMPTION_ID", "coupon_status": "used", "used_at": "2026-06-16T09:05:00.000Z" } }

SDK

No SDK method — call the REST endpoint directly with the X-Mobile-Token header.

Mobile App — Config & Runtime ​

Get mobile app config ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Create mobile app config ​

Path Parameters ​

Request Body ​

Example Request ​

Response (201) ​

SDK ​

Update mobile app config ​

Path Parameters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Delete mobile app config ​

Path Parameters ​

Example Request ​

Response ​

SDK ​

Create an action ​

Path Parameters ​

Request Body ​

Example Request ​

Response (201) ​

SDK ​

Update an action ​

Path Parameters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Delete an action ​

Path Parameters ​

Example Request ​

Response ​

SDK ​

Reorder actions ​

Path Parameters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Get mobile app (runtime view) ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Execute an action on a pass ​

Path Parameters ​

Request Body ​

Example Request ​

Response (200) ​

SDK ​

Search passes ​

Path Parameters ​

Query Parameters ​

Example Request ​

Response (200) ​

SDK ​

Lookup pass by barcode ​

Path Parameters ​

Query Parameters ​

Example Request ​

Response (200) ​

SDK ​

Get pass history ​

Path Parameters ​

Query Parameters ​

Example Request ​

Response (200) ​

SDK ​

Get pass loyalty ​

Path Parameters ​

Example Request ​

Response (200) ​

SDK ​

Mobile App — Config & Runtime

Get mobile app config

Path Parameters

Example Request

Response (200)

SDK

Create mobile app config

Path Parameters

Request Body

Example Request

Response (201)

SDK

Update mobile app config

Path Parameters

Request Body

Example Request

Response (200)

SDK

Delete mobile app config

Path Parameters

Example Request

Response

SDK

Create an action

Path Parameters

Request Body

Example Request

Response (201)

SDK

Update an action

Path Parameters

Request Body

Example Request

Response (200)

SDK

Delete an action

Path Parameters

Example Request

Response

SDK

Reorder actions

Path Parameters

Request Body

Example Request

Response (200)

SDK

Get mobile app (runtime view)

Path Parameters

Example Request

Response (200)

SDK

Execute an action on a pass

Path Parameters

Request Body

Example Request

Response (200)

SDK

Search passes

Path Parameters

Query Parameters

Example Request

Response (200)

SDK

Lookup pass by barcode

Path Parameters

Query Parameters

Example Request

Response (200)

SDK

Get pass history

Path Parameters

Query Parameters

Example Request

Response (200)

SDK

Get pass loyalty

Path Parameters

Example Request

Response (200)

SDK