> ## Documentation Index > Fetch the complete documentation index at: https://storekit.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Tools > Reference for the 18 merchant MCP tools: sixteen reads and two writes, with inputs, defaults, date basis and what each returns, scoped to the account. 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](/docs/developers/mcp/response-format); every failure is an [`isError` result](/docs/developers/mcp/errors). ## 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. ### `get-menu` 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](/docs/developers/webhooks/webhook-events). ### `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`. ## Related topics - [WebMCP Tools](/docs/developers/agents/ordering/webmcp.md) - [Merchant MCP Overview](/docs/developers/mcp/overview.md) - [Payment Links Reference](/docs/payment-links/reference.md) - [MCP Endpoint](/docs/developers/agents/ordering/mcp-endpoint.md) - [Errors](/docs/developers/mcp/errors.md)