# VEXiON cards > VEXiON cards public API, integrations, and knowledge base. Build loyalty programs, gift cards, and digital wallet passes for any POS or e-commerce platform. - [Knowledge Base (104 pages)](https://vexioncards.mintlify.app/_llms/en/knowledge-base.txt): Getting Started, Cards, Managing Existing Cards, Customers, Scanner, Notifications, Settings, Integrations. ## API Reference ### API Reference - [Introduction](https://vexioncards.mintlify.app/api-reference/introduction.md): Understand the base URL, authentication, response codes, and headers you'll use everywhere. - [Quickstart](https://vexioncards.mintlify.app/api-reference/quickstart.md): Enroll a customer and award their first stamp - five minutes, three requests. - [Custom Cards](https://vexioncards.mintlify.app/api-reference/custom-cards.md): The card type with no loyalty mechanics: model your own data with custom fields, write it per customer, and render it on the wallet pass. - [Testing and environments](https://vexioncards.mintlify.app/api-reference/test-mode.md): Build against a sandbox environment, then switch to production by changing the base URL and the key. - [Pagination](https://vexioncards.mintlify.app/api-reference/pagination.md): How to page through list endpoints using cursor pagination. - [Rate Limits](https://vexioncards.mintlify.app/api-reference/rate-limits.md): How rate limiting works, per-endpoint limits, and how to handle 429 responses. - [Idempotency](https://vexioncards.mintlify.app/api-reference/idempotency.md): Make POST requests safe to retry using the Idempotency-Key header. - [Errors](https://vexioncards.mintlify.app/api-reference/errors.md): The error envelope, common error codes, and how to debug failed requests. - [Money and currency](https://vexioncards.mintlify.app/api-reference/money-and-currency.md): How amounts, currencies and money limits work in the VEXiON cards API: minor units, the business currency, the largest bill and cashback limits. - [Versioning](https://vexioncards.mintlify.app/api-reference/versioning.md): URL-versioned major, additive-only inside v1. Bug fixes and stricter validation ship with a dated changelog entry. - [Changelog](https://vexioncards.mintlify.app/api-reference/changelog.md): Every change to the VEXiON cards Public API, dated. Entries are never deleted or rewritten. - [Webhooks](https://vexioncards.mintlify.app/api-reference/webhooks.md): Receive events the moment they happen - HMAC verification, retries, and the security checklist. ### MCP server - [VEXiON MCP server](https://vexioncards.mintlify.app/ai/mcp-server.md): Run your loyalty program from Claude, ChatGPT, Cursor and other AI assistants. Connect once, then look up customers, record transactions, build cards and send notifications in plain language. - [Permissions and security](https://vexioncards.mintlify.app/ai/mcp-permissions.md): Choose what an AI assistant may do in your business, see what it can never do, revoke access at any time, and report a security problem. - [Tools](https://vexioncards.mintlify.app/ai/mcp-tools.md): All 31 tools of the VEXiON MCP server: what each does, the access it needs, which ones ask for confirmation, and the limits for notifications and reports. ### Customers - [List customers](https://vexioncards.mintlify.app/api-reference/customers/list-customers.md): Returns a cursor-paginated list of customers in the calling organization, sorted by `created_at` **descending** (newest first). - [Upsert a customer](https://vexioncards.mintlify.app/api-reference/customers/upsert-a-customer.md): Enrolls a new customer on a specific card template, or upserts an existing one. - [Retrieve a customer](https://vexioncards.mintlify.app/api-reference/customers/retrieve-a-customer.md): Retrieves a single customer by ID. - [Delete a customer (GDPR soft-delete)](https://vexioncards.mintlify.app/api-reference/customers/delete-a-customer-gdpr-soft-delete.md): Removes a customer. Two modes, selected by the `mode` query parameter. - [Update a customer](https://vexioncards.mintlify.app/api-reference/customers/update-a-customer.md): Updates a customer record. Only fields present in the body are changed. - [Send the wallet card to the customer by email or SMS](https://vexioncards.mintlify.app/api-reference/customers/send-the-wallet-card-to-the-customer-by-email-or-sms.md): 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`… ### Cards - [List card templates](https://vexioncards.mintlify.app/api-reference/cards/list-card-templates.md): Returns a cursor-paginated list of card TEMPLATES in the calling organization. - [Create a card template](https://vexioncards.mintlify.app/api-reference/cards/create-a-card-template.md): Creates a new card template. - [Retrieve a card template](https://vexioncards.mintlify.app/api-reference/cards/retrieve-a-card-template.md): Retrieve a single card template by id. Returns the full Card object including design, pass_fields, mechanics, form_builder, referral configuration, issuer details, terms, registration URLs (with per-location variants), and live issued_count. Returns 404 if the card does not exist or is archived in a… - [Archive a card template (soft delete)](https://vexioncards.mintlify.app/api-reference/cards/archive-a-card-template-soft-delete.md): Archive a card template (soft delete). Existing customers enrolled in the card keep their wallet passes and continue to earn/redeem; the card is removed from the public catalog and POST /v1/customers with this card_id returns 404. To permanently delete with GDPR right-to-be-forgotten (PII anonymizat… - [Update a card template](https://vexioncards.mintlify.app/api-reference/cards/update-a-card-template.md): Update a card template. Send only the fields you want to change (partial update). The card.type is IMMUTABLE - to change type, archive this card and create a new one. The card.id is also immutable. Most updates take effect immediately and propagate to all enrolled customers' wallet passes via silent… - [Reissue a reusable coupon](https://vexioncards.mintlify.app/api-reference/cards/reissue-a-reusable-coupon.md): Mass-reactivates a reusable coupon: every holder whose `couponstatus` is currently `redeemed` flips back to usable (the wallet pass QR reappears, the offer field renders again), and the refreshed pass content is pushed to every installed holder so the change is visible without asking anyone to reins… ### Transactions - [List transactions](https://vexioncards.mintlify.app/api-reference/transactions/list-transactions.md): Lists ledger entries newest first (`created_at desc, id desc` tiebreak). Cursor pagination: default 25, max 100; filters compose with the cursor. - [Create a transaction](https://vexioncards.mintlify.app/api-reference/transactions/create-a-transaction.md): Records a loyalty action against a customer's card. You describe the real-world event with exactly **two verbs** - `award` or `redeem` - and the server derives the concrete `type`, computes the balance, and snapshots tier state. - [Retrieve a transaction](https://vexioncards.mintlify.app/api-reference/transactions/retrieve-a-transaction.md): Returns a single ledger entry by id. - [Reverse a transaction](https://vexioncards.mintlify.app/api-reference/transactions/reverse-a-transaction.md): Posts a compensating entry that exactly negates the original. The reversal is itself a transaction (`kind: "reversal"`, `type: "reversal"`, original type under `reverses.type`); the original becomes `reversed: true` with a `reversed_by` pointer. **Both rows stay in the ledger forever.** ### Products - [List products](https://vexioncards.mintlify.app/api-reference/products/list-products.md): Lists catalog entries **org-wide**, newest first - filter by `location_id` to see one location's catalog. Scope: `products:read`. - [Create a product](https://vexioncards.mintlify.app/api-reference/products/create-a-product.md): Creates a **manual catalog entry** at one location. Scope: `products:write`. - [Retrieve a product](https://vexioncards.mintlify.app/api-reference/products/retrieve-a-product.md): Returns one catalog entry. POS-synced products carry a read-only `pos_ref` (the mapping to the location's till - sync-owned, vendor never surfaced); manual and API entries have `pos_ref: null`. Scope: `products:read`. - [Update a product](https://vexioncards.mintlify.app/api-reference/products/update-a-product.md): Edits catalog metadata. Scope: `products:write`. ### Notifications - [List notifications](https://vexioncards.mintlify.app/api-reference/notifications/list-notifications.md): Returns a cursor-paginated list of broadcasts in the calling organization, newest first. - [Send a notification](https://vexioncards.mintlify.app/api-reference/notifications/send-a-notification.md): Sends a broadcast push notification to wallet passes (Apple Wallet + Google Wallet). Scope: `notifications:send`. and an `Idempotency-Key` header. - [Retrieve a notification](https://vexioncards.mintlify.app/api-reference/notifications/retrieve-a-notification.md): 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`). - [Cancel a scheduled notification](https://vexioncards.mintlify.app/api-reference/notifications/cancel-a-scheduled-notification.md): Cancels a **scheduled** broadcast (future `schedule_at`) whose fan-out has not started yet. Sets `status: "cancelled"`. - [List per-recipient deliveries](https://vexioncards.mintlify.app/api-reference/notifications/list-per-recipient-deliveries.md): Returns the per-recipient, per-device delivery rows for one broadcast - the answer to "did customer X receive it, on which device, and why not". ### Locations - [List locations](https://vexioncards.mintlify.app/api-reference/locations/list-locations.md): Lists your locations, newest first - each row is the **full Location object**: address + pin, geo notification, enabled cards with their per-location signup URLs, assigned team, and POS-bridge status. Organizations have few locations, so no slim row shape exists; one call gives you everything the da… - [Retrieve a location](https://vexioncards.mintlify.app/api-reference/locations/retrieve-a-location.md): Returns one location - the complete picture in a single call. Scope: `locations:read`. - [Update a location](https://vexioncards.mintlify.app/api-reference/locations/update-a-location.md): Edits a location. Scope: `locations:write`. ### Team members - [List team members](https://vexioncards.mintlify.app/api-reference/team-members/list-team-members.md): Lists team members, newest first. Scope: `team_members:read`. **Default excludes terminal states** - filter `status=revoked` (dashboard-revoked) or `status=expired` (auto-expired scanners) explicitly to audit past staff (their records are preserved forever so `Transaction.team_member_id` history sta… - [Create a team member](https://vexioncards.mintlify.app/api-reference/team-members/create-a-team-member.md): Adds a staff account. Scope: `team_members:write`. Pick the flow with `mode`: - [Retrieve a team member](https://vexioncards.mintlify.app/api-reference/team-members/retrieve-a-team-member.md): Returns one team member by `tm_` id - including `revoked` members, which the default listing hides (their records are preserved so POS transaction history stays attributable). Scope: `team_members:read`. - [Update a team member](https://vexioncards.mintlify.app/api-reference/team-members/update-a-team-member.md): Edits an `invited` or `active` member. Scope: `team_members:write`. - [Resend an invitation](https://vexioncards.mintlify.app/api-reference/team-members/resend-an-invitation.md): Re-sends the invitation email to a member still in `status: "invited"` - the previous accept link is superseded. Use when the first email was lost or the link aged out. Scope: `team_members:write`. ### Custom fields - [List custom fields](https://vexioncards.mintlify.app/api-reference/custom-fields/list-custom-fields.md): Lists your reusable custom-field definitions, cursor-paginated, with live usage bookkeeping on every row: `usage_count` and `cards_using[]` show exactly which card templates reference each field - the numbers that decide which edits are allowed (renames, type changes, and option removals are blocked… - [Create a custom field](https://vexioncards.mintlify.app/api-reference/custom-fields/create-a-custom-field.md): Creates a reusable field definition. Scope: `custom_fields:write`. - [Retrieve a custom field](https://vexioncards.mintlify.app/api-reference/custom-fields/retrieve-a-custom-field.md): Returns one field definition with live usage bookkeeping (`usage_count`, `cards_using[]`). Scope: `custom_fields:read`. - [Delete a custom field](https://vexioncards.mintlify.app/api-reference/custom-fields/delete-a-custom-field.md): Deletes a field definition - only when nothing references it (`usage_count` must be 0, otherwise `409 custom_field_in_use`; detach it from every card's `form_builder` first). Scope: `custom_fields:write`. - [Update a custom field](https://vexioncards.mintlify.app/api-reference/custom-fields/update-a-custom-field.md): Lifecycle-gated edit. Scope: `custom_fields:write`. What's allowed depends on whether the field is in use (`usage_count > 0`): ### Events - [List events](https://vexioncards.mintlify.app/api-reference/events/list-events.md): Account-wide feed of domain events that fanned out to at least one enabled webhook endpoint, newest first. Each row carries the same envelope content a subscribed receiver was pushed - useful for reconciliation, backfilling a receiver that was down, or building your own audit trail without inspectin… ### Webhook endpoints - [List webhook endpoints](https://vexioncards.mintlify.app/api-reference/webhook-endpoints/list-webhook-endpoints.md): Lists your registered webhook receivers, cursor-paginated (default 25, max 100), newest first. Filter by `status` to find `auto_disabled` endpoints that need attention after sustained failures. - [Create a webhook endpoint](https://vexioncards.mintlify.app/api-reference/webhook-endpoints/create-a-webhook-endpoint.md): ## Delivery retries - [List catalog event types](https://vexioncards.mintlify.app/api-reference/webhook-endpoints/list-catalog-event-types.md): Returns the full, fixed catalog of webhook event names your integration can subscribe to (the same 22-name `WebhookEventName` enum accepted by `enabled_events`), each with a one-line description of when it fires. Not paginated - the catalog is small and changes only alongside a versioned API bump, n… - [Retrieve a webhook endpoint](https://vexioncards.mintlify.app/api-reference/webhook-endpoints/retrieve-a-webhook-endpoint.md): Returns one webhook endpoint: its URL, subscribed events, status, and pinned `api_version` - everything except the `secret`, which only ever appears in create and rotate responses (lost secret = rotate). - [Delete a webhook endpoint](https://vexioncards.mintlify.app/api-reference/webhook-endpoints/delete-a-webhook-endpoint.md): Deletes the endpoint. In-flight retries are cancelled. Past delivery records stay readable for 90 days via the deliveries listing. - [Update a webhook endpoint](https://vexioncards.mintlify.app/api-reference/webhook-endpoints/update-a-webhook-endpoint.md): Updates `url`, `description`, `enabled_events`, or `status`. URL changes re-run SSRF validation. `api_version` is **immutable** - create a new endpoint to move to a newer date version. - [List recent deliveries](https://vexioncards.mintlify.app/api-reference/webhook-endpoints/list-recent-deliveries.md): Returns the last **90 days** of delivery attempts for this endpoint, newest first. One row per attempt including retries - high volume; use `limit=100` to drain faster. - [Retry (resend) a webhook delivery](https://vexioncards.mintlify.app/api-reference/webhook-endpoints/retry-resend-a-webhook-delivery.md): Manually re-send a past delivery - the manual counterpart to the automatic 12-attempt retry. A new delivery attempt is created for the SAME event: it carries the same `webhook-id` (event id) as the original, so an idempotent receiver de-duplicates it against the first delivery. The original delivery… - [Rotate the signing secret](https://vexioncards.mintlify.app/api-reference/webhook-endpoints/rotate-the-signing-secret.md): Mints a new signing secret and returns it - the only other place a secret is ever visible. Scope: `webhooks:manage`. - [Send a test event](https://vexioncards.mintlify.app/api-reference/webhook-endpoints/send-a-test-event.md): Sends a synthetic event to the endpoint **synchronously** and returns the delivery result - wire up your receiver, then prove the whole path (TLS, signature verification, 2xx) in one call before going live. ### API keys - [Verify the calling key](https://vexioncards.mintlify.app/api-reference/api-keys/verify-the-calling-key.md): The **whoami** endpoint - returns the calling key's own object: scopes, status, and effective rate limits. Never any secret material (`masked_key` only). ### Organization - [Retrieve your organization](https://vexioncards.mintlify.app/api-reference/organization/retrieve-your-organization.md): **Scope: `organization:read`.** Added 2026-07-27 (owner-approved versioned API change, v1 scope registry reopened from twelve to thirteen scopes) - this endpoint used to require no scope at all, so any valid key for the organization could read it regardless of its granted scopes; that gap is now clo… - [List invoices](https://vexioncards.mintlify.app/api-reference/organization/list-invoices.md): Returns issued subscription invoices, newest first, cursor-paginated (default 25, max 100). - [Retrieve an invoice](https://vexioncards.mintlify.app/api-reference/organization/retrieve-an-invoice.md): Returns a single invoice with a **freshly signed** `pdf_url` (1-hour TTL). Download promptly; the url itself expires per S3's own presigned-URL rules - an expired link returns S3's own `403 Forbidden` (an XML body, not the VEXiON JSON error envelope, since the request goes straight to S3 and never r… ### Icons - [List icons](https://vexioncards.mintlify.app/api-reference/icons/list-icons.md): Browse the VEXiON cards 3D icon library. 10,000+ icons across 23 categories (Animals, Food & Drink, Technology & Media, etc.) for use as stamp_icon_url on stamp cards or pattern_icon_urls[] on non-stamp cards. ### API Reference - [Webhook event delivery](https://vexioncards.mintlify.app/api-reference/webhook-event-delivery.md): The envelope this API sends for EVERY webhook event, regardless of which event fired it - see the WebhookEventName enum for the full catalog (customer.*, card.*, transaction.*, notification.*, location.updated, team_member.*, webhook_endpoint.delivery_failed, custom_field.*, product.*). One generic… ## OpenAPI Specs - [openapi](/openapi.json) > The links below point to documentation indexes. Follow each `/_llms/` index recursively until you reach documentation pages. ## Indexes - [English / Knowledge Base (104 pages)](https://vexioncards.mintlify.app/_llms/en/knowledge-base.txt): Getting Started, Cards, Managing Existing Cards, Customers, Scanner, Notifications, Settings, Integrations. - [Czech (174 pages)](https://vexioncards.mintlify.app/_llms/cs.txt): API referencia, Centrum pomoci. - [Czech / Centrum pomoci (104 pages)](https://vexioncards.mintlify.app/_llms/cs/centrum-pomoci.txt): Začíname, Karty, Správa existujúcich kariet, Zákazníci, Skener, Notifikácie, Nastavenia, Integrácie. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.