Outils

Tous les outils sont restreints au compte authentifié ; venueId restreint à un seul établissement de ce compte et est rejeté (NOT_FOUND) pour tout autre. Chaque outil renvoie l’enveloppe { data, meta } ; chaque échec est un résultat isError.

Entrées partagées

Ces paramètres reviennent dans plusieurs outils et se comportent de la même façon partout.

Paramètre	Type	Notes
`page`	entier ≥ 1	Par défaut `1`
`limit`	entier 1–100	Valeurs par défaut par outil ci-dessous ; `list-top-products` plafonne à 25
`from`, `to`	string	`YYYY-MM-DD` ou datetime ISO avec `Z`/offset numérique (≤ 3 chiffres fractionnaires). Les valeurs date-only sont des dates calendaires locales dans le fuseau horaire effectif, inclusives. Plage ≤ 90 dates locales
`timezone`	Nom IANA	Remplace le fuseau horaire effectif. Par défaut : le fuseau horaire de l’établissement quand `venueId` est donné, sinon `UTC`
`dateBasis`	enum	Quel horodatage la plage de dates filtre : voir chaque outil

Chaque enum ci-dessous est une liste fixe validée par le serveur ; toute autre valeur est rejetée avec INVALID_INPUT. Les valeurs de mode de fulfillment, là où elles sont acceptées, sont exactement : InStore, Delivery, Pickup, Curbside, Billpay, CateringDelivery, CateringPickup.

Venues

`list-venues`

Lecture. Commence ici : c’est comme ça qu’un agent découvre les identifiants d’établissements.

Entrée	Notes
`archived`	`true` n’affiche que les établissements archivés ; par défaut, actifs uniquement
`page`, `limit`	Limite par défaut 100

Renvoie data.results[] de résumés d’établissements : id, name, slug, timezone, currency, adresse et capacités de fulfillment.

`get-venue`

Lecture.

Entrée	Notes
`venueId`	Requis

Renvoie l’établissement avec l’adresse, les horaires d’ouverture par mode de fulfillment, les temps de préparation, les frais de livraison et les frais de service.

Commandes

`list-orders`

Lecture. Les commandes rejetées et annulées sont exclues sauf si elles sont sélectionnées avec status. pagination.total peut être une estimation ; pagine sur hasMore.

Entrée	Notes
`venueId`	Optionnel
`status`	Statut stocké exact : `New`, `Received`, `Pending`, `Accepted`, `Preparing`, `Ready For Pickup`, `Out for Delivery`, `Delivered`, `Complete`, `Rejected`, `Cancelled`, `Failed`, `Retrying`, `Syncing`
`fulfillmentMethod`	Voir les valeurs partagées
`from`, `to`, `timezone`	Par défaut les 7 dernières dates locales
`dateBasis`	`fulfillment` (par défaut : heure programmée, à défaut création) ou `creation`
`page`, `limit`	Limite par défaut 50

`get-order`

Lecture.

Entrée	Notes
`orderId`	Identifiant de commande court alphanumérique

Renvoie les lignes de commande avec les modificateurs, la ventilation des prix (sous-total, frais de livraison, frais de service, pourboire, réduction), le client, la table/zone, l’adresse de livraison et l’historique des remboursements.

`get-order-events`

Lecture. La piste d’audit du cycle de vie de la commande : changements de statut, résultats de dispatch POS, mises à jour de livraison.

Entrée	Notes
`orderId`	Requis
`page`, `limit`	Limite par défaut 100

Menus

`list-menus`

Lecture.

Entrée	Notes
`venueId`	Optionnel
`showArchived`	Par défaut `false`
`page`, `limit`	Limite par défaut 100

Renvoie les menus avec l’affectation à l’établissement et le statut actif/archivé. Lecture.

Entrée	Notes
`menuId`	Identifiant de menu (string)

Renvoie les catégories avec l’ordre d’affichage, et les produits avec les prix, la disponibilité, le suivi d’inventaire et les tags. Non paginé.

Snooze

`get-snooze-report`

Lecture. Les snooze qui chevauchent l’intervalle. Le résumé et la série temporelle couvrent l’intervalle entier ; les articles sont paginés.

Entrée	Notes
`venueId`	Optionnel
`from`, `to`, `timezone`	Par défaut les 7 dernières dates locales
`source`	`manual`, `deliverect`, `lightspeed`, `zonal`
`includeEvents`	Événements on/off par article ; par défaut `false`
`eventLimit`	1–100, par défaut 100. Les articles qui dépassent sont signalés `eventsTruncated`
`page`, `limit`	Limite par défaut 50

Stats

`get-order-stats`

Lecture. Nombre de commandes, somme des totaux et valeur moyenne de commande par heure de création de commande, aux côtés de la période précédente de même durée. Les totaux excluent les commandes rejetées/annulées et ne sont pas nets de remboursements (une entrée meta.warnings le précise). Sur un compte dont les établissements utilisent plus d’une devise, venueId est requis (INVALID_INPUT).

Entrée	Notes
`venueId`	Optionnel, voir ci-dessus
`period`	1–90 dates locales aujourd’hui inclus ; par défaut 30. Pas avec `from`/`to`
`from`, `to`, `timezone`	Alternative à `period`

`list-top-products`

Lecture. Produits classés par quantité vendue, par heure de création de commande. Les prix sont les prix actuels du catalogue, pas les prix de vente historiques. Les comptes multi-devises doivent passer venueId.

Entrée	Notes
`venueId`	Optionnel, voir ci-dessus
`from`, `to`, `timezone`	Par défaut les 30 dernières dates locales
`page`, `limit`	Limite par défaut 10, max 25

Réductions

`list-discount-codes`

Lecture.

