Campaigns — Actions

Actions define what a campaign does to each pass in its audience. A campaign can have multiple actions that run in sort order. Actions can only be added to / reordered on draft campaigns.

Auth: Bearer token — workspace member. /campaigns/:id/actions* routes resolve the workspace from the campaign row; /campaign-actions/:id* routes resolve it by joining the action to its parent campaign.

Action Types

Type	Description
push_notification	Send a notification to passes
template_switch	Switch passes to a different template (optionally temporary)
custom_field_update	Update custom field values on passes
give_reward	Issue one or more rewards
assign_tier	Assign a loyalty tier (optionally temporary)

Action Config by Type

The action_config object is validated against the action type:

push_notification

Field	Type	Required	Description
notification_message	string	Yes	Message to send

template_switch

Field	Type	Required	Description
target_template_id	string (UUID)	Yes	Template to switch passes to
duration_days	number | null	No	Make the switch temporary; reverts after N days (1–3650)

custom_field_update

Field	Type	Required	Description
custom_field_updates	object	Yes	Key-value pairs of fields to set

give_reward

Field	Type	Required	Description
reward_ids	string[] (UUID)	Yes	One or more rewards to issue

assign_tier

Field	Type	Required	Description
tier_id	string (UUID)	Yes	Tier to assign
duration_days	number | null	No	Make the assignment temporary; reverts after N days (1–3650)

Action Status

Status	Description
pending	Action hasn't started yet
in_progress	Action is currently executing
completed	Action finished successfully
failed	Action failed

---

List Campaign Actions

GET /wallethero-api/campaigns/:id/actions

Returns the campaign's actions ordered by sort, then date_created.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
id	string (UUID)	Campaign identifier

Example Request

curl "https://api.wallethero.app/wallethero-api/campaigns/CAMPAIGN_ID/actions" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "campaign_id": "CAMPAIGN_ID",
      "action_type": "push_notification",
      "action_config": { "notification_message": "Earn double points this weekend!" },
      "status": "pending",
      "sort": 0
    }
  ]
}

SDK

const actions = await wh.campaigns.getActions("CAMPAIGN_ID");

---

Add Campaign Action

POST /wallethero-api/campaigns/:id/actions

Adds an action to a draft campaign. The action_config is validated against action_type.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
id	string (UUID)	Campaign identifier

Request Body

Field	Type	Required	Description
action_type	string	Yes	One of push_notification, template_switch, custom_field_update, give_reward, assign_tier
action_config	object	Yes	Config for the chosen type (see Action Config by Type)
sort	number	No	Position in the execution order

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/campaigns/CAMPAIGN_ID/actions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "push_notification",
    "action_config": { "notification_message": "Earn double points this weekend!" }
  }'

Response (200)

{
  "data": {
    "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "campaign_id": "CAMPAIGN_ID",
    "action_type": "push_notification",
    "action_config": { "notification_message": "Earn double points this weekend!" },
    "status": "pending",
    "sort": 0
  }
}

SDK

const action = await wh.campaigns.addAction("CAMPAIGN_ID", {
  action_type: "push_notification",
  action_config: { notification_message: "Earn double points this weekend!" },
});

// Convenience helpers:
await wh.campaigns.addPushNotificationAction("CAMPAIGN_ID", "Hello!");
await wh.campaigns.addTemplateSwitchAction("CAMPAIGN_ID", "TEMPLATE_ID");
await wh.campaigns.addCustomFieldUpdateAction("CAMPAIGN_ID", { tier: "Gold" });

---

Reorder Campaign Actions

POST /wallethero-api/campaigns/:id/actions/reorder

Reorders a campaign's actions. action_ids must contain every action on the campaign, in the desired execution order (index 0 runs first).

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
id	string (UUID)	Campaign identifier

Request Body

Field	Type	Required	Description
action_ids	string[] (UUID)	Yes	All action IDs in the new order (at least one)

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/campaigns/CAMPAIGN_ID/actions/reorder" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action_ids": ["aaaa...", "bbbb...", "cccc..."] }'

Response (200)

{
  "data": [
    { "id": "aaaa...", "sort": 0 },
    { "id": "bbbb...", "sort": 1 },
    { "id": "cccc...", "sort": 2 }
  ]
}

SDK

const actions = await wh.campaigns.reorderActions("CAMPAIGN_ID", [
  "aaaa...",
  "bbbb...",
  "cccc...",
]);

---

Update Campaign Action

PATCH /wallethero-api/campaign-actions/:id

Updates an action's config and/or sort order.

Auth: Bearer token — workspace member (resolved via the parent campaign).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Action identifier

Request Body

Field	Type	Required	Description
action_config	object	No	Replacement config (validated against the action's type)
sort	number	No	New position in the execution order

Example Request

curl -X PATCH "https://api.wallethero.app/wallethero-api/campaign-actions/ACTION_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action_config": { "notification_message": "Updated message!" } }'

Response (200)

{
  "data": {
    "id": "ACTION_ID",
    "action_type": "push_notification",
    "action_config": { "notification_message": "Updated message!" },
    "status": "pending"
  }
}

SDK

const action = await wh.campaigns.updateAction("ACTION_ID", {
  action_config: { notification_message: "Updated message!" },
});

---

Delete Campaign Action

DELETE /wallethero-api/campaign-actions/:id

Removes an action from its campaign.

Auth: Bearer token — workspace member (resolved via the parent campaign).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Action identifier

Example Request

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

Response (200)

{ "success": true, "message": "Action deleted" }

SDK

await wh.campaigns.deleteAction("ACTION_ID");

---

Execute Single Action

POST /wallethero-api/campaign-actions/:id/execute

Executes one action immediately against the campaign's audience.

Auth: Bearer token — workspace member (resolved via the parent campaign).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Action identifier

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/campaign-actions/ACTION_ID/execute" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": { "id": "ACTION_ID", "status": "completed", "executed_at": "2026-01-16T10:05:00Z" }
}

SDK

const action = await wh.campaigns.executeAction("ACTION_ID");

---

Execute All Actions

POST /wallethero-api/campaigns/:id/execute-all

Executes all pending actions on the campaign in order.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
id	string (UUID)	Campaign identifier

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/campaigns/CAMPAIGN_ID/execute-all" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    { "id": "aaaa...", "status": "completed" },
    { "id": "bbbb...", "status": "completed" }
  ]
}

SDK

const actions = await wh.campaigns.executeAllActions("CAMPAIGN_ID");