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

# Strumenti

> Riferimento dei 18 strumenti merchant MCP: sedici letture e due scritture con input, default e base delle date, limitate all'account autenticato.

Tutti gli strumenti sono limitati all'account autenticato; `venueId` restringe a un locale su quell'account e viene rifiutato (`NOT_FOUND`) per qualsiasi altro. Ogni strumento restituisce l'[envelope `{ data, meta }`](/docs/it/developers/mcp/response-format); ogni fallimento è un [risultato `isError`](/docs/it/developers/mcp/errors).

## Input condivisi

Questi parametri ricorrono tra gli strumenti e si comportano allo stesso modo ovunque.

| Parametro | Tipo | Note |
| - | - | - |
| `page` | integer ≥ 1 | Default `1` |
| `limit` | integer 1-100 | Default per strumento sotto; `list-top-products` limita a 25 |
| `from`, `to` | string | `YYYY-MM-DD` o datetime ISO con `Z`/offset numerico (≤ 3 cifre frazionarie). I valori solo data sono date di calendario locali nel fuso orario effettivo, inclusive. Intervallo ≤ 90 date locali |
| `timezone` | Nome IANA | Sostituisce il fuso orario effettivo. Default: il fuso orario del locale quando è dato `venueId`, altrimenti `UTC` |
| `dateBasis` | enum | Quale timestamp filtra l'intervallo di date, consulta ogni strumento |

Ogni enum sotto è una lista fissa validata dal server; qualsiasi altro valore viene rifiutato con `INVALID_INPUT`. I valori dei metodi di fulfillment, dove accettati, sono esattamente: `InStore`, `Delivery`, `Pickup`, `Curbside`, `Billpay`, `CateringDelivery`, `CateringPickup`.

## Locali

### `list-venues`

Lettura. Parti da qui: è come un agente scopre gli ID dei locali.

| Input | Note |
| - | - |
| `archived` | `true` mostra solo i locali archiviati; default solo attivi |
| `page`, `limit` | Limit di default 100 |

Restituisce `data.results[]` di riepiloghi dei locali: `id`, `name`, `slug`, `timezone`, `currency`, indirizzo e capability di fulfillment.

### `get-venue`

Lettura.

| Input | Note |
| - | - |
| `venueId` | Obbligatorio |

Restituisce il locale con indirizzo, orari di apertura per metodo di fulfillment, tempi di preparazione, commissioni di consegna e service charge.

## Ordini

### `list-orders`

Lettura. Gli ordini rifiutati e cancellati sono esclusi salvo che vengano selezionati con `status`. `pagination.total` può essere una stima; pagina con `hasMore`.

| Input | Note |
| - | - |
| `venueId` | Opzionale |
| `status` | Stato esatto memorizzato: `New`, `Received`, `Pending`, `Accepted`, `Preparing`, `Ready For Pickup`, `Out for Delivery`, `Delivered`, `Complete`, `Rejected`, `Cancelled`, `Failed`, `Retrying`, `Syncing` |
| `fulfillmentMethod` | Vedi valori condivisi |
| `from`, `to`, `timezone` | Default ultime 7 date locali |
| `dateBasis` | `fulfillment` (default: tempo programmato, ripiegando sulla creazione) o `creation` |
| `page`, `limit` | Limit di default 50 |

### `get-order`

Lettura.

| Input | Note |
| - | - |
| `orderId` | ID ordine alfanumerico corto |

Restituisce le voci con modificatori, il dettaglio dei prezzi (subtotale, commissione di consegna, service charge, mancia, sconto), cliente, tavolo/area, indirizzo di consegna e cronologia dei rimborsi.

### `get-order-events`

Lettura. L'audit trail del ciclo di vita dell'ordine: cambi di stato, esiti del dispatch al POS, aggiornamenti di consegna.

| Input | Note |
| - | - |
| `orderId` | Obbligatorio |
| `page`, `limit` | Limit di default 100 |

