Loyalty

Schedule a campaign

Schedule a draft campaign for a future send. The campaign is validated (draft status, message content present), transitions to scheduled, and a delayed job fires at sendAt to start the send automatically. Returns 202 with the campaign in scheduled. A past or present sendAt is accepted and triggers an immediate send (flagged by scheduledImmediately on the response). The schedule can be cancelled back to draft with POST /:id/cancel before it fires.

post/v1/loyalty/campaigns/{id}/schedule

Request

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

Path parameters

idstring uuid required

Campaign ID

Request body

sendAtstring date-time required

Send time (RFC 3339, UTC). The campaign transitions to scheduled and a delayed job fires at this instant. A past or present timestamp is accepted and triggers an immediate send (flagged by scheduledImmediately on the response).

Example request

{
  "sendAt": "2026-07-15T09:00:00Z"
}

Response

Campaign accepted for scheduling

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.