Entrée	Notes
`venueId`	Codes affectés à cet établissement
`showArchived`	Par défaut `false`
`page`, `limit`	Limite par défaut 100

Renvoie le code, le type, le montant, les statistiques d’utilisation et les dates de validité.

`create-discount-code`

Écriture. readOnlyHint: false, idempotentHint: false. Le code doit être unique par établissement (CONFLICT sinon) et est stocké en minuscules.

Entrée	Notes
`code`	Requis
`type`	`fixed`, `percent`, `buyonegetonefree`, `freedelivery`
`codeAmount`	Unités mineures pour `fixed` ; dixièmes de pour cent pour `percent` (`100` = 10 %) ; `0` pour les deux autres
`venues[]`	Requis, ≥ 1 : `{ id, enabled? }` (`enabled` par défaut `true`)
`description`	Optionnel
`usageLimit`	Utilisations totales ; `0` = illimité (par défaut)
`usageLimitPerUser`	Par email client ; `0` = illimité (par défaut)
`minimumAmount`	Sous-total minimum, unités mineures ; par défaut `0`
`maxDiscountAmount`	Plafond sur la réduction, unités mineures ; `0` = pas de plafond
`startDate`, `endDate`	Horodatages ISO avec offset ; omets pour immédiat / pas d’expiration. `endDate` doit suivre `startDate`
`fulfillmentMethods[]`	Restreint aux modes ; omets pour tous
`autoApply`	Applique automatiquement au checkout ; par défaut `false`

Renvoie le code de réduction créé dans data.

Remboursements

`list-refunds`

Lecture. Remboursements réussis uniquement.

Entrée	Notes
`venueId`	Requis
`from`, `to`, `timezone`	Par défaut les 7 dernières dates locales
`dateBasis`	`refund` (par défaut : quand le remboursement a été effectué) ou `creation` (quand la commande originale a été passée)
`page`, `limit`	Limite par défaut 50

Pay at table

`list-bills`

Lecture. Additions par heure de création.

Entrée	Notes
`venueId`	Requis
`status`	`open`, `closed`
`from`, `to`, `timezone`	Par défaut les 7 dernières dates locales
`page`, `limit`	Limite par défaut 50

Renvoie le statut, la devise, le total, le montant dû, les couverts et le nom de la table.

Liens de paiement

`list-payment-links`

Lecture.

Entrée	Notes
`venueId`	Optionnel
`status`	`active`, `inactive`, `expired`, `completed`
`type`	`one_off`, `reusable`
`page`, `limit`	Limite par défaut 20

Renvoie les détails du lien avec les stats de paiement.

`get-payment-link`

Lecture.

Entrée	Notes
`id`	ID externe, `plink_…`

`create-payment-link`

Écriture. readOnlyHint: false, idempotentHint: false. Le lien est actif dès sa création.

Entrée	Notes
`venueId`	Requis
`type`	`one_off` (se désactive après un paiement) ou `reusable`
`amountType`	`fixed` ou `variable`
`amount`	Unités mineures, 1–1 000 000. Requis pour `fixed`, interdit pour `variable`
`title`	Requis, ≤ 255 caractères
`description`, `reference`	Optionnels ; `reference` ≤ 255 caractères
`expiresAt`	Horodatage ISO avec offset ; omets pour pas d’expiration
`minAmount`, `maxAmount`	Bornes pour `variable`, unités mineures, ≤ 1 000 000
`maxPayments`	`reusable` uniquement ; se désactive après ce nombre de paiements
`imageUrl`	URL affichée au checkout
`successMode`	`thank_you` (par défaut) ou `redirect`
`successMessage`	Mode `thank_you` uniquement
`successRedirectUrl`	Requis quand `successMode` est `redirect`
`collectBusinessName`, `collectCustomerName`, `collectEmail`, `collectPhone`	Booléens, par défaut `false`

Renvoie le lien créé dans data. Déclenche le webhook payment_link.created.

`get-payment-link-qr`

Lecture. Le seul outil qui renvoie une image.

Entrée	Notes
`id`	ID externe, `plink_…`
`size`	Pixels, 100–2000 ; par défaut 500

Le résultat porte les métadonnées de checkout dans structuredContent (et le bloc texte JSON) plus un bloc content natif MCP image/png. Il n’y a pas de champ base64 à l’intérieur de data.

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

Entrées partagées

Venues

`list-venues`

`get-venue`

Commandes

`list-orders`

`get-order`

`get-order-events`

Menus

`list-menus`

`get-menu`

Snooze

`get-snooze-report`

Stats

`get-order-stats`

`list-top-products`

Réductions

`list-discount-codes`

`create-discount-code`

Remboursements

`list-refunds`

Pay at table

`list-bills`

Liens de paiement

`list-payment-links`

`get-payment-link`

`create-payment-link`

`get-payment-link-qr`

​Entrées partagées

​Venues

​list-venues

​get-venue

​Commandes

​list-orders

​get-order

​get-order-events

​Menus

​list-menus

​get-menu

​Snooze

​get-snooze-report

​Stats

​get-order-stats

​list-top-products

​Réductions

​list-discount-codes

​create-discount-code

​Remboursements

​list-refunds

​Pay at table

​list-bills

​Liens de paiement

​list-payment-links

​get-payment-link

​create-payment-link

​get-payment-link-qr

Entrées partagées

Venues

`list-venues`

`get-venue`

Commandes

`list-orders`

`get-order`

`get-order-events`

Menus

`list-menus`

`get-menu`

Snooze

`get-snooze-report`

Stats

`get-order-stats`

`list-top-products`

Réductions

`list-discount-codes`

`create-discount-code`

Remboursements

`list-refunds`

Pay at table

`list-bills`

Liens de paiement

`list-payment-links`

`get-payment-link`

`create-payment-link`

`get-payment-link-qr`