Tools - docs

All tools are scoped to the authenticated account; venueId narrows to one venue on that account and is rejected (NOT_FOUND) for any other. Every tool returns the { data, meta } envelope; every failure is an isError result.

Shared Inputs

These parameters recur across tools and behave identically everywhere.

Parameter	Type	Notes
`page`	integer ≥ 1	Default `1`
`limit`	integer 1–100	Per-tool defaults below; `list-top-products` and `search-customers` cap at 25
`from`, `to`	string	`YYYY-MM-DD` or ISO datetime with `Z`/numeric offset (≤ 3 fractional digits). Date-only values are local calendar dates in the effective timezone, inclusive. Range ≤ 90 local dates
`timezone`	IANA name	Overrides the effective timezone. Default: the venue’s timezone when `venueId` is given, otherwise `UTC`. Exception: `get-customer` defaults to `Europe/London`
`dateBasis`	enum	Which timestamp the date range filters — see each tool

Every enum below is a fixed list validated by the server; any other value is rejected with INVALID_INPUT. Fulfillment method values, where accepted, are exactly: InStore, Delivery, Pickup, Curbside, Billpay, CateringDelivery, CateringPickup.

Venues

`list-venues`

Read. Start here: it is how an agent discovers venue IDs.

Input	Notes
`archived`	`true` shows only archived venues; default active only
`page`, `limit`	Default limit 100

Returns data.results[] of venue summaries: id, name, slug, timezone, currency, address and fulfillment capabilities.

`get-venue`

Read.

Input	Notes
`venueId`	Required

Returns the venue with address, opening hours per fulfillment method, prep times, delivery fees and service charges.

`snooze-venue`

Write. readOnlyHint: false, idempotentHint: false. Closes the whole store to new orders until the specified time; pre-orders may continue if that setting is enabled.

Input	Notes
`venueId`	Required positive integer
`until`	Required future ISO datetime with `Z` or a numeric offset and at most three fractional-second digits
`reason`	Required, 1–255 characters. One of `CLOSING_EARLY`, `BETWEEN_SERVICE`, `KITCHEN_TOO_BUSY`, `BAR_TOO_BUSY`, `TECH_ISSUE` (optionally followed by details), or free text

Returns the venue ID, name, snooze end time, reason and enabled status.

`unsnooze-venue`

Write. readOnlyHint: false, idempotentHint: true. Reopens a whole store early; if it is not snoozed, no change is made.

Input	Notes
`venueId`	Required positive integer

Returns the venue ID, whether it was snoozed and, when reopened, the reopening time.

`list-tables`

Read. Lists dine-in tables at one venue; non-archived tables are included by default, including inactive ones.

Input	Notes
`venueId`	Required positive integer
`archived`	Default `false`; `true` shows archived tables only
`page`, `limit`	Default limit 100

Returns data.results[] with each table’s id, name, nullable area, active and archived fields.

Orders

`list-orders`

Read. Rejected and cancelled orders are excluded unless selected with status. pagination.total may be an estimate; page on hasMore.

Input	Notes
`venueId`	Optional
`status`	Exact stored status: `New`, `Received`, `Pending`, `Accepted`, `Preparing`, `Ready For Pickup`, `Out for Delivery`, `Delivered`, `Complete`, `Rejected`, `Cancelled`, `Failed`, `Retrying`, `Syncing`
`fulfillmentMethod`	See shared values
`from`, `to`, `timezone`	Default last 7 local dates
`dateBasis`	`fulfillment` (default: scheduled time, falling back to creation) or `creation`
`table`	Table name or number, up to 100 characters; requires `venueId` and cannot be combined with `tableId`
`tableId`	Table UUID from `list-tables`; requires `venueId` and cannot be combined with `table`
`page`, `limit`	Default limit 50

Each order row includes table as id, name and nullable area, or null when no table is associated.

`get-order`

Read.

Input	Notes
`orderId`	Short alphanumeric order ID

