Tools

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

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`
`page`, `limit`	Default limit 50

`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`, `deliverect`, `lightspeed`, `zonal`
`includeEvents`	Per-item on/off events; default `false`
`eventLimit`	1–100, default 100. Items exceeding it are flagged `eventsTruncated`
`page`, `limit`	Default limit 50

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`

`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
`page`, `limit`	Default limit 50

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

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.

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

Shared Inputs

Venues

`list-venues`

`get-venue`

Orders

`list-orders`

`get-order`

`get-order-events`

Menus

`list-menus`

`get-menu`

Snoozing

`get-snooze-report`

Stats

`get-order-stats`

`list-top-products`

Discounts

`list-discount-codes`

`create-discount-code`

Refunds

`list-refunds`

Pay at Table

`list-bills`

Payment Links

`list-payment-links`

`get-payment-link`

`create-payment-link`

`get-payment-link-qr`

​Shared Inputs

​Venues

​list-venues

​get-venue

​Orders

​list-orders

​get-order

​get-order-events

​Menus

​list-menus

​get-menu

​Snoozing

​get-snooze-report

​Stats

​get-order-stats

​list-top-products

​Discounts

​list-discount-codes

​create-discount-code

​Refunds

​list-refunds

​Pay at Table

​list-bills

​Payment Links

​list-payment-links

​get-payment-link

​create-payment-link

​get-payment-link-qr

Shared Inputs

Venues

`list-venues`

`get-venue`

Orders

`list-orders`

`get-order`

`get-order-events`

Menus

`list-menus`

`get-menu`

Snoozing

`get-snooze-report`

Stats

`get-order-stats`

`list-top-products`

Discounts

`list-discount-codes`

`create-discount-code`

Refunds

`list-refunds`

Pay at Table

`list-bills`

Payment Links

`list-payment-links`

`get-payment-link`

`create-payment-link`

`get-payment-link-qr`