> ## Documentation Index
> Fetch the complete documentation index at: https://vexioncards.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> 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.

The server lists **31 tools** for an OAuth connection and 30 for an API key (an API key has no `list_businesses`). You do not call them yourself: the assistant picks the right one from your request. This page tells you what each one can do, so you know what to allow.

A tool appears only if your connection holds the access it needs. With OAuth that is the [access level](https://vexioncards.mintlify.site/ai/mcp-permissions.md) you chose. With several businesses, the list is the union over the businesses: a tool appears if at least one business allows it. With an API key it is the key's scopes.

**Type** shows whether a tool only reads (**Read**), changes data (**Write**), or reaches a customer and needs a confirmation (**Confirm**).

> [!NOTE]
>
> You choose the businesses on the VEXiON consent page when you connect. The tool `list_businesses` shows which ones the connection can use. `select_organization` is only a fallback for old connections that have no stored choice. It asks which business to use and remembers the answer for that app. It is not counted in the 31.

## Several businesses

One OAuth connection can cover several businesses, each with its own access level. An API key stays one key for one business.

* **`organization_id`**: every tool takes this argument. It is the public organization id of the business, as returned by `list_businesses` and `get_account_overview`. It is required when the connection has 2 or more businesses. It is optional with 1. The assistant normally fills it in itself. You only name the business, for example "visits at Brew Haven last week".
* **Answers**: with several businesses, each answer starts with "Business: Name (org\_id)."
* **Checked per business**: a tool works in a business only if the access of that business allows it. A call for a business without that access is refused with a message that names the business.
* **Unavailable businesses**: a business that becomes unavailable (admin role lost, left VEXiON PRO) is shown as unavailable by `list_businesses`. The other businesses keep working. A paused business stays listed, but calls for it are refused with the account-state message.
* **Confirmations**: a confirmation for a customer message belongs to one business. It never works for another business.

## Start here

| Tool | What it does | Needs | Type |
| - | - | - | - |
| `list_businesses` | Lists the businesses the connection can use. For each business it shows the access level, and which businesses are unavailable right now and why. The assistant uses it to find the `organization_id` of a business. OAuth connections only: an API key has one business and does not list this tool. | Nothing (no scope) | Read |
| `get_account_overview` | Returns your business (name, plan, limits and usage, including how many customers you have) and a short list of your locations and cards: names, types, status and how many of each card were issued. The assistant uses it to find the right card and location, then reads the details with `get_card` or `get_location`. Lists up to 100 locations and 100 cards, and leaves out any part your connection cannot read. | Business | Read |

## Cards

| Tool | What it does | Needs | Type |
| - | - | - | - |
| `list_cards` | Lists your card templates (stamp, reward, discount, coupon, membership, gift card, custom). Archived cards are left out unless asked for. | Cards: read | Read |
| `get_card` | Shows one card: design, rules and how many were issued. | Cards: read | Read |
| `list_icons` | Browses the icon library (about 10,000 icons) to pick stamp icons for a card design. | Cards: read | Read |
| `create_card` | Creates a card. It is **live immediately** and customers can sign up, so the assistant should confirm the design with you first. Custom cards cannot be created this way. | Cards: write | Write |
| `update_card` | Changes a card. The change appears on **every pass already installed**. Switching levels on (`earn_mode` tiered) places every customer in a level from their past purchases. A card with levels needs at least one level with a multiplier of 1 or more. Cashback is limited to 30 percent (60 percent per level), a card has at most 20 rewards, and an unknown key inside `mechanics` is refused. | Cards: write | Write |

## Customers

| Tool | What it does | Needs | Type |
| - | - | - | - |
| `list_customers` | Finds customers by email, phone, scanned pass value, card, location, wallet status or sign-up dates. There is no name search. At most 100 per page. | Customers: read | Read |
| `get_customer` | Shows one customer: profile, card balance (stamps, points, level, or credit in money on a cashback card) and their last 20 transactions. | Customers: read, Transactions: read | Read |
| `summarize_customers` | Report on new sign-ups for a date range: how many, wallet installs, grouped by day, week, month, card, location, device or status. Returns counts only, never names or contact details. | Customers: read | Read |
| `create_customer` | Adds a customer to a card. If the same email, phone or reference already exists on that card, it updates that customer instead of creating a duplicate. Does not send the card. | Customers: write | Write |
| `update_customer` | Changes a customer's name, phone, date of birth, language, reference and custom values. It never changes marketing consent, and email changes stay in the dashboard. | Customers: write | Write |
| `send_card_to_customer` | Emails one customer the link to add their card to Apple Wallet or Google Wallet. Email only. | Customers: write, read | **Confirm** |

## Transactions

| Tool | What it does | Needs | Type |
| - | - | - | - |
| `list_transactions` | Lists individual transactions, newest first, up to 100 per page. For totals and trends the assistant uses `summarize_transactions` instead. | Transactions: read | Read |
| `get_transaction` | Shows one transaction in full, including whether it was reversed. | Transactions: read | Read |
| `summarize_transactions` | Report on transactions for a date range: counts, unique customers, awards, redemptions and sums, grouped by day, week, month, card, location, type or action. Follows the same rules as the dashboard. Counts and sums only, no personal data. | Transactions: read | Read |
| `create_transaction` | Records a transaction for one customer: add stamps or points, record spend, or redeem a reward. On a cashback card the amount is in points, also when redeeming: the credit the customer sees is points times the card's `cashback_point_value`. Updates the customer's pass and can trigger your automatic messages. Gift card, membership and custom cards are refused. `external_id` is required: the assistant keeps the same `external_id` when it retries the same purchase, so a retry books once, and uses a new one for every new purchase, so two identical purchases both book. `currency` is optional and must be the business currency. The bill and `value` have limits, see [Money and currency](https://vexioncards.mintlify.site/api-reference/money-and-currency.md). | Transactions: write | Write |
| `reverse_transaction` | Undoes a transaction that was recorded through the API. Reverses the whole transaction, once. A reversal cannot be reversed. | Transactions: write, read | **Confirm** |

## Notifications

| Tool | What it does | Needs | Type |
| - | - | - | - |
| `list_notifications` | Lists push notifications sent to wallet cards, newest first, with status and delivery counts. | Notifications: read | Read |
| `get_notification` | Shows one notification: text, audience, status, schedule and delivery counts. | Notifications: read | Read |
| `list_notification_deliveries` | Shows, for one notification, which customer and wallet it reached and whether it arrived. | Notifications: read | Read |
| `send_notification` | Sends a push notification to customers' lock screens, now or scheduled. Reaches real people and cannot be recalled. | Notifications: send | **Confirm** |
| `cancel_notification` | Cancels a notification that is scheduled for later, while its send time is more than a minute away. | Notifications: send | Write |

## Products and locations

| Tool | What it does | Needs | Type |
| - | - | - | - |
| `list_products` | Lists the product catalog used to match transaction lines. | Products: read | Read |
| `get_product` | Shows one product: name, SKU, category, tags, reference price and whether it is archived. | Products: read | Read |
| `create_product` | Adds a product to the catalog of one location. Products that come from a till cannot be added here. | Products: write | Write |
| `update_product` | Changes a product. Setting it inactive archives it; products cannot be deleted. | Products: write | Write |
| `list_locations` | Lists your locations (stores). | Locations: read | Read |
| `get_location` | Shows one location: name, address, map position, near-store message and active cards. | Locations: read | Read |
| `update_location` | Changes a location's name, address, map position, near-store message or active cards. A card removed from a location can no longer be scanned or issued there. | Locations: write | Write |

## Settings

| Tool | What it does | Needs | Type |
| - | - | - | - |
| `list_custom_fields` | Lists your custom customer fields (key, label, type and options) so the assistant can fill them in correctly. | Custom fields: read (always included with OAuth access) | Read |

## Tools that ask for confirmation

Three tools reach real people or cannot be undone. They always work in two steps, so nothing happens on the first message.

| Tool | Why it needs a preview |
| - | - |
| `send_notification` | A push notification cannot be recalled once sent. |
| `send_card_to_customer` | It sends a real email to a customer. |
| `reverse_transaction` | A reversal changes a customer's balance and cannot be reversed. |

**1. Preview**

The assistant calls the tool without confirming. VEXiON checks the request and returns a **preview**: what would be sent or changed. For a notification that is the text and the audience filters. The number of recipients is not known before sending. Nothing has happened yet.

**2. You decide**

The assistant shows you the preview. Read it. If it is not what you want, say so and nothing is sent.

**3. Confirm**

When you agree, the assistant calls the tool again with the confirmation it received. VEXiON then carries out exactly the previewed action.

A confirmation works only once, only for the same business and exactly the same details, and only for 10 minutes. If the assistant changes the message or the audience after the preview, the old confirmation is refused and a new preview is needed. If a confirmed action fails in a way that leaves its result unknown, the assistant is told it **may already have been done** and is not allowed to repeat it. It checks first.

> [!TIP]
>
> Turn on your AI app's tool-approval setting, if it has one, so you also see each tool call before it runs. This is a second check on top of the VEXiON preview.

Two other tools also change what customers see, and they do not need a confirmation, so read what the assistant proposes before you agree:

* `create_card` makes a card **live at once**. Customers can sign up straight away.
* `update_card` and `update_location` change every installed pass for the cards involved.

Writing a transaction or changing a card also updates customers' wallet passes and can trigger your business's own automatic messages, for example when a reward is reached.

## Notification rules

A push notification appears on customers' lock screens and cannot be recalled.

| Rule | Detail |
| - | - |
| **One language per send** | Title (up to 60 characters) and body (up to 240) are plain text in one language. No `{{variables}}`. |
| **Audience** | Empty means every active customer with a card installed in a wallet. Filters (cards, customers, locations) combine with AND, so each one you add narrows the audience. |
| **Several languages** | Send one notification per language. See below. |
| **Scheduling** | Up to 90 days ahead. A scheduled notification can be cancelled until one minute before its send time. After that it cannot be stopped. |
| **Frequency** | 1 notification per minute and 50 per day for your business. The limit is shared by every connected AI app (per API key when a key is used). |

> [!WARNING]
>
> **The message goes out in your business's name.** It reaches the members of your own card. You are responsible for the content and for the direct marketing rules that apply to you. Promote only your own goods and services, never offers of third parties. Members who turned off marketing messages for that card do not receive it.

### Sending in more than one language

A notification has one language. For customers who speak different languages, the assistant sends one notification per language, using each customer's saved language:

**1. Group your customers by language**

The assistant reads each customer's language from the customer list. A customer with no saved language counts as English.

**2. Write one message per language**

It writes the title and body in each language and puts only that language's customers in the audience, up to 1,000 customers per send.

**3. Preview and confirm each one**

You see a preview for each language and confirm each separately.

Because sends are limited to 1 per minute and 50 per day, plan the order. For more than about 1,000 customers per language, use the VEXiON dashboard or a single language.

## Date filters on lists

`list_customers` and `list_transactions` filter by date with these arguments. Each takes Unix seconds or an ISO 8601 date-time.

| Argument | Tools | Meaning |
| - | - | - |
| `created_gte`, `created_lte` | `list_customers`, `list_transactions` | Created at or after, and at or before, this time. For customers: when they signed up. For transactions: `created_at`, the time VEXiON recorded the row. |
| `updated_gte`, `updated_lte` | `list_customers` | Changed at or after, and at or before, this time. |

The names use underscores because AI apps such as Claude accept only letters, digits, `_`, `.` and `-` in argument names. The [REST API](https://vexioncards.mintlify.site/api-reference/pagination.md) keeps its own names (`created[gte]` and so on) and is unchanged. The MCP server still accepts the old bracket names `created[gte]`, `created[lte]`, `updated[gte]` and `updated[lte]` for existing scripts; they are no longer listed in the tool definitions. If you send both spellings, the underscore name wins.

## Reports and large lists

Reports count rows instead of reading them one by one, but they still take time.

| Limit | Detail |
| - | - |
| **Time** | A report call stops after **30 seconds**. If it has read at least one full page by then, it returns the totals so far, marked `truncated`, with a `next_cursor`. |
| **Rows** | A single call reads at most **3,000** transactions or customers. |
| **Date range** | Up to 366 days per report. |
| **Read budget** | A full report can use up to 30 of your 60 reads per minute. Wait a minute between large reports. |
| **List pages** | Lists return up to 100 rows per page. |

When a report is partial, the assistant calls it again from where it stopped (with `continue_after` set to `next_cursor`) and adds the new counts to the earlier ones. If you ask for a very large range, ask for it month by month. Partial totals are labelled, never presented as complete.

Totals follow the VEXiON dashboard rules. A reversed entry still counts as a transaction, and its reversal subtracts from the sums on the day the reversal was recorded.

Very large results are trimmed to a safe size. When that happens the result says so, and the assistant narrows the question.

## What the tools refuse

Some tools also refuse specific cases:

* `create_transaction` refuses gift card, membership and custom cards. It also refuses a bill above the largest bill of the currency (`amount_too_large`), a `value` above the limit (`value_too_large`), `amount_minor` on a redeem (`amount_not_valid_for_action`) and a `currency` that is not the business currency (`currency_mismatch`).
* `reverse_transaction` refuses cashback and other money transactions, and transactions that came from the till, scanner or online shop. Only transactions recorded through the API can be reversed.
* `send_card_to_customer` is email only. Texting is not available.
* `update_customer` cannot change email addresses.

See also [what the assistant can never do](https://vexioncards.mintlify.site/ai/mcp-permissions.md#what-the-assistant-can-never-do) and [Rate limits](https://vexioncards.mintlify.site/api-reference/rate-limits.md#mcp-server).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.