Fiest Developers

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>
  1. Choose an inclusive period of at most 31 refund business dates. The response includes the restaurant's timezone and business-day start.
  2. Save each event using (restaurantId, refundId) as the unique key. Treat both IDs as opaque strings.
  3. Pass nextCursor as cursor to fetch the next page. Keep the dates and any order_id filter unchanged, and continue until nextCursor is null.
  4. 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 kindAccounting treatment
sale_refundUse the returned signed sales and VAT amounts.
pending_payment_refundDoes not reduce completed sales or VAT.
duplicate_capture_refundDoes not reduce sales or VAT.
unfinished_payment_refundDoes not reduce completed sales or VAT.
unresolved_refundReview 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.

On this page