Refunds and original orders

Approved order reads include the original order and its sold and refunded item lines. Accounting summaries remain the source for period totals. Reading order details does not create a refund, change a payment or execute a provider action.

Access

Use the approved fiest.restaurant.read and fiest.orders.read scopes. Accounting-only access does not unlock orders. Fiest can enable reviewed order reads on an existing restaurant connection when the restaurant owner/admin has already approved that access; client registration approval alone is insufficient. Issued access tokens retain their original scopes. A normal rotating refresh can receive explicitly approved reads, while an explicitly reduced scope stays reduced. A revoked, expired or missing refresh session requires the partner's existing Connect flow. See approved access and reconnects.

Find the original order

1. Use find orders inside the authorized restaurant. To find refunded orders sold in a period, supply an inclusive business-date range of at most 31 days and status=partially_refunded or status=refunded. These are separate filters; follow the returned nextCursor for every page.
2. Preserve the returned opaque orderId. If you already have that exact ID, the exact lookup can search all history; do not derive a database order key.
3. Pass the same ID unchanged to get order details.

The details include originalAmountMinor, totalAmountMinor, refundAmountMinor, items, refundedItems, tips, discounts and VAT evidence. All monetary amounts are integer EUR cents. Preserve line/catalog IDs when provided and honor itemsTruncated and refundedItemsTruncated; a bounded or historical response is not proof of a complete original document.

refundAmountMinor and refundedItems are cumulative evidence attached to the original order. This API does not currently expose a separate chronological refund-event listing with an event-to-order link for every credit. Do not invent an event date or identifier from the order creation time.

Sale date and refund date

Order-search date windows select the original order's business date. They are not refund-event-date exports. An order sold in June and refunded in July may be absent from a July order search even though its refund appears in July's accounting totals.

Use accounting summary and payment report for the refund period, following refund dates and signed amounts. Respect refundReporting.policy, legacyTiming, incompleteEvidence and report readiness. Do not subtract a refund again from sales totals that already include its effect, or mix cumulative order refunds into event-date totals.

Payment-provider references

Order details can include stored Viva, SumUp and Stripe identifiers in order.paymentReferences. Preserve the provider, receipt, transaction and checkout/session identifier types separately. A missing identifier stays null; references do not prove a refund, provider fee or bank settlement. See provider payment references for unavailable, empty and truncated results.

MCP's find_orders and get_order_details use the same shared Services reads. They require their own MCP grant; Partner API tokens cannot be used with MCP.