Skip to main content
Every successful tool call returns one envelope, delivered twice in the MCP result: as structuredContent, and as the JSON text of the first content block. Read whichever your client exposes; they are identical. Every tool publishes a matching outputSchema, so a spec-compliant client validates structuredContent against it.

data

  • List tools return data.results, an array.
  • Detail tools (get-venue, get-order, get-menu, get-payment-link, get-order-stats, get-customer, the writes) return the record itself in data.
  • get-snooze-report returns a summary, a time series and a paginated items array together.
  • Fields are allowlisted per resource: tools return serialized fields, not the underlying record.
  • Most records include a dashboardUrl that opens the same record in the storekit dashboard.

meta

meta is strict: no undocumented keys appear, and new keys arrive with a version bump.

Pagination

Pages start at 1. limit is capped at 100 (25 for list-top-products and search-customers); a larger value fails the tool’s input schema and the call is refused. hasMore and nextPage come from fetching one row beyond the page on most tools, so they are exact; list-transactions and search-customers work them out from the total count. total is null when the tool does not count, and may be flagged totalIsEstimate: true on large order lists where an exact count is too slow. Drive loops from hasMore, not from total:
Lists are live; a record created between pages can shift subsequent pages.

Dates and Timezones

Inputs (from, to) accept:
  • YYYY-MM-DD — a local calendar date in the effective timezone, inclusive at both ends (to: "2026-09-18" runs to 23:59:59.999 that day);
  • an ISO datetime with Z or a numeric offset and at most three fractional digits, e.g. 2026-09-18T14:00:00+01:00. Offset-less datetimes are rejected; or
  • a relative date: today, yesterday, or -N followed by d, w, m or y (N from 0 to 999), optionally with Start or End to snap to the start or end of that day, ISO week, month or year. For example -1mStart to -1mEnd is last month.
get-end-of-day-report, get-app-audience and list-transactions cover whole days, so they accept dates and relative dates but not datetimes. The effective timezone is timezone if supplied, otherwise the venue’s timezone when venueId is given, otherwise UTC. meta.timezone always states which was used. The longest range is set per tool: no maximum on the paginated lists (list-orders, list-bills, list-refunds, list-feedback, list-reviews), 366 local calendar dates for get-order-stats and run-report, 92 for list-transactions and 90 for the rest. Longer ranges are rejected with INVALID_INPUT. Each tool has a default range (7 or 30 dates) and a basis — creation, fulfillment, refund or snooze_overlap — that says which timestamp the range filters; see Tools. meta.dateRange echoes the resolved range so a client can display exactly what was counted. Write inputs (startDate, endDate, expiresAt, until) must be full ISO timestamps with an offset. Date-only values are not accepted for writes.

Money

All amounts are integers in minor currency units (pence, cents) and are never converted. The currency travels with the data — as currencyCode on venues, orders, bills, refunds and stats, as currency on payment links, and as meta.currencyCodes for the result as a whole. codeAmount on a percentage discount is in tenths of a percent, not a currency amount. Account-wide get-order-stats, list-top-products and get-end-of-day-report queries on an account whose venues use more than one currency are refused (INVALID_INPUT); pass venueId.

Images

get-payment-link-qr is the only tool that returns binary data. Its content array holds the JSON text block followed by a native MCP image block:
structuredContent carries the checkout URL and link metadata only; there is no base64 field inside data.

Errors

A failed call is not an envelope. It is an isError: true result with no structuredContent, whose single text block is an { error } object, or plain text when the arguments fail the tool’s input schema. See Errors.