Campaigns

Campaigns automate bulk actions over an audience of passes — push notifications, template switches, custom-field updates, reward grants, and tier assignments. An audience is defined either by a saved segment (segment_id) or a manual list of client IDs (manual_client_ids); the two are mutually exclusive.

Marketing consent (GDPR): every campaign send is treated as marketing-purpose, so audience resolution — manual and segment alike — excludes clients whose marketing_consent is not true. The same gate applies to audience preview/count, so what you see is what will be targeted. Transactional flows (pass delivery emails, pairing codes) do not run through campaigns and are unaffected.

Auth: All campaign endpoints require a Bearer token. Workspace-scoped routes (/workspace/:workspaceId/...) and entity routes (/campaigns/:id/..., /campaign-actions/:id/...) are guarded so the caller must be a member of the owning workspace. The calendar route resolves the workspace from the workspace_id query parameter.

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Campaign Lifecycle

Status	Description
draft	Campaign is being configured
scheduled	Campaign is scheduled to run at a future time
active	Campaign is currently executing
completed	Campaign finished executing all actions
cancelled	Campaign was cancelled before completion

Action Types

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

Campaign Structure

interface Campaign {
  id: string;
  workspace_id: string;
  name: string;
  description?: string;
  status: 'draft' | 'scheduled' | 'active' | 'completed' | 'cancelled';
  scheduled_at?: string;
  started_at?: string;
  completed_at?: string;
  segment_id?: string;          // mutually exclusive with manual_client_ids
  manual_client_ids?: string[]; // mutually exclusive with segment_id
}

Reference Pages

• CRUD & listing — list, create, get, update, delete, calendar, summary, duplicate
• Lifecycle — schedule, start-now, complete, cancel
• Actions — manage and execute campaign actions
• Statistics & audience — preview, count, events, errors, audience, statistics, reachability

Endpoint Index

Method	Endpoint	Page
GET	/wallethero-api/workspace/:workspaceId/campaigns	crud
POST	/wallethero-api/workspace/:workspaceId/campaigns	crud
GET	/wallethero-api/campaigns/calendar	crud
GET	/wallethero-api/campaigns/:id	crud
PATCH	/wallethero-api/campaigns/:id	crud
DELETE	/wallethero-api/campaigns/:id	crud
POST	/wallethero-api/campaigns/:id/duplicate	crud
GET	/wallethero-api/workspace/:workspaceId/campaigns/summary	crud
POST	/wallethero-api/campaigns/:id/schedule	lifecycle
POST	/wallethero-api/campaigns/:id/start-now	lifecycle
POST	/wallethero-api/campaigns/:id/complete	lifecycle
POST	/wallethero-api/campaigns/:id/cancel	lifecycle
GET	/wallethero-api/campaigns/:id/actions	actions
POST	/wallethero-api/campaigns/:id/actions	actions
POST	/wallethero-api/campaigns/:id/actions/reorder	actions
PATCH	/wallethero-api/campaign-actions/:id	actions
DELETE	/wallethero-api/campaign-actions/:id	actions
POST	/wallethero-api/campaign-actions/:id/execute	actions
POST	/wallethero-api/campaigns/:id/execute-all	actions
GET	/wallethero-api/campaigns/:id/preview	statistics
GET	/wallethero-api/campaigns/:id/count	statistics
GET	/wallethero-api/campaigns/:id/events	statistics
GET	/wallethero-api/campaigns/:id/errors	statistics
GET	/wallethero-api/campaigns/:id/audience	statistics
GET	/wallethero-api/campaigns/:id/statistics	statistics
GET	/wallethero-api/campaigns/:id/unreachable-audience	statistics
GET	/wallethero-api/campaigns/:id/action-stats	statistics
POST	/wallethero-api/workspace/:workspaceId/audience-reachability	statistics

SDK Example

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

// Create a campaign
const { data: campaign } = await wh.campaigns.create({
  workspace_id: "WORKSPACE_ID",
  name: "Winter Promo Push",
  segment_id: "SEGMENT_ID",
});

// Add a push notification action
await wh.campaigns.addAction(campaign.id, {
  action_type: "push_notification",
  action_config: { notification_message: "Earn double points this weekend!" },
});

// Preview the audience, then start
const preview = await wh.campaigns.previewAudience(campaign.id);
console.log(`Targeting ${preview.total} passes`);
await wh.campaigns.startNow(campaign.id);