Returns line items with modifiers, price breakdown (subtotal, delivery fee, service charge, tip, discount), customer, table/area, delivery address and refund history.

`get-order-events`

Read. The order’s lifecycle audit trail: status changes, POS dispatch results, delivery updates.

Input	Notes
`orderId`	Required
`page`, `limit`	Default limit 100

Menus

`list-menus`

Read.

Input	Notes
`venueId`	Optional
`showArchived`	Default `false`
`page`, `limit`	Default limit 100

Returns menus with venue assignment and active/archived status. Read.

Input	Notes
`menuId`	Menu ID (string)

Returns categories with display order, and products with prices, availability, inventory tracking and tags. Not paginated.

Snoozing

`get-snooze-report`

Read. Snoozes that overlap the interval. The summary and time series cover the whole interval; items are paginated.

Input	Notes
`venueId`	Optional
`from`, `to`, `timezone`	Default last 7 local dates
`source`	`manual`, `mcp`, `pos`, `deliverect`, `lightspeed`, `zonal`, `tissl`, `toast`, `syrve`
`includeEvents`	Per-item on/off events; default `false`
`eventLimit`	1–100, default 100. Items exceeding it are flagged `eventsTruncated`
`page`, `limit`	Default limit 50

`list-snoozed-items`

Read. Lists menu items that are currently snoozed, ordered by when the snooze ends.

Input	Notes
`venueId`	Optional
`page`, `limit`	Default limit 100

Returns data.results[] with each item’s menu item ID and name, PLU, venue ID, snooze start and end. Write. readOnlyHint: false, idempotentHint: false. Hides one or more menu items from ordering until the specified time, replacing any existing snooze on those items.

Input	Notes
`venueId`	Required positive integer
`menuItemIds`	1–50 menu item IDs from `get-menu`
`until`	Required future ISO datetime with `Z` or a numeric offset and at most three fractional-second digits; the snooze starts immediately

Returns the venue ID and the snoozed items with their IDs, names, venue IDs and start/end times. Write. readOnlyHint: false, idempotentHint: true. Clears snoozes so menu items can be ordered again.

Input	Notes
`menuItemIds`	1–50 menu item IDs

Returns each item ID and name, and whether it was snoozed.

Stats

`get-order-stats`

Read. Order count, sum of order totals and average order value by order creation time, alongside the preceding period of equal length. Totals exclude rejected/cancelled orders and are not net of refunds (a meta.warnings entry says so). On an account whose venues use more than one currency, venueId is required (INVALID_INPUT).

Input	Notes
`venueId`	Optional, see above
`period`	1–90 local dates including today; default 30. Not with `from`/`to`
`from`, `to`, `timezone`	Alternative to `period`
`table`	Table name or number, up to 100 characters; requires `venueId` and cannot be combined with `tableId`
`tableId`	Table UUID from `list-tables`; requires `venueId` and cannot be combined with `table`

`list-top-products`

Read. Products ranked by quantity sold, by order creation time. Prices are current catalogue prices, not historical selling prices. Multi-currency accounts must pass venueId.

Input	Notes
`venueId`	Optional, see above
`from`, `to`, `timezone`	Default last 30 local dates
`page`, `limit`	Default limit 10, max 25

Discounts

`list-discount-codes`

Read.

Input	Notes
`venueId`	Codes assigned to this venue
`showArchived`	Default `false`
`page`, `limit`	Default limit 100

Returns code, type, amount, usage stats and validity dates.

`create-discount-code`

Write. readOnlyHint: false, idempotentHint: false. The code must be unique per venue (CONFLICT otherwise) and is stored lowercased.

