Formato della risposta

Ogni chiamata a uno strumento andata a buon fine restituisce un envelope, consegnato due volte nel risultato MCP: come structuredContent, e come testo JSON del primo blocco di content. Leggi quello che il tuo client espone; sono identici. Ogni strumento pubblica un outputSchema corrispondente, così un client conforme alla specifica valida structuredContent contro di esso.

{
  "data": {
    "results": [
      { "id": 42, "name": "Soho", "timezone": "Europe/London", "currency": "GBP" }
    ]
  },
  "meta": {
    "schemaVersion": 2,
    "timezone": "Europe/London",
    "dateRange": {
      "from": "2026-09-11T23:00:00.000Z",
      "to": "2026-09-18T22:59:59.999Z",
      "basis": "fulfillment",
      "endInclusive": true
    },
    "pagination": {
      "page": 1,
      "limit": 50,
      "returned": 50,
      "total": 1240,
      "totalIsEstimate": true,
      "hasMore": true,
      "nextPage": 2,
      "truncated": true
    },
    "warnings": [],
    "currencyCodes": ["GBP"]
  }
}

`data`

Gli strumenti list restituiscono data.results, un array.
Gli strumenti detail (get-venue, get-order, get-menu, get-payment-link, get-order-stats, le due scritture) restituiscono il record stesso in data.
get-snooze-report restituisce insieme un riepilogo, una time series e un array items paginato.
I campi sono in allowlist per risorsa. Qualsiasi cosa non presente nell’outputSchema di uno strumento non viene mai inviata, indipendentemente da ciò che contiene il record sottostante.

`meta`

Campo	Tipo	Significato
`schemaVersion`	`2`	Incrementato ad ogni breaking change all’envelope o alla forma di una risorsa
`timezone`	Nome IANA o `null`	Il fuso orario in cui è stato interpretato l’intervallo di date
`dateRange`	object o `null`	L’intervallo risolto e inclusivo effettivamente applicato, come istanti UTC, più il suo `basis`
`pagination`	object o `null`	Presente sui risultati paginati
`warnings`	`string[]`	Avvertenze leggibili, ad esempio che le statistiche sono al lordo dei rimborsi
`currencyCodes`	`string[]`, opzionale	Codici ISO 4217 distinti presenti nel risultato

meta è strict: non compaiono chiavi non documentate, e nuove chiavi arrivano con un bump di versione.

Paginazione

Le pagine partono da 1. limit è limitato a 100 (25 per list-top-products) e ridotto silenziosamente se ne chiedi di più. hasMore e nextPage derivano dal fetch di una riga oltre la pagina, quindi sono sempre esatti. total è null quando lo strumento non conta, e può essere contrassegnato totalIsEstimate: true su grandi liste di ordini dove un conteggio esatto è troppo lento. Guida i loop da hasMore, non da total:

let page = 1;
do {
  const { data, meta } = await call("list-orders", { venueId, from, to, page, limit: 100 });
  process(data.results);
  page = meta.pagination.nextPage;
} while (page !== null);

Le liste sono live; un record creato tra due pagine può spostare le pagine successive.

Date e fusi orari

Gli input (from, to) accettano:

YYYY-MM-DD: una data di calendario locale nel fuso orario effettivo, inclusiva a entrambe le estremità (to: "2026-09-18" arriva fino a 23:59:59.999 di quel giorno); oppure
un datetime ISO con Z o un offset numerico e al massimo tre cifre frazionarie, ad esempio 2026-09-18T14:00:00+01:00. I datetime senza offset vengono rifiutati.

Il fuso orario effettivo è timezone se fornito, altrimenti il fuso orario del locale quando è dato venueId, altrimenti UTC. meta.timezone indica sempre quale è stato usato. Gli intervalli possono coprire al massimo 90 date di calendario locali; gli intervalli più lunghi vengono rifiutati con INVALID_INPUT. Ogni strumento ha un intervallo di default (7 o 30 date) e un basis (creation, fulfillment, refund o snooze_overlap) che indica quale timestamp filtra l’intervallo; consulta Strumenti. meta.dateRange ripete l’intervallo risolto in modo che un client possa mostrare esattamente ciò che è stato conteggiato. Gli input di scrittura (startDate, endDate, expiresAt) devono essere timestamp ISO completi con offset. I valori solo data non sono accettati per le scritture.

Valuta

Tutti gli importi sono interi in unità minori della valuta (pence, cent) e non vengono mai convertiti. La valuta viaggia con i dati: come campo currency su locali, ordini, conti e link, e come meta.currencyCodes per il risultato nel suo complesso. codeAmount su uno sconto percentuale è in decimi di percentuale, non in un importo di valuta. Le statistiche a livello di account e le query sui top-product su un account i cui locali usano più di una valuta vengono rifiutate (INVALID_INPUT); passa venueId.

Immagini

get-payment-link-qr è l’unico strumento che restituisce dati binari. Il suo array content contiene il blocco di testo JSON seguito da un blocco immagine MCP nativo:

{
  "type": "image",
  "mimeType": "image/png",
  "data": "<base64 PNG>"
}

structuredContent porta solo l’URL di checkout e i metadata del link; non c’è alcun campo base64 dentro data.

Errori

Una chiamata fallita non è un envelope. È un risultato isError: true il cui singolo blocco di testo è un oggetto { error }, senza structuredContent. Consulta Errori.

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

Formato della risposta

`data`

`meta`

Paginazione

Date e fusi orari

Valuta

Immagini

Errori

​data

​meta

​Paginazione

​Date e fusi orari

​Valuta

​Immagini

​Errori

`data`

`meta`

Paginazione

Date e fusi orari

Valuta

Immagini

Errori