Skip to main content
POST

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
required

Stable opaque string up to 255 chars. Same key + same body within 24h replays cached response.

Required string length: 8 - 255
Pattern: ^[A-Za-z0-9_-]{8,255}$
Accept-Language
enum<string>
default:sk

Preferred language for error messages and localized fields. One of sk, cs, en, de. Defaults to card's default_language.

Available options:
sk,
cs,
en,
de

Body

application/json

Body for POST /v1/cards. Creates a card template. type, name, description, default_language, design, form_builder and issuer are required - everything else has sensible defaults or can be added via PATCH. The mechanics block must match the chosen type. Once created, type is immutable; all other fields can be patched.

type
enum<string>
required

REQUIRED. Card mechanics type. Immutable after creation. Determines which mechanics block applies, which initial_state overrides are valid on customer enrollment, and the wallet pass layout. Notifications reach every card type, including custom.

membership and gift_card cards exist too, but they are dashboard-managed: create them there or through a connected POS, not through this endpoint. Once created, they are fully readable through this API.

Available options:
stamp,
reward,
discount,
coupon,
custom
name
required

REQUIRED. Display name (string OR per-language object). At minimum the default_language must have a value.

Required string length: 1 - 100
default_language
enum<string>
required

REQUIRED. Default language for the card. Determines which language is used when the customer's preference is not supported.

Available options:
sk,
cs,
en,
de
description
required

REQUIRED. Brief customer-facing description of the card/loyalty program. Required by Apple PKPass (description field, used for accessibility/voice-over) and Google LoyaltyClass (programName description for review approval). Can be a string OR per-language object for multi-language passes. Min 1, max 500 chars per language.

Required string length: 1 - 500
Example:
design
object
required

Visual design of the wallet pass. Required: design_mode, bg_color, text_color, icon_url (logo_url is optional; the pass falls back to text when omitted).

VISUAL LAYOUT by mode + type:

  • design_mode=standard + stamp: mechanics.stamp_icon_url + (optional custom_background_image_url)
  • design_mode=individual + stamp: mechanics.stamp_count_images (N+1 per-position images; image_url accepts a plain URL or an OPTIONAL per-language map - every position must share the same language set; each customer sees the variant in their language, else sk, else en, else the first one)
  • design_mode=standard + non-stamp: pattern_type + pattern_icon_urls + (optional custom_background_image_url) Server AUTO-GENERATES the final pattern image per supported language: pass a per-language object as card description and each language gets its own image; single-language cards (or a plain-string description) get one image. Each customer is served the image matching the language they picked at signup (fallback sk, then en, then the first one). No image URLs are needed for the standard pattern.
  • design_mode=individual + non-stamp: individual_background_image_url REQUIRED (accepts a plain URL or an OPTIONAL per-language map; each customer sees the variant in their language, else sk, else en, else the first one)

TIER OVERRIDES: tiered reward/discount cards use mechanics.tiers[i].background_image_urls (per-language) which overrides any card-level background for customers at that tier.

form_builder
object
required

REQUIRED. Signup form rendered at the public claim URL (/signup/{card_id}). ENFORCEMENT: email (system_key='email') and first_name (system_key='first_name') are ALWAYS required and CANNOT be deleted from fields[]. Server returns 422 'form_builder_missing_email_field' or 'form_builder_missing_first_name_field' if either is missing. Both fields' system_key cannot be unset, but their translations can be overridden (e.g., display 'Tel. kontakt' instead of 'Email' in Slovak). Partners can add additional system fields (last_name, phone, date_of_birth, address, consent) or custom_field references with custom labels.

issuer
object
required

REQUIRED. Issuer details. company_name is REQUIRED because it maps to Apple PKPass.organizationName (shown on lock screen) and Google LoyaltyClass.issuerName (shown in pass list). Without it, Apple shows 'Unknown Issuer' and Google rejects the pass during review.

external_id
string | null

Optional partner reference for syncing with external systems. Persisted on the card template and returned on reads (null when unset). Not unique: two templates may share a reference, so GET /v1/cards?external_id= filters and can return more than one row. Send null to clear it.