Input	Notes
`code`	Required
`type`	`fixed`, `percent`, `buyonegetonefree`, `freedelivery`
`codeAmount`	Minor units for `fixed`; tenths of a percent for `percent` (`100` = 10%); `0` for the other two
`venues[]`	Required, ≥ 1: `{ id, enabled? }` (`enabled` default `true`)
`description`	Optional
`usageLimit`	Total uses; `0` = unlimited (default)
`usageLimitPerUser`	Per customer email; `0` = unlimited (default)
`minimumAmount`	Minimum subtotal, minor units; default `0`
`maxDiscountAmount`	Cap on the discount, minor units; `0` = no cap
`startDate`, `endDate`	ISO timestamps with offset; omit for immediate / no expiry. `endDate` must follow `startDate`
`fulfillmentMethods[]`	Restrict to methods; omit for all
`autoApply`	Apply automatically at checkout; default `false`

Returns the created discount code in data.

Refunds

`list-refunds`

Read. Successful refunds only.

Input	Notes
`venueId`	Required
`from`, `to`, `timezone`	Default last 7 local dates
`dateBasis`	`refund` (default: when the refund was made) or `creation` (when the original order was placed)
`page`, `limit`	Default limit 50

Pay at Table

`list-bills`

Read. Bills by creation time.

Input	Notes
`venueId`	Required
`status`	`open`, `closed`
`from`, `to`, `timezone`	Default last 7 local dates
`table`	Table name or number, up to 100 characters; requires `venueId` and cannot be combined with `tableId`
`tableId`	Table UUID from `list-tables`; requires `venueId` and cannot be combined with `table`
`page`, `limit`	Default limit 50

Returns status, currency, total, amount due, covers and table name.

Feedback & Reviews

`list-feedback`

Read. Lists completed storekit feedback (ratings and comments left after an online order or pay-at-table bill), newest first. Defaults to the last 30 local dates and feedback with written overall or item-level detail.

Input	Notes
`venueId`	Optional
`from`, `to`, `timezone`	Default last 30 local dates
`minRating`, `maxRating`	Optional ratings from 1 (lowest) to 5 (highest)
`hasComment`	Default `true`; matches a non-empty overall comment or item comment/reason. `false` applies no comment filter
`source`	`order` or `table_bill`
`item`	Case-insensitive substring of the item name
`reason`	Item reason text; known values are `taste_seasoning`, `temperature`, `value_for_money`, `something_else`, `portion_size`, `missing_incorrect`, `presentation`, `dietary_allergens`
`sentiment`	`positive`, `negative`, `neutral`
`orderId`	Filter by online order ID
`email`	Exact customer email match, case-insensitive
`sort`	`newest` (default) or `lowest`
`page`, `limit`	Default limit 25

Returns feedback rows with ID, venue, rating, comment, creation time, source, order or bill ID, customer email and item feedback (name, rating, sentiment, reasons, comment, quantity and modifiers).

`list-reviews`

Read. Lists public Google reviews, newest first, with our reply when one was sent.

Input	Notes
`venueId`	Optional
`from`, `to`, `timezone`	Default last 30 local dates
`minRating`, `maxRating`	Optional ratings from 1 (lowest) to 5 (highest)
`replyStatus`	`needs_reply`, `replied` or `all` (default)
`hasComment`	Optional; `true` means a non-empty comment, `false` means no comment
`sort`	`newest` (default) or `lowest`
`page`, `limit`	Default limit 25

Returns review rows with reviewer name, rating, comment, creation time and reply (comment, at, source) or null.

`get-feedback-summary`

Read. Summarises storekit feedback and Google reviews for a period against the preceding period of the same length. Defaults to the last 30 local dates; not paginated.

Input	Notes
`venueId`	Optional; when supplied, `venues` is `null`
`from`, `to`, `timezone`	Default last 30 local dates

Returns storekit review counts, averages, 1–5 rating breakdown, low-rating share and completion rate; google review counts, averages, low-rating and unreplied counts, storekit-attributed reviews, current rating/total and changes (or null when there is no Google data); items with most complained/praised items and top reasons plus reason totals; venues worst first for account-wide calls (up to 25, with a meta.warnings entry if capped); and up to three low- and high-rated recent feedback quotes, including customer email. Items are grouped by name across venues. Google ratings are daily snapshots: a past period uses the last full UTC day that ended before the period ended, while a period that includes today uses today’s live rating.

Customers

`search-customers`

