Notifications

Retrieve a notification

Returns the notification object - the single source of truth for broadcast state: lifecycle status (queued/scheduled/processing/completed/partial/failed/cancelled), aggregate per-channel stats, and the lifecycle timestamps (schedule_at, sent_at, completed_at).

Need per-recipient granularity (“did customer X get it on which device”)? That’s GET /v1/notifications/{id}/deliveries - an unbounded row collection that cannot live inline on this DTO.

Polling this endpoint is fine for short-lived broadcasts; for high-volume monitoring prefer the notification.delivery_updated webhook. The DTO always shows the unrendered template - per-recipient rendered text is not retrievable.

Scope: notifications:read.

GET

notifications

{id}

Retrieve a notification

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vexioncards.one/v1/notifications/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "ntf_01J9P0G7K9C0RYHXJ2K7A4N5MZ",
  "object": "notification",
  "title": {
    "en": "Summer special menu"
  },
  "body": {
    "en": "Try the new lime lemonade for 2.50 EUR."
  },
  "audience": {
    "card_ids": [
      "crd_sophcrprtvpmmnwxah2lomnkee"
    ]
  },
  "status": "completed",
  "schedule_at": null,
  "sent_at": 1782134401,
  "stats": {
    "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": 1782134400,
  "completed_at": 1782134522,
  "request_id": "req_01J9P0G7K9C0RYHXJ2K7A4N5MZ"
}

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.

Path Parameters

string

required

Notification identifier (ntf_ prefix).

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

Response

Notification.

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.

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"

Retrieve a notification

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

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vexioncards.one/v1/notifications/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "ntf_01J9P0G7K9C0RYHXJ2K7A4N5MZ",
  "object": "notification",
  "title": {
    "en": "Summer special menu"
  },
  "body": {
    "en": "Try the new lime lemonade for 2.50 EUR."
  },
  "audience": {
    "card_ids": [
      "crd_sophcrprtvpmmnwxah2lomnkee"
    ]
  },
  "status": "completed",
  "schedule_at": null,
  "sent_at": 1782134401,
  "stats": {
    "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": 1782134400,
  "completed_at": 1782134522,
  "request_id": "req_01J9P0G7K9C0RYHXJ2K7A4N5MZ"
}

API Reference

MCP server

Customers

Cards

Transactions

Products

Notifications

Locations

Team members

Custom fields

Events

Webhook endpoints

API keys

Organization

Icons

API Reference

Retrieve a notification

Authorizations

Path Parameters

Response