Maximum string length: 255
languages_supported
enum<string>[]

Languages this card supports. Defaults to [default_language] when omitted.

Available options:
sk,
cs,
en,
de
barcode_format
enum<string>
default:QR

Barcode format for the wallet pass. Default 'QR' (works on both Apple and Google Wallet).

Available options:
QR,
Aztec,
PDF417,
Code128,
Code39,
EAN8,
EAN13,
ITF14,
UPCA,
DataMatrix,
Codabar
purchase_amount_required
boolean
default:false

Scanner UX flag. When true, staff MUST enter a purchase amount before they can record a transaction against this card. When false, the amount field is optional (staff can record visit-only / quick-redeem transactions). Affects scanner behavior across all card types.

Example:

false

pass_fields
object
required if type = custom

The wallet pass layout - three front slots + back rows, identical model on Apple and Google (the same shape the platform's partner integrations have used in production):

The PRIMARY front area (the big number - stamps, points, balance) is owned by the card's mechanics and never configurable here. Typed values ({{custom.<key>}} of type date/number/currency/boolean) render locale-formatted on both platforms automatically.

PATCH replaces this object as a WHOLE, it does not merge per slot. Any slot you omit is REMOVED from the card. Sending {"pass_fields": {"header": {...}}} on a card that also had front_left, front_right, back or barcode_alt_text clears those. To change one slot, send the full pass_fields object including every slot you want to keep, or read the card first and send it back with your edit applied. This differs from metadata and custom on other resources, which ARE JSON Merge Patch (a per-key merge where null deletes one key).

Example:
mechanics
object
conditionally required

Type-specific mechanics block. REQUIRED but must match Card.type. Pick the matching tab. Custom = pick 'Custom (null)'. An unknown key inside mechanics (also inside a reward, a level or employee) answers 422 parameter_unknown with the full name, for example mechanics.rewards[0].colour. Before, an unknown key was ignored.

issue_limit
integer | null

Maximum customer enrollments. Null = unlimited. Capped at 100,000,000 to prevent overflow abuse. 0 and null both mean unlimited; both read back as null.

Required range: 0 <= x <= 100000000
referral
object | null

Referral program configuration.

terms_of_use
object | null

Optional terms and conditions shown on the wallet pass back side. text supports per-language (string OR object {sk, cs, en, de}) - the pass renders the customer's own language variant when present, falling back to the card's default-language text otherwise. full_url is a single URL only (no per-language variant).

metadata
object

Free-form partner key-value map.

Persisted on the card template and returned on reads. Omitted entirely when empty rather than sent as null. On PATCH the map is merged per key, so sending one key never clears the others.

links
object[]

Card-attached links shown on the wallet pass back side - business links (website/social) and a review-prompt link. Max 10 items.

Maximum array length: 10
Example:

Response

Card created.

A card template defines the loyalty program a merchant offers. The template controls visual design, mechanics (stamps/points/discount/etc.), the customer signup form, wallet pass content, and behavioral defaults. Customers are enrolled in exactly one card via POST /v1/customers. Cards are immutable on type after creation.

id
string
required

Card identifier - an opaque, server-issued token prefixed crd_. Immutable.

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

"crd_sophcrprtvpmmnwxah2lomnkee"

type
enum<string>
required

Card mechanics type. Immutable after creation. Drives which mechanics block applies, which initial_state overrides are valid on POST /v1/customers, and which wallet pass layout is used. 'custom' is partner-driven and has no built-in mechanics. Notifications reach every card type, including custom.

Available options:
stamp,
reward,
discount,
coupon,
membership,
gift_card,
custom
Example:

"stamp"

name
required

Display name of the card template. Accepts a plain string (used in all languages) OR a per-language object {sk: '...', en: '...'} for localized names.

Required string length: 1 - 100
Example:
description
required

REQUIRED. Brief customer-facing description of the card/loyalty program. Required by Apple PKPass (description field, used for accessibility/voice-over) and Google LoyaltyClass (programName description for review approval). Can be a string OR per-language object for multi-language passes. Min 1, max 500 chars per language.

Required string length: 1 - 500
Example:
languages_supported
enum<string>[]
required

Languages this card template supports. Customer.language must be one of these. Pass content and notification templates must provide values for each.

Minimum array length: 1
Available options:
sk,
cs,
en,
de
Example:
default_language
enum<string>
required

Default language used when the customer's preferred language is not in languages_supported.

Available options:
sk,
cs,
en,
de
Example:

"sk"

design
object
required

Visual design of the wallet pass. Required: design_mode, bg_color, text_color, icon_url (logo_url is optional; the pass falls back to text when omitted).

VISUAL LAYOUT by mode + type:

  • design_mode=standard + stamp: mechanics.stamp_icon_url + (optional custom_background_image_url)
  • design_mode=individual + stamp: mechanics.stamp_count_images (N+1 per-position images; image_url accepts a plain URL or an OPTIONAL per-language map - every position must share the same language set; each customer sees the variant in their language, else sk, else en, else the first one)
  • design_mode=standard + non-stamp: pattern_type + pattern_icon_urls + (optional custom_background_image_url) Server AUTO-GENERATES the final pattern image per supported language: pass a per-language object as card description and each language gets its own image; single-language cards (or a plain-string description) get one image. Each customer is served the image matching the language they picked at signup (fallback sk, then en, then the first one). No image URLs are needed for the standard pattern.
  • design_mode=individual + non-stamp: individual_background_image_url REQUIRED (accepts a plain URL or an OPTIONAL per-language map; each customer sees the variant in their language, else sk, else en, else the first one)

TIER OVERRIDES: tiered reward/discount cards use mechanics.tiers[i].background_image_urls (per-language) which overrides any card-level background for customers at that tier.

mechanics
object
required

Type-specific mechanics block. REQUIRED but must match Card.type. Pick the matching tab. Custom = pick 'Custom (null)'.

issuer
object
required

REQUIRED. Issuer details. company_name is REQUIRED because it maps to Apple PKPass.organizationName (shown on lock screen) and Google LoyaltyClass.issuerName (shown in pass list). Without it, Apple shows 'Unknown Issuer' and Google rejects the pass during review.

object
string

Resource type discriminator. Always 'card' for this resource. Useful for client libraries that handle polymorphic responses (e.g., webhooks delivering mixed event types). Server always sets it.

Allowed value: "card"
Example:

"card"

external_id
string | null

Your stable reference for this card template (e.g., your internal product SKU). Useful for syncing with external systems. Persisted on the card template and returned on reads (null when unset). Not unique: two templates may share a reference, so GET /v1/cards?external_id= filters and can return more than one row. Send null to clear it.

Maximum string length: 255
Example:

"loyalty-coffee-stamp-2026"

barcode_format
enum<string>
default:QR

Barcode format rendered on the wallet pass to identify customers at POS. QR/Aztec/PDF417/Code128 work on both Apple and Google Wallet; others are Google Wallet only.

Available options:
QR,
Aztec,
PDF417,
Code128,
Code39,
EAN8,
EAN13,
ITF14,
UPCA,
DataMatrix,
Codabar
Example:

"QR"

purchase_amount_required
boolean
default:false

Scanner UX flag. When true, staff MUST enter a purchase amount before they can record a transaction against this card. When false, the amount field is optional (staff can record visit-only / quick-redeem transactions). Affects scanner behavior across all card types.

Example:

false

pass_fields
object

The wallet pass layout - three front slots + back rows, identical model on Apple and Google (the same shape the platform's partner integrations have used in production):

The PRIMARY front area (the big number - stamps, points, balance) is owned by the card's mechanics and never configurable here. Typed values ({{custom.<key>}} of type date/number/currency/boolean) render locale-formatted on both platforms automatically.

PATCH replaces this object as a WHOLE, it does not merge per slot. Any slot you omit is REMOVED from the card. Sending {"pass_fields": {"header": {...}}} on a card that also had front_left, front_right, back or barcode_alt_text clears those. To change one slot, send the full pass_fields object including every slot you want to keep, or read the card first and send it back with your edit applied. This differs from metadata and custom on other resources, which ARE JSON Merge Patch (a per-key merge where null deletes one key).

Example:
form_builder
object

Configuration for the public customer signup form at /signup/{card_id}. Lists which fields to collect, in what order, and which are required.

issue_limit
integer | null

Maximum number of customers that can be enrolled in this card. Null = unlimited. When reached, POST /v1/customers returns 403 card_limit_reached. 0 and null both mean unlimited; both read back as null.

Required range: x >= 0
Example:

1000

issued_count
integer
read-only

Current number of customers enrolled in this card (read-only). Updated on every successful POST /v1/customers.

Required range: x >= 0
Example:

234

referral
object | null

Referral program configuration. When enabled, customers can refer friends via a unique referral URL; both parties earn a bonus when the referee enrolls and completes a qualifying action.

Example:
terms_of_use
object | null

Optional terms and conditions shown on the wallet pass back side. text supports per-language (string OR object {sk, cs, en, de}) - the pass renders the customer's own language variant when present, falling back to the card's default-language text otherwise. full_url is a single URL only (no per-language variant).

registration_url
string<uri> | null

Public signup URL where customers self-enroll. Pattern: https://vexioncards.one/signup/?id={card_id}. Share via QR code, flyer, or email. Append ?loc={location_id} for per-location attribution (signup_location_id on the resulting customer). For per-location URLs of every location with this card enabled, call GET /v1/locations and check enabled_card_ids for this card's id (or read each location's cards[] (GET /v1/locations) - every entry carries its location-scoped signup_url). We previously had registration_urls_per_location on this response, but it duplicated data that lives on Location and forced an extra refresh whenever a location toggled the card on/off.

Example:

"https://vexioncards.one/signup/?id=crd_sophcrprtvpmmnwxah2lomnkee"

metadata
object

Free-form key-value map for partner-internal IDs and integration markers. NOT rendered on the wallet pass. Shape IS enforced (422 validation_failed): max 50 keys, key must match ^[a-zA-Z0-9_]{1,40}$, values must be strings of at most 500 chars. The platform never interprets the contents.

Persisted on the card template and returned on reads. Omitted entirely when empty rather than sent as null. On PATCH the map is merged per key, so sending one key never clears the others. (Distinct from Customer.metadata, which is built and live.)

Example:
status
enum<string>
default:active

Template lifecycle. draft (created but never launched - not issuable, its public signup page turns customers away), active (issuable), paused (temporarily closed to NEW signups; existing passes keep working and keep earning), archived (retired - existing customer passes keep working, no new signups). A card created through this API is born active. DELETE archives, never destroys, and historical references stay resolvable forever.

Available options:
draft,
active,
paused,
archived
Example:

"active"

image_generation
object

Server-side pass-image generation state. Standard-design cards get their wallet pass images (the per-stamp-state strip images, or the single pattern strip) rendered automatically after create and after design edits. The card is returned immediately and images render in the background, typically within seconds. processing: rendering in progress - the pass already works and images appear as soon as they are ready. completed: all images are live. failed: rendering hit an error and is retried automatically; the card itself is unaffected. not_applicable: individual-design cards (you supply the images) and cards with no generated imagery.

created_at
integer

Unix timestamp when the card was created.

Example:

1782345600

updated_at
integer

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

Example:

1782604800

activated_at
integer | null

Unix seconds when the card FIRST went live. Stamped on the first transition to active and never overwritten, so it survives pause/reactivate and un-archive cycles. Null for a card that has never been activated (a draft).

paused_at
integer | null

Unix seconds of the most recent transition to paused. Restamped on every pause. Null for a card that has never been paused. Not cleared when the card reactivates, so it records the last pause, not the current state - read status for that.

archived_at
integer | null

Unix timestamp when the card was archived (status='archived'). Null if active.

Example:

null

links
object[]

Card-attached links shown on the wallet pass back side - business links (website/social) and a review-prompt link. Max 10 items.

Maximum array length: 10
Example:
currency
enum<string>

The business currency of this card. A business has one currency, so it is the same on every card. Set from the country of the first location and locked after the first transaction, customer balance or gift card purchase. See Money and currency.

Available options:
EUR,
CZK,
GBP,
HUF,
PLN,
RON,
CHF,
USD