Read. Searches account customers by email, first or last name, or phone. Order totals cover the last 24 months.

Input	Notes
`query`	Required, 2–100 characters
`venueId`	Optional
`page`, `limit`	Default page 1 and limit 10; limit maximum 25

Returns matching customers’ email, name, phone, order count, 24-month order value in minor currency units, last order date and marketing opt-in status.

`get-customer`

Read. Returns a customer profile with contact, order, app, loyalty, recent-order and insight data.

Input	Notes
`email`	Required valid customer email address
`venueId`	Optional
`timezone`	IANA timezone for customer insights; default `Europe/London`

Returns customer contact and order totals, app and loyalty data, up to 10 recent orders, and customer insights when available.

Payment Links

`list-payment-links`

Read.

Input	Notes
`venueId`	Optional
`status`	`active`, `inactive`, `expired`, `completed`
`type`	`one_off`, `reusable`
`page`, `limit`	Default limit 20

Returns link details with payment stats.

`get-payment-link`

Read.

Input	Notes
`id`	External ID, `plink_…`

`create-payment-link`

Write. readOnlyHint: false, idempotentHint: false. The link is active as soon as it is created.

Input	Notes
`venueId`	Required
`type`	`one_off` (deactivates after one payment) or `reusable`
`amountType`	`fixed` or `variable`
`amount`	Minor units, 1–1,000,000. Required for `fixed`, forbidden for `variable`
`title`	Required, ≤ 255 chars
`description`, `reference`	Optional; `reference` ≤ 255 chars
`expiresAt`	ISO timestamp with offset; omit for no expiry
`minAmount`, `maxAmount`	Bounds for `variable`, minor units, ≤ 1,000,000
`maxPayments`	`reusable` only; deactivates after this many payments
`imageUrl`	URL shown on checkout
`successMode`	`thank_you` (default) or `redirect`
`successMessage`	`thank_you` mode only
`successRedirectUrl`	Required when `successMode` is `redirect`
`collectBusinessName`, `collectCustomerName`, `collectEmail`, `collectPhone`	Booleans, default `false`

Returns the created link in data. Fires the payment_link.created webhook.

`get-payment-link-qr`

Read. The only tool that returns an image.

Input	Notes
`id`	External ID, `plink_…`
`size`	Pixels, 100–2000; default 500

The result carries the checkout metadata in structuredContent (and the JSON text block) plus a native MCP image/png content block. There is no base64 field inside data.

​Shared Inputs

​Venues

​list-venues

​get-venue

​snooze-venue

​unsnooze-venue

​list-tables

​Orders

​list-orders

​get-order

​get-order-events

​Menus

​list-menus

​get-menu

​Snoozing

​get-snooze-report

​list-snoozed-items

​snooze-menu-items

​unsnooze-menu-items

​Stats

​get-order-stats

​list-top-products

​Discounts

​list-discount-codes

​create-discount-code

​Refunds

​list-refunds

​Pay at Table

​list-bills

​Feedback & Reviews

​list-feedback

​list-reviews

​get-feedback-summary

​Customers

​search-customers

​get-customer

​Payment Links

​list-payment-links

​get-payment-link

​create-payment-link

​get-payment-link-qr

Shared Inputs

Venues

`list-venues`

`get-venue`

`snooze-venue`

`unsnooze-venue`

`list-tables`

Orders

`list-orders`

`get-order`

`get-order-events`

Menus

`list-menus`

`get-menu`

Snoozing

`get-snooze-report`

`list-snoozed-items`

`snooze-menu-items`

`unsnooze-menu-items`

Stats

`get-order-stats`

`list-top-products`

Discounts

`list-discount-codes`

`create-discount-code`

Refunds

`list-refunds`

Pay at Table

`list-bills`

Feedback & Reviews

`list-feedback`

`list-reviews`

`get-feedback-summary`

Customers

`search-customers`

`get-customer`

Payment Links

`list-payment-links`

`get-payment-link`

`create-payment-link`

`get-payment-link-qr`