Loyalty

Get a campaign

Fetch a single wallet marketing campaign, including its targeting, message content, schedule and lifecycle status. The isStranded and scheduleJobLost flags reflect the live BullMQ job state (this endpoint only, at most one Redis read): isStranded when a sending campaign has no worker draining it, scheduleJobLost when a past-due scheduled campaign lost its delayed trigger (auto-recovered hourly). They may differ briefly from the list view, which never computes them.

get/v1/loyalty/campaigns/{id}

Request

  • Base URL: https://api.prod.keyban.io
  • URL: https://api.prod.keyban.io/v1/loyalty/campaigns/{id}
  • Auth: API key in header X-Api-Key

Path parameters

idstring uuid required

Campaign ID

Response

Campaign retrieved successfully

idstring uuid required

Entity UUID

createdAtstring date-time required

Creation date (ISO 8601)

updatedAtstring date-time required

Last update date (ISO 8601)

applicationstring uuid required

Application (brand) the campaign belongs to.

namestring required

Campaign name shown in the back-office campaign list.

descriptionstring nullable

Internal note describing the campaign intent. Never sent to customers.

channelsstring[] required

Wallet channels the campaign targets — a non-empty subset of google/apple.

sendAtstring date-time nullable

Scheduled send time (RFC 3339). Null means immediate send when triggered.

status'draft' | 'scheduled' | 'sending' | 'sent' | 'finished' required

Lifecycle status. Server-managed: a campaign is always created as draft.

audienceSnapshotCountinteger nullable

Audience size frozen when sending starts: the count of opted-in accounts matching the targeting, BEFORE the per-recipient consent and frequency-cap exclusions. It can therefore be higher than the number of actual deliveries. Null until the campaign starts sending.

conversionWindowDaysinteger required

Days after sending during which conversions are measured. Defaults to 7.

sentAtstring date-time nullable

Timestamp when sending started (anchors the conversion window). Null until sent.

isStrandedboolean

Computed flag, set only on the campaign detail endpoint: true when the campaign is stuck in sending because its send job failed or vanished (no worker is draining it), so it can be resumed via POST /:id/resume. Absent on list responses and for any non-sending campaign.

scheduledImmediatelyboolean

Computed flag, set only on the POST /:id/schedule response: true when the requested sendAt was already in the past, so the campaign fires immediately instead of waiting. Absent (never false) in the nominal case where sendAt is in the future and the campaign is scheduled for later.

scheduleJobLostboolean

Computed flag, set only on the campaign detail endpoint: true when the campaign is stuck in scheduled past its due date because its delayed trigger vanished (no job will fire it). An hourly safety-net sweep re-arms it automatically, so this is informational and self-heals. Absent on list responses and for any non-scheduled or not-yet-due campaign.

Example response

{
  "application": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Summer menu launch",
  "description": "Promote the new summer menu to recent visitors.",
  "channels": [
    "google",
    "apple"
  ],
  "targeting": {
    "minPoints": 100,
    "maxPoints": 500,
    "minVisits": 3,
    "rewardTierIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  },
  "content": {
    "header": "New summer menu",
    "body": "Come and taste our new summer menu this week."
  },
  "sendAt": "2026-06-23T10:00:00Z",
  "status": "draft",
  "audienceSnapshotCount": 1234,
  "conversionWindowDays": 7,
  "sentAt": "2026-06-15T14:30:00Z",
  "scheduledImmediately": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.