Cancel a scheduled notification

Cancels a scheduled broadcast (future schedule_at) whose fan-out has not started yet. Sets status: "cancelled".

An immediate (non-scheduled) broadcast is queued for delivery the moment it is accepted and can never be cancelled - even a call made seconds later returns 409 broadcast_not_cancellable. The same 409 applies to a scheduled broadcast whose fan-out has already started, and to one whose send time is less than a minute away (a job that is about to run can no longer be stopped). Repeating the cancel of a broadcast that is already cancelled returns 200. There is no recall once delivery begins; the pushes are already at the providers.

DELETE /v1/notifications/{id}

Cancel a scheduled notification

cURL

curl --request DELETE \
  --url https://api.vexioncards.one/v1/notifications/{id} \
  --header 'Authorization: Bearer <token>'

200

Cancelled

{
  "id": "ntf_01J9P0G7K9C0RYHXJ2K7A4N5MZ",
  "object": "notification",
  "title": {
    "en": "Weekend double stamps!"
  },
  "body": {
    "en": "This Saturday and Sunday every coffee earns 2 stamps."
  },
  "audience": {
    "card_ids": [
      "crd_sophcrprtvpmmnwxah2lomnkee"
    ]
  },
  "status": "cancelled",
  "schedule_at": 1782893400,
  "sent_at": null,
  "stats": {
    "total": 0,
    "audience_resolved_count": 0,
    "apple_wallet": {
      "total": 0,
      "delivered": 0,
      "failed": 0
    },
    "google_wallet": {
      "total": 0,
      "delivered": 0,
      "failed": 0
    },
    "delivered": 0,
    "failed": 0
  },
  "completed_at": null,
  "created_at": 1782800000
}

Authorizations

Authorization · string · header · required

Your secret API key as a Bearer token: Authorization: Bearer vxn_sk_.... Keys are created and scoped in the dashboard - see Authentication.

Headers

Idempotency-Key · string<uuid>

Recommended on PATCH and DELETE for safe retries.

Required string length: 8 - 255

Pattern: ^[A-Za-z0-9_-]{8,255}$

Path Parameters

id · string · required

Notification identifier (ntf_ prefix). Must be a scheduled broadcast whose fan-out has not started - a queued (immediate) broadcast can never be cancelled.

Pattern: ^ntf_[A-Za-z0-9]+$

Response

200

application/json

Cancelled notification (full object, status: "cancelled").

A broadcast push notification. Created via POST /v1/notifications, delivered asynchronously to wallet passes (Apple Wallet + Google Wallet). The stored DTO always shows the UNRENDERED template - per-recipient rendered text is not retrievable after the fact.

id · string · required

Notification identifier. Opaque, ntf_ prefix. Immutable.

Pattern: ^ntf_[A-Za-z0-9]+$

Example:

"ntf_01J9P0G7K9C0RYHXJ2K7A4N5MZ"

object · string · required

Resource type discriminator. Always 'notification'.

Allowed value: "notification"

Example:

"notification"

title · object · required

Localized title keyed by language code (en, sk, cs, de). At least one locale required. Per-locale value is plain text, 1-60 characters (Apple Wallet's lock-screen banner truncates around 60). Template variables are supported. Card-mechanics variables ({{card.balance}}, {{stamps_remaining}}, ...) require a card-scoped audience (card_ids).

Show child attributes

Example:

{ "en": "Summer special menu" }

body · object · required

Localized body keyed by language code (en, sk, cs, de). At least one locale required. Per-locale value is plain text, 1-240 characters (worst-case room after banner chrome on Apple + Google). Template variables are supported. Card-mechanics variables ({{card.balance}}, {{stamps_remaining}}, ...) require a card-scoped audience (card_ids).

Show child attributes

Example:

{
  "en": "Try the new lime lemonade for 2.50 EUR."
}

status · enum<string> · required

Broadcast lifecycle:

• queued - accepted, fan-out imminent
• scheduled - accepted with a future schedule_at; cancellable until it fires
• processing - worker batches draining
• completed - every per-recipient attempt finished (provider ack'd or retries exhausted; does NOT mean the human saw it)
• partial - finished with failure rate above the warning threshold (~5%)
• failed - catastrophic failure before deliveries (rare; safe to retry with a fresh Idempotency-Key). Reserved: NOT emitted by v1 today (see note below).
• cancelled - cancelled while queued/scheduled

failed is declared but NOT emitted by v1 today. status is DERIVED per read from four raw signals (schedule flag + fire time, fan-out start, drain completion, delivery counters); nothing records a crash that happened before any delivery was attempted, so no code path can produce failed. GET /v1/notifications?status=failed is accepted and returns an empty page rather than an error, so branching over the full enum stays safe. The other six are all live, including cancelled, which is backed by a real cancelledAt timestamp set by DELETE /v1/notifications/{id} and takes precedence over every other signal.

Available options: queued, scheduled, processing, completed, partial, failed, cancelled

Example:

"completed"

stats · object · required

Aggregate delivery counters, updated as the asynchronous fan-out drains (queue → worker batches → per-device dispatch). Starts at zero on accept. For per-recipient rows, use GET /v1/notifications/{id}/deliveries.

Show child attributes

Example:

{
  "total": 121,
  "audience_resolved_count": 121,
  "apple_wallet": { "total": 98, "delivered": 96, "failed": 2 },
  "google_wallet": { "total": 23, "delivered": 22, "failed": 1 },
  "delivered": 118,
  "failed": 3
}

created_at · integer · required

Unix seconds. Time the broadcast was accepted.

Example:

1782134400

audience · object | null

The audience filter this broadcast was sent with. Null/empty = broadcast to all active customers.

Show child attributes

Example:

{
  "card_ids": ["crd_sophcrprtvpmmnwxah2lomnkee"]
}

schedule_at · integer | null

Unix seconds when a scheduled broadcast fires. Null for immediate sends. While in the future, the broadcast is normally status: "scheduled" and cancellable via DELETE. EXCEPTION: if the audience resolved to zero recipients at accept time there is nothing to deliver now or later, so the broadcast is accepted as already finished - status is completed with every counter at 0 and audience_resolved_count: 0, it never appears under ?status=scheduled, and DELETE returns 409 broadcast_not_cancellable even though this value is still in the future. Poll on status, not on schedule_at.

Example:

null

sent_at · integer | null

Unix seconds when fan-out started - set on EVERY send (immediate and scheduled). Null only before dispatch.

Example:

1782134401

completed_at · integer | null

Unix seconds. Populated when status reaches completed, partial, or failed. Null while queued/processing.

Example:

1782134522

request_id · string

The request id of the request that ACCEPTED this broadcast. Include it in support requests: it identifies the exchange where the fan-out actually happened. On an idempotent replay (a repeat call with the same Idempotency-Key, answered with Idempotent-Replayed: true) this deliberately differs from the Vexion-Request-Id response header: the body keeps the original accept id, while the header carries the id of the replay exchange you are holding.

Example:

"req_01J9P0G7K9C0RYHXJ2K7A4N5MZ"