Refunds
Import individual refunds and reconcile them with accounting reports.
Use find refunds to read refund events for an authorized restaurant. Each event has its own amount, date and stable ID, plus a link to the original order when available. This endpoint only reads refunds; it does not issue them.
Access
Partner API reads require fiest.restaurant.read, fiest.orders.read and
fiest.accounting.read, approved by the restaurant owner or admin. See
connection setup for authorization.
For MCP, use find_refunds with restaurant, orders and analytics read access.
It is available on standard and read-only connections with those permissions.
Partner API tokens cannot be used with MCP.
Import refunds
GET /v1/restaurants/{restaurantId}/refunds?start_date=2026-07-01&end_date=2026-07-31&limit=20
Authorization: Bearer <access-token>- Choose an inclusive period of at most 31 refund business dates. The response includes the restaurant's timezone and business-day start.
- Save each event using
(restaurantId, refundId)as the unique key. Treat both IDs as opaque strings. - Pass
nextCursorascursorto fetch the next page. Keep the dates and anyorder_idfilter unchanged, and continue untilnextCursoris null. - Check the evidence and reconcile the full period before completing the import.
The dates select refunds, even when the original sale is older. A June sale
refunded in July appears in July's results. Use order_id to filter by a known
original order.
Amounts and returned items
amountMinor is this event's positive refund amount in cents. Two partial
refunds of EUR 20 and EUR 30 have amounts of 2000 and 3000. The cumulative total
of 5000 is informational; do not import it as a third refund. Check currency
before posting amounts.
Returned items contain the names and quantities available from the original
sale. Check itemsEvidence and itemsTruncated; an amount-only refund may not
identify which items were returned.
| Event kind | Accounting treatment |
|---|---|
sale_refund | Use the returned signed sales and VAT amounts. |
pending_payment_refund | Does not reduce completed sales or VAT. |
duplicate_capture_refund | Does not reduce sales or VAT. |
unfinished_payment_refund | Does not reduce completed sales or VAT. |
unresolved_refund | Review before posting; the accounting impact may be unknown. |
Check the event's accounting.evidenceStatus, payment allocation and nullable
amounts. Missing values are unknown, not zero. Historical cumulative entries
cannot recover missing partial-refund dates. Inspect legacyTiming and
incompleteEvidence on every page.
Original order and payment references
When originalOrderId is present, pass it unchanged to
get order details. Order details may show a
cumulative refund total; do not import that total again as an event.
Original-sale and refund-specific payment references are different. A sale transaction ID does not prove that a refund settled. Missing references remain null. See payment references.
Voided orders
Voided orders are excluded from recognized sales and VAT. Their original
amount may still appear in order history. Exclude status=voided when totaling
history fields.
Voids are not events in this refund feed. Do not create another refund credit for a voided order already excluded from sales.
Reconcile and refresh imports
Compare refunds with the accounting summary
and payment report for the same period.
Use refundBreakdown, when available, to separate sales refunds from tips,
gift-card liabilities and other returns. Do not deduct refunds again from
already adjusted sales totals.
Reread overlapping periods and update events by their unique key to catch late or corrected records. The latest refund date is not a permanent checkpoint. Follow the accounting checks before posting changes.
Find refund events
Lists individual refunds by their refund business date, oldest first, with incremental amounts, stable opaque refund IDs, original order links when resolvable, frozen…
Find orders
Returns newest-first order summaries. Exact order_id lookup and cursor browsing may search all history; partial or operational filters require an inclusive date range of at…