Campaigns — CRUD & Listing

Create, read, update, and delete campaigns, plus the calendar, status-summary, and duplicate helpers. See the overview for the campaign model and lifecycle.

Auth: Bearer token — workspace member. List / create / summary are workspace-scoped by path; get / update / delete / duplicate resolve the workspace from the campaign row; calendar resolves it from the workspace_id query parameter.

---

List Campaigns

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

Lists every campaign in the workspace, newest first (sorted by -date_created).

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier

Example Request

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

Response (200)

{
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "workspace_id": "WORKSPACE_ID",
      "name": "Winter Promo Push",
      "description": "Weekend double points",
      "status": "draft",
      "segment_id": "22222222-2222-2222-2222-222222222222",
      "scheduled_at": null,
      "date_created": "2026-01-10T08:00:00Z"
    }
  ]
}

SDK

const { data } = await wh.campaigns.list({
  filter: { workspace_id: { _eq: "WORKSPACE_ID" } },
});
// or, equivalently:
const { data: byWs } = await wh.campaigns.getByWorkspace("WORKSPACE_ID");

---

Create Campaign

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

Creates a draft campaign. Provide either segment_id or manual_client_ids (mutually exclusive) — or neither, to fill the audience in later.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier

Request Body

Field	Type	Required	Description
name	string	Yes	Campaign name
description	string	No	Free-text description
scheduled_at	string (ISO 8601)	No	Time to run the campaign at
segment_id	string (UUID)	No	Target a saved segment (mutually exclusive with manual_client_ids)
manual_client_ids	string[] (UUID)	No	Target a manual list of clients (mutually exclusive with segment_id)

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/campaigns" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Winter Promo Push",
    "description": "Weekend double points",
    "segment_id": "22222222-2222-2222-2222-222222222222"
  }'

Response (201)

{
  "data": {
    "id": "11111111-1111-1111-1111-111111111111",
    "workspace_id": "WORKSPACE_ID",
    "name": "Winter Promo Push",
    "status": "draft",
    "segment_id": "22222222-2222-2222-2222-222222222222"
  }
}

SDK

const { data: campaign } = await wh.campaigns.create({
  workspace_id: "WORKSPACE_ID",
  name: "Winter Promo Push",
  segment_id: "22222222-2222-2222-2222-222222222222",
});

---

Get Campaigns Calendar

GET /wallethero-api/campaigns/calendar

Returns campaigns for a calendar view, optionally filtered by status and a scheduled-time window. Registered before /campaigns/:id so the literal calendar is not parsed as a UUID.

Auth: Bearer token — workspace member (resolved from the workspace_id query parameter).

Query Parameters

Parameter	Type	Required	Description
workspace_id	string (UUID)	Yes	Workspace identifier
start	string (ISO 8601)	No	Window start (scheduled_at lower bound)
end	string (ISO 8601)	No	Window end (scheduled_at upper bound)
status	string	No	One of draft, scheduled, active, completed, cancelled

Example Request

curl "https://api.wallethero.app/wallethero-api/campaigns/calendar?workspace_id=WORKSPACE_ID&start=2026-01-01T00:00:00Z&end=2026-01-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200)

{
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "Winter Promo Push",
      "status": "scheduled",
      "scheduled_at": "2026-01-20T09:00:00Z"
    }
  ]
}

SDK

const campaigns = await wh.campaigns.getCalendar("WORKSPACE_ID", {
  status: "scheduled",
  start: "2026-01-01T00:00:00Z",
  end: "2026-01-31T23:59:59Z",
});

---

Get Campaign

GET /wallethero-api/campaigns/:id

Fetches a single campaign by ID.

Auth: Bearer token — workspace member (resolved from the campaign row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Campaign identifier

Example Request

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

Response (200)

{
  "data": {
    "id": "CAMPAIGN_ID",
    "workspace_id": "WORKSPACE_ID",
    "name": "Winter Promo Push",
    "status": "draft",
    "segment_id": "22222222-2222-2222-2222-222222222222"
  }
}

SDK

const { data: campaign } = await wh.campaigns.get("CAMPAIGN_ID");

---

Update Campaign

PATCH /wallethero-api/campaigns/:id

Updates a campaign's editable fields. Any workspace_id in the body is stripped. Pass segment_id: null or manual_client_ids: null to clear an audience.

Auth: Bearer token — workspace member (resolved from the campaign row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Campaign identifier

Request Body

Field	Type	Required	Description
name	string	No	New name
description	string	No	New description
scheduled_at	string (ISO 8601)	No	New scheduled time
segment_id	string (UUID) | null	No	Assign or clear the target segment
manual_client_ids	string[] (UUID) | null	No	Assign or clear the manual audience

WARNING

Only draft campaigns can be updated.

Example Request

curl -X PATCH "https://api.wallethero.app/wallethero-api/campaigns/CAMPAIGN_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Winter Promo Push (v2)" }'

Response (200)

{
  "data": { "id": "CAMPAIGN_ID", "name": "Winter Promo Push (v2)", "status": "draft" }
}

SDK

const { data } = await wh.campaigns.update("CAMPAIGN_ID", {
  name: "Winter Promo Push (v2)",
});

---

Delete Campaign

DELETE /wallethero-api/campaigns/:id

Deletes a campaign.

Auth: Bearer token — workspace member (resolved from the campaign row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Campaign identifier

Example Request

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

Response (200)

{ "message": "Campaign deleted" }

SDK

await wh.campaigns.delete("CAMPAIGN_ID");

---

Duplicate Campaign

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

Creates a copy of the campaign (in draft). By default its actions are copied too.

Auth: Bearer token — workspace member (resolved from the campaign row).

Path Parameters

Parameter	Type	Description
id	string (UUID)	Campaign identifier to copy

Request Body

Field	Type	Required	Default	Description
name	string	No	"<name> (copy)"	Name for the new campaign
include_actions	boolean	No	true	Copy the source campaign's actions

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/campaigns/CAMPAIGN_ID/duplicate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Winter Promo Push (clone)", "include_actions": true }'

Response (200)

{
  "data": { "id": "33333333-3333-3333-3333-333333333333", "name": "Winter Promo Push (clone)", "status": "draft" }
}

SDK

const campaign = await wh.campaigns.duplicate("CAMPAIGN_ID", {
  name: "Winter Promo Push (clone)",
  includeActions: true,
});

---

Campaign Status Summary

GET /wallethero-api/workspace/:workspaceId/campaigns/summary

Returns campaign counts per status for the workspace.

Auth: Bearer token — workspace member.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier

Example Request

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

Response (200)

{
  "data": { "draft": 4, "scheduled": 2, "active": 1, "completed": 7, "cancelled": 0 }
}

SDK

const { data: summary } = await wh.campaigns.getStatusSummary("WORKSPACE_ID");