Refunds

Use find refunds to import retained refund events for an authorized restaurant. Each event includes its own refund amount and date, a stable import identifier, and a link to the original order where it is still available. This read does not issue a refund or execute a payment action.

Access

Use fiest.restaurant.read, fiest.orders.read and fiest.accounting.read. Fiest can enable reviewed reads on an existing restaurant connection when the restaurant owner/admin has already approved them; 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.

Import refunds

GET /v1/restaurants/{restaurantId}/refunds?start_date=2026-07-01&end_date=2026-07-31&limit=20
Authorization: Bearer <access-token>

1. Choose an inclusive window of at most 31 refund business dates. The restaurant's timezone and business-day start are returned in period.
2. Import each event using (restaurantId, refundId) as the upsert key. Treat both identifiers as opaque strings.
3. Repeat the same request with the returned nextCursor in cursor until it is null. Keep dates and any order_id filter unchanged. Results are ordered by refund occurrence time and identifier, oldest first.
4. Retain each event's classification and evidence status. Reconcile the whole period before committing the import checkpoint.

The dates select refunds, even if their original sales are older. A June sale refunded in July appears in July's refund feed. To restrict the feed to one known original order, supply its exact opaque order_id.

Event amounts and returned lines

amountMinor is the positive amount of this event. Two partial refunds of EUR 20 and EUR 30 produce amounts of 2000 and 3000. The second cumulativeAmountMinor is 5000; it is informational and must not be imported as another refund. Known monetary amounts use integer minor units. Check currency; unknown historical currency remains null.

items contains incremental returned quantities with frozen sale names and stored line/catalog identifiers. Honor itemsEvidence and itemsTruncated. An amount-only refund or incomplete historical snapshot may have no provable item allocation. No historical item, tax rate or refund date is guessed.

If a tab payment attempt was never completed, was fully returned, and the tab was subsequently paid separately, the proven return is an unfinished_payment_refund. It must not reduce the later sale or its VAT. Older genuine refund cycles remain sale refunds. Fiest requires matching source, timing and complete tender evidence before making this distinction.

accounting reuses the same VAT, tender, tip and deferred gift-card calculation as accounting reports. Its amounts are signed credits. Check tenderAllocation, evidenceStatus and nullable fields before posting entries. A complete evidence status refers to the available reporting evidence; it is not independent confirmation from a payment provider.

Historical provenance=legacy_cumulative entries retain the available aggregate and date. They cannot recover each missing partial refund. Page-level legacyTiming and incompleteEvidence describe that page, so inspect every page.

Original order and payment references

When originalOrderId is present, pass it unchanged to get order details. The refund event keeps its frozen impact; the current order details show cumulative lifetime refund evidence. Do not import that cumulative evidence again as an event.

originalReceiptReference, originalSaleOccurredAt and originalSaleBusinessDate preserve retained source evidence. An archived sale may have these fields without a resolvable current originalOrderId.

Original-order details can include stored Viva, SumUp and Stripe identifiers. The event's paymentReference contains only refund-specific evidence that Fiest retained, such as a checkout reference. Missing provider and provider refund IDs remain null. An original sale transaction ID is not proof that a refund executed or settled. See provider payment references.

Voided orders

A recent-order void is separate from a sale refund. Voided orders remain in order history and order details with status=voided and zero recognized sales and VAT. Their original order amount remains available as evidence; it is not recognized revenue.

Order search (find_orders / the orders endpoint) retains the recorded total and VAT for history. Exclude status=voided rows when totaling those fields. Order details' grossSalesMinor, netSalesMinor and vatMinor report the zero recognized amounts; accounting summaries already apply this exclusion.

Voids do not produce events in this refund feed, even if a payment provider uses a refund to reverse the payment. This endpoint does not export the separate void ledger or provider-void references. Do not invent an additional refund credit for an order already excluded as voided.

Reconcile and refresh imports

Use accounting summary and payment report for the same refund period. Compare sale-refund accounting effects separately from pending-payment, extra-capture and unresolved returns. Summing every amountMinor is not the same as the accounting report's sale-refund total. Do not subtract credits again from already refund-adjusted sales totals.

This is an event-date export, not a change feed. Reread overlapping periods and upsert by ID to catch late recordings. Rescan historical periods when source evidence is repaired; the newest occurredAt is not a permanent change checkpoint. Historical reclassifications need reconciliation before booking, especially unresolved returns. Follow refund dates and signed amounts and respect report readiness.

MCP's find_refunds uses the same Services capability with orders and analytics read consent. It is available on both standard and read-only connections when those scopes are granted. Partner API tokens cannot be used with MCP.