## Menu

### `list-menus`

Lettura.

| Input | Note |
| - | - |
| `venueId` | Opzionale |
| `showArchived` | Default `false` |
| `page`, `limit` | Limit di default 100 |

Restituisce i menu con l'assegnazione al locale e lo stato attivo/archiviato.

### `get-menu`

Lettura.

| Input | Note |
| - | - |
| `menuId` | ID menu (string) |

Restituisce categorie con ordine di visualizzazione, e prodotti con prezzi, disponibilità, tracciamento dell'inventario e tag. Non paginato.

## Snooze

### `get-snooze-report`

Lettura. Gli snooze che si sovrappongono all'intervallo. Il riepilogo e la time series coprono l'intero intervallo; gli item sono paginati.

| Input | Note |
| - | - |
| `venueId` | Opzionale |
| `from`, `to`, `timezone` | Default ultime 7 date locali |
| `source` | `manual`, `deliverect`, `lightspeed`, `zonal` |
| `includeEvents` | Eventi on/off per item; default `false` |
| `eventLimit` | 1-100, default 100. Gli item che lo superano sono contrassegnati `eventsTruncated` |
| `page`, `limit` | Limit di default 50 |

## Statistiche

### `get-order-stats`

Lettura. Conteggio degli ordini, somma dei totali degli ordini e valore medio dell'ordine **per momento di creazione dell'ordine**, insieme al periodo precedente di uguale lunghezza. I totali escludono gli ordini rifiutati/cancellati e non sono al netto dei rimborsi (un'entry `meta.warnings` lo dice). Su un account i cui locali usano più di una valuta, `venueId` è obbligatorio (`INVALID_INPUT`).

| Input | Note |
| - | - |
| `venueId` | Opzionale, vedi sopra |
| `period` | 1-90 date locali oggi incluso; default 30. Non con `from`/`to` |
| `from`, `to`, `timezone` | Alternativa a `period` |

### `list-top-products`

Lettura. Prodotti classificati per quantità venduta, per momento di creazione dell'ordine. I prezzi sono i prezzi **correnti** del catalogo, non i prezzi storici di vendita. Gli account multi-valuta devono passare `venueId`.

| Input | Note |
| - | - |
| `venueId` | Opzionale, vedi sopra |
| `from`, `to`, `timezone` | Default ultime 30 date locali |
| `page`, `limit` | Limit di default 10, max 25 |

## Sconti

### `list-discount-codes`

Lettura.

| Input | Note |
| - | - |
| `venueId` | Codici assegnati a questo locale |
| `showArchived` | Default `false` |
| `page`, `limit` | Limit di default 100 |

Restituisce codice, tipo, importo, statistiche di utilizzo e date di validità.

### `create-discount-code`

**Scrittura.** `readOnlyHint: false`, `idempotentHint: false`. Il codice deve essere univoco per locale (`CONFLICT` altrimenti) ed è memorizzato in minuscolo.

| Input | Note |
| - | - |
| `code` | Obbligatorio |
| `type` | `fixed`, `percent`, `buyonegetonefree`, `freedelivery` |
| `codeAmount` | Unità minori per `fixed`; **decimi di percentuale** per `percent` (`100` = 10%); `0` per gli altri due |
| `venues[]` | Obbligatorio, ≥ 1: `{ id, enabled? }` (`enabled` default `true`) |
| `description` | Opzionale |
| `usageLimit` | Utilizzi totali; `0` = illimitato (default) |
| `usageLimitPerUser` | Per email cliente; `0` = illimitato (default) |
| `minimumAmount` | Subtotale minimo, unità minori; default `0` |
| `maxDiscountAmount` | Limite sullo sconto, unità minori; `0` = nessun limite |
| `startDate`, `endDate` | Timestamp ISO **con offset**; ometti per immediato / nessuna scadenza. `endDate` deve seguire `startDate` |
| `fulfillmentMethods[]` | Limita ai metodi; ometti per tutti |
| `autoApply` | Applica automaticamente al checkout; default `false` |

Restituisce il codice sconto creato in `data`.

## Rimborsi

### `list-refunds`

Lettura. Solo rimborsi andati a buon fine.

| Input | Note |
| - | - |
| `venueId` | **Obbligatorio** |
| `from`, `to`, `timezone` | Default ultime 7 date locali |
| `dateBasis` | `refund` (default: quando è stato effettuato il rimborso) o `creation` (quando è stato effettuato l'ordine originale) |
| `page`, `limit` | Limit di default 50 |

## Pay at Table

### `list-bills`

Lettura. Conti per momento di creazione.

| Input | Note |
| - | - |
| `venueId` | **Obbligatorio** |
| `status` | `open`, `closed` |
| `from`, `to`, `timezone` | Default ultime 7 date locali |
| `page`, `limit` | Limit di default 50 |

Restituisce stato, valuta, totale, importo dovuto, coperti e nome del tavolo.

## Payment link

### `list-payment-links`

Lettura.

| Input | Note |
| - | - |
| `venueId` | Opzionale |
| `status` | `active`, `inactive`, `expired`, `completed` |
| `type` | `one_off`, `reusable` |
| `page`, `limit` | Limit di default 20 |

Restituisce i dettagli del link con le statistiche di pagamento.

### `get-payment-link`

Lettura.

| Input | Note |
| - | - |
| `id` | ID esterno, `plink_…` |

### `create-payment-link`

**Scrittura.** `readOnlyHint: false`, `idempotentHint: false`. Il link è attivo non appena viene creato.

| Input | Note |
| - | - |
| `venueId` | Obbligatorio |
| `type` | `one_off` (si disattiva dopo un pagamento) o `reusable` |
| `amountType` | `fixed` o `variable` |
| `amount` | Unità minori, 1-1.000.000. Obbligatorio per `fixed`, vietato per `variable` |
| `title` | Obbligatorio, ≤ 255 caratteri |
| `description`, `reference` | Opzionali; `reference` ≤ 255 caratteri |
| `expiresAt` | Timestamp ISO con offset; ometti per nessuna scadenza |
| `minAmount`, `maxAmount` | Limiti per `variable`, unità minori, ≤ 1.000.000 |
| `maxPayments` | Solo `reusable`; si disattiva dopo questo numero di pagamenti |
| `imageUrl` | URL mostrato al checkout |
| `successMode` | `thank_you` (default) o `redirect` |
| `successMessage` | Solo modalità `thank_you` |
| `successRedirectUrl` | Obbligatorio quando `successMode` è `redirect` |
| `collectBusinessName`, `collectCustomerName`, `collectEmail`, `collectPhone` | Booleani, default `false` |

Restituisce il link creato in `data`. Attiva il [webhook](/docs/it/developers/webhooks/webhook-events) `payment_link.created`.

### `get-payment-link-qr`

Lettura. L'unico strumento che restituisce un'immagine.

| Input | Note |
| - | - |
| `id` | ID esterno, `plink_…` |
| `size` | Pixel, 100-2000; default 500 |

Il risultato porta i metadata di checkout in `structuredContent` (e nel blocco di testo JSON) più un blocco di contenuto MCP nativo `image/png`. Non c'è alcun campo base64 dentro `data`.


## Related topics

- [Strumenti WebMCP](/docs/it/developers/agents/ordering/webmcp.md)
- [Costruisci i tuoi strumenti su storekit](/docs/it/guides/build/overview.md)
- [Panoramica del merchant MCP](/docs/it/developers/mcp/overview.md)
- [Riferimento dei payment link](/docs/it/payment-links/reference.md)
- [MCP Endpoint](/docs/it/developers/agents/ordering/mcp-endpoint.md)


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