Customers

Send the wallet card to the customer by email or SMS

Sends (or re-sends) the wallet claim link to the customer over email, SMS, or both. Subject to a 5-minute per-channel cooldown to prevent abuse: a tight retry loop returns 429. The customer must already have the contact field for the chosen channel (email for channel=email, phone for channel=sms, both for channel=both) or the request returns 422 contact_missing_for_channel. Templates and copy follow the customer’s language, overridable via language. A successful delivery sets delivery.status='sent', returns the updated Customer, and fires customer.updated. For first-time enrolment, prefer passing deliver inline on POST /v1/customers instead of this two-step flow. In the sandbox, SMS is never sent and email goes only to your own people: POST /v1/customers/{id}/deliver answers 422 sms_not_available_in_sandbox or 422 recipient_not_allowed_in_sandbox, and both are checked before the cooldown, so channel=both never sends half.

POST

customers

{id}

deliver

curl --request POST \
  --url https://api.vexioncards.one/v1/customers/{id}/deliver \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "channel": "email",
  "language": "sk"
}
'

{
  "id": "cus_d31a90e6b8c47fb251f0",
  "object": "customer",
  "email": "lucy.morgan@example.com",
  "phone": "+421948555200",
  "first_name": "Lucia",
  "language": "sk",
  "gdpr_redacted_at": null,
  "card_id": "crd_zqpuluiwik4cs2aulxk3e54haa",
  "card_type": "custom",
  "status": null,
  "device": null,
  "installed_at": null,
  "claim_url": "https://vexioncards.one/card/add/84ad785b092fd348211c8dcc",
  "last_delivery": {
    "channel": "email",
    "status": "sent",
    "to": "lucy.morgan@example.com",
    "sent_at": 1782691800
  },
  "referral_stats": null,
  "created_at": 1782604900,
  "updated_at": 1782691800,
  "last_visited_at": null,
  "last_visited_location_id": null,
  "deleted_at": null
}

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>

required

Replay-safe key, 24h cache. UUID v4 recommended.

Required string length: 8 - 255

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

Accept-Language

enum<string>

One of en, sk, cs, de. Defaults to en.

Available options:

en,

sk,

cs,

de

Path Parameters

string

required

Customer id with cus_ prefix.

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

Body

application/json

Deliver the wallet card link to the customer by email or SMS.

channel

enum<string>

required

Where to send the claim link: email, sms, or both. The customer record must carry the matching contact (422 contact_missing_for_channel otherwise). SMS goes out only to E.164 numbers.

Available options:

email,

sms,

both

language

enum<string>

Message language. Defaults to the customer's preferred language, then the card default.

Available options:

en,

sk,

cs,

de

Response

Updated customer - last_delivery reflects this send.

string

required

Customer identifier - an opaque, server-issued token prefixed cus_. Encodes the internal record through a keyed cipher (AES-128 + an integrity tag, base32-encoded) - not decodable or guessable client-side; the prefix lets clients route on resource type without parsing the ID.

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

Example:

"cus_g2y5z2ylfkrybsthe2qnweualy"

object

string

required

Always 'customer'. Type discriminator for consumers that handle multiple resource families.

Allowed value: "customer"

card_id

string

required

Card template (crd_) this customer is enrolled in. Immutable.

external_id

string | null

Your stable reference for this customer (CRM ID, internal account number, etc.). Highest-priority dedupe field on POST.

string<email> | null

Customer's email address. Used for wallet pass delivery, account recovery, and dedupe.

Maximum string length: 255

Example:

"customer@example.com"

phone

string | null

Customer's phone number in E.164 format. Used for SMS pass delivery and dedupe.

Required string length: 8 - 16

Pattern: ^\+[1-9]\d{1,14}$

Example:

"+14155552671"

first_name

string | null

Given name. Shown on the wallet pass when configured.

last_name

string | null

Family name. Shown on the wallet pass when configured.

date_of_birth

string<date> | null

Customer's date of birth in ISO 8601 format (YYYY-MM-DD). Used for birthday campaigns and age-gated rewards.

language

enum<string>

Preferred display language for the wallet pass and notifications. Writable values are sk, cs, en, de; reads may additionally return hu, hr, or ro for legacy customers enrolled before the language set was narrowed.

Available options:

sk,

cs,

en,

de,

hu,

hr,

ro

marketing_opt_in

boolean

A record of the customer's marketing consent, stored and returned for your own use and audits. VEXiON does not apply it when sending notifications: a notification sent through the API is not filtered by this flag or by the customer's marketing switch in the dashboard. To respect opt-outs on API sends, send only to customers with marketing_opt_in true, using explicit customer_ids.

Unix timestamp when the customer requested GDPR right-to-be-forgotten. When set, all PII fields are anonymized but the skeleton record is preserved for analytics integrity. Distinct from deleted_at (soft-delete from admin or DELETE /v1/customers/{id}).

Example:

null

card_type

enum<string>

Echo of the parent card's type for routing convenience. Mirrors card.type.

Available options:

stamp,

reward,

discount,

coupon,

membership,

gift_card,

custom

card

object

Type-specific mechanics data (stamps collected, points balance, tier, gift-card balance, etc.). Shape varies per card_type.

Show child attributes

Location whose signup QR/link enrolled this customer (?loc= on the signup URL). Null for customers created via API or dashboard - only public signup-form enrollments carry it.

status

enum<string> | null

Wallet pass install state on the customer's device. installed = pass on at least one device, not_installed = signed up but pass not yet added, deleted = customer removed the pass, disputed = wallet flagged the pass. A customer with no stored status reads not_installed; the value is never null.

Available options:

installed,

not_installed,

deleted,

disputed,

null

device

enum<string> | null

Wallet platform holding the pass: apple_wallet or google_wallet. Null when no wallet pass is installed. The platform tracks Apple and Google Wallet only - any other install channel reads as null.

Available options:

apple_wallet,

google_wallet,

null

installed_at

integer | null

Unix seconds when the pass was FIRST added to a wallet (Apple/Google install callback). Null until installed. Distinct from created_at (when the customer record was created at signup) - the gap between the two is your activation funnel.

Example:

1779494400

apple_wallet_url

string | null

Direct download URL for the .pkpass file. Sent to iPhone customers via SMS or email.

google_wallet_url

string | null

Save-to-Google-Wallet URL for this customer's card, or null if not yet generated. Generated lazily: null on a freshly created customer, and populated on the first GET /v1/customers/{id} for that customer (not on create, and not on the list endpoint) - persisted after the first successful generation, so later reads return the same URL without regenerating it. A transient generation failure leaves this null; retry by reading the customer again.

claim_url

string

Public claim URL the customer visits to add the pass to their wallet. Auto-detects device and serves the right format. Treat the URL as opaque - never construct or parse it; its internal format may change.

serial_number

string

The value encoded in the customer's wallet pass QR code or barcode, and the number printed on physical cards. A merchant-assigned custom number when serial_number_locked is true; otherwise a platform-assigned 24-character hex value, or a referral link ending in it when the card has referrals enabled. NOT the customer id: to find the customer behind a scanned code, call GET /v1/customers?serial_number=<scanned value>.

serial_number_locked

boolean

True when the serial number was custom-set by staff (do not regenerate). False when auto-generated.

custom

object

Custom field VALUES for this customer, keyed by the definition's key. Validated against the card's form and the cf_ definitions - unknown keys are rejected (422 unknown_custom_field).

Value shapes by field type: text/textarea → string; number → number (integer when the definition says so); currency → integer minor units; date → YYYY / YYYY-MM / YYYY-MM-DD per granularity; boolean → true/false; select → one option value; multiselect → array of option values.

Renderable everywhere via {{custom.<key>}}: pass slots, notification title/body - typed values format in the customer's locale.

metadata

object

Partner-internal {key: value} map (max 50 keys, key ^[a-zA-Z0-9_]{1,40}$, string values ≤500 chars). NEVER rendered to the customer - for CRM ids, import batches, integration markers. Customer-facing typed data belongs in custom (validated against custom field definitions, renderable on passes/notifications).

Update semantics (JSON Merge Patch): PATCH merges per key - send only the keys you change; "key": null deletes that key; "metadata": null clears the whole map; omitting metadata leaves it untouched.

Show child attributes

last_delivery

object | null

Most recent email/SMS delivery attempt for this customer's wallet pass. Null if never delivered via API. Contains channel, destination (redacted email/phone), status, sent_at timestamp, and error message if delivery failed.

Show child attributes

referral_stats

object | null

Referral program statistics for this customer. Null when the card template has no referral program configured. All counts are non-negative integers.

Show child attributes

created_at

integer

Unix timestamp when the customer record was created (signup time).

updated_at

integer

Unix timestamp when any field on the customer was last modified.

last_visited_at

integer | null

Unix seconds of the customer's most recent confirmed transaction - ANY channel (POS, scanner, API, online). Stored denormalized for fast filtering; equals the newest ledger entry (see GET /v1/transactions), except that gift card lock, employee refill and merchant issue rows do not move it.

Example:

1782604800

level_valid_until

integer | null

Unix seconds until which the customer keeps the current discount or reward tier (level retention, mechanics.tier_demotion). It is the end of the Bratislava calendar day: a qualifying transaction on or before that day keeps the level, and the first daily run after it moves the customer down one tier. Null when level retention is off on the card, the customer is on the lowest tier, the card cannot use level retention (employee discount, Booqme or Bookio card, flat reward, fewer than 2 tiers), or the card entry is deleted or disputed. Reminders go out 14 and 3 days before this date.

Example:

1807833599

last_visited_location_id

string | null

Location of the most recent confirmed transaction - ANY channel. Stored denormalized for fast filtering; equals the newest ledger entry (see GET /v1/transactions), except that gift card lock, employee refill and merchant issue rows do not move it.

Example:

"loc_g2f2cbt7cbuz3hambazorvws2q"

deleted_at

integer | null

Unix seconds when the customer was soft-deleted (DELETE /v1/customers/{id} or dashboard). Null while active. Soft-deleted customers keep their FULL transaction ledger - history is never destroyed. Distinct from gdpr_redacted_at (right-to-be-forgotten anonymization).

curl --request POST \
  --url https://api.vexioncards.one/v1/customers/{id}/deliver \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "channel": "email",
  "language": "sk"
}
'

{
  "id": "cus_d31a90e6b8c47fb251f0",
  "object": "customer",
  "email": "lucy.morgan@example.com",
  "phone": "+421948555200",
  "first_name": "Lucia",
  "language": "sk",
  "gdpr_redacted_at": null,
  "card_id": "crd_zqpuluiwik4cs2aulxk3e54haa",
  "card_type": "custom",
  "status": null,
  "device": null,
  "installed_at": null,
  "claim_url": "https://vexioncards.one/card/add/84ad785b092fd348211c8dcc",
  "last_delivery": {
    "channel": "email",
    "status": "sent",
    "to": "lucy.morgan@example.com",
    "sent_at": 1782691800
  },
  "referral_stats": null,
  "created_at": 1782604900,
  "updated_at": 1782691800,
  "last_visited_at": null,
  "last_visited_location_id": null,
  "deleted_at": null
}

API Reference

MCP server

Customers

Cards

Transactions

Products

Notifications

Locations

Team members

Custom fields

Events

Webhook endpoints

API keys

Organization

Icons

API Reference

Send the wallet card to the customer by email or SMS

Authorizations

Headers

Path Parameters

Body

Response