Campaigns

Campaigns action guides explain identifiers, fields, permissions, effects, worked examples, verification and recovery.

Before you start

Confirm the intended environment and credential organization, then discover the current action contract. Discover and bind an authorized Campaigns workspace separately from action input. Organization privacy export and erasure span the verified organization rather than one workspace. Stored integration or journey metadata does not grant access or prove an external event.

Examples and source scope

These thirty guides distinguish retained local fixture responses with simulated Auth and sealed egress from synthetic source-only illustrations. Broad output schemas can accept partial or refusal objects; workspace archival returns an empty HTTP 204. No example proves production execution, notification delivery or privacy completion. The source revision below is reviewed source, not verified runtime adoption. Preserve each guide’s evidence limits.

Action guides

• Create a campaign batch — Campaigns: Creates one draft batch in the selected campaign/workspace. plannedCount is a plan; this creates no codes, launches no print run and proves no distribution.
• Record a batch failure — Campaigns: For an active batch, records a failure row and changes that batch to paused. It does not pause or archive the campaign.
• List campaign batches — Campaigns: Lists batch metadata for the selected campaign, newest updates first. An empty array can also mean that the campaign id is absent or outside the bound workspace; this read does not verify campaign existence.
• Update a campaign batch — Campaigns: Changes stored batch name, status or plannedCount. The source accepts the declared status set without an active-only transition guard. An update advances updatedAt even when no effective field changes.
• Complete and archive a campaign — Campaigns: Records a completion and changes an active or paused campaign to archived. Its codes subsequently fail the active-campaign validation check.
• Create a draft campaign — Campaigns: Creates one draft campaign. Optional offerId must resolve in the selected organization/workspace. Creating it neither activates redemption nor issues codes.
• Get campaign dashboard — Campaigns: Reads stored batch, code, placement and redemption counts plus counts for each journey event type. Resource identity is the request id; the dashboard response contains counts. Stored events do not establish a live provider outcome.
• Get campaign — Campaigns: Reads one non-deleted campaign in the bound organization and workspace. An absent or differently scoped campaign returns HTTP 404 campaign_not_found.
• List campaigns — Campaigns: Lists non-deleted campaigns in the bound organization and workspace, newest updates first. An empty array is valid.
• Update or activate a campaign — Campaigns: Changes campaign name, offer or draft/active/paused/archived status. Activation allows existing active codes to validate/redeem; it does not issue or distribute codes.
• Issue campaign codes — Campaigns: Issues an explicit code once, or generates count codes (default one, declared maximum 1000). It stores active code records for an existing campaign; this path does not itself require the campaign to be active.
• List issued codes — Campaigns: Lists code records in the bound organization/workspace, optionally filtered by campaignId; results are ordered newest creation first.
• Record a code redemption — Campaigns: Evaluates and records a redemption, consuming the stored overall/per-user limit where enforced. This is a write, not a validation read, discount delivery, payment charge or commission payout.
• Enable, disable or associate a code — Campaigns: Updates active/disabled status, optional batchId and stored quroSlug for one code string in this workspace. It does not change a label, call Quro, or prove a physical placement.
• Check code eligibility — Campaigns: Evaluates a code and returns HTTP 200 with valid:true or valid:false and a reason. This read does not consume redemption capacity.
• List campaign integrations — Campaigns: Lists stored application/resource links for the campaign. It does not call another application, verify a linked resource, grant access or establish provider connectivity. An absent campaign can return an empty list.
• Store a campaign integration reference — Campaigns: Stores or replaces the link keyed by organization, workspace, campaign, applicationId and purpose. It does not replace every campaign integration.
• List campaign journey events — Campaigns: Lists stored journey events for the campaign, newest occurrence first. Subject and external references are stored attribution, not executed follow-ups. An absent campaign can return an empty list.
• Append a campaign journey event — Campaigns: Appends one local event after checking campaign existence and any supplied codeId/placementId belongs to the same campaign/workspace. It does not prove a scan, booking, signup or provider outcome occurred.
• Create a reusable offer — Campaigns: Stores one workspace offer with kind, numeric value, optional label and rules. This neither activates a campaign nor issues a code.
• List workspace offers — Campaigns: Lists stored offers in the bound organization/workspace, newest update first. Reading an offer does not establish that any campaign or code uses it.
• Erase organization-owned Campaigns data — Campaigns: After exact organization authorization and literal ERASE confirmation, checks active campaigns, active batches and placed assets; blockers return 409 without proceeding.
• Export Campaigns organization data — Campaigns: Exports the explicitly authorized organization across Campaigns stores, with secret-like fields redacted. It excludes canonical platform identity, delivered Notify records, provider credentials and backups. Workspace recipient settings are not included in this export. It does not erase records.
• Record a physical-code placement — Campaigns: Creates a local planned placement for an existing code-record id in the selected campaign/workspace. No physical delivery, printing or provider operation is executed.
• List campaign placements — Campaigns: Lists stored physical-code placement metadata. Recorded status and timestamps do not establish the current physical location of an asset. An absent campaign can return an empty list.
• Update a recorded placement — Campaigns: Updates local details or planned/placed/recovered/lost status. Moving to placed can fill placedAt, and moving to recovered/lost can fill endedAt; these timestamps do not establish actual asset location.
• List campaign redemptions — Campaigns: Reads the campaign redemption ledger and sums stored value and commissionAccrued. It does not redeem a code, charge a payment, pay commission or send a notification. A missing campaign returns HTTP 404 campaign_not_found.
• Read the Campaigns widget — Campaigns: Reads a canonical workspace-scoped v3 stats widget using bounded local queries. Missing workspace/data may yield an empty state; query failure can yield unavailable. Neither state proves zero organization-wide activity.
• Archive an empty Campaigns workspace — Campaigns: Checks app-local emptiness, requests canonical Auth archival, then deletes the local identity mirror. The source does not permanently delete canonical workspace identity.
• Set the Campaigns notification recipient — Campaigns: Stores one nonempty userId in the selected workspace’s app-local setting, replacing the stored recipient. It does not verify that user’s current membership, delivery eligibility or preferences and sends no notification by itself.

Change log

Prepared 30 reviewed action-guide links for this Reference collection. Publication and reader verification remain separate from preparation.