# Find refund events

Source: https://docs.fiest.io/api/reference/find-refunds
Canonical sandbox contract: https://docs.fiest.io/openapi.yaml

## GET /v1/restaurants/{restaurantId}/refunds

Lists individual refunds by their refund business date, oldest first, with incremental amounts, stable opaque refund IDs, original order links when resolvable, frozen returned-line quantity deltas and signed canonical accounting impacts. A June sale refunded in July appears in July. Includes separately classified pending-payment and extra-capture returns; these do not imply a new sale or VAT credit. Legacy cumulative evidence cannot prove missing partial refund dates. Follow every nextCursor unchanged with the same restaurant, date and order filters. Flags are page-local. Re-read overlapping windows and deduplicate refundId to catch late evidence; pagination is not a permanent change feed. Unknown impacts remain null. Original sale references from getOrderDetails do not prove provider refund execution.

## Authentication

Send an OAuth access token in the `Authorization` header as
`Bearer $FIEST_ACCESS_TOKEN`.

Required scopes: `fiest.restaurant.read`, `fiest.orders.read`, `fiest.accounting.read`

## Quick request

```bash
curl --request GET \
  --url 'https://api-sandbox.fiest.io/v1/restaurants/11111111-1111-4111-8111-111111111111/refunds?start_date=start_date&end_date=end_date' \
  --header 'Authorization: Bearer $FIEST_ACCESS_TOKEN'
```

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `restaurantId` | path | Yes | string (uuid) | A restaurant identifier returned by the authorized restaurant list. |
| `organization_id` | query | No | string (uuid) | An organizationId returned by GET /v1/organizations. Required for restaurant-scoped calls when a Management portfolio authorization covers more than one organization; omitted for a single-restaurant authorization and optional for a one-organization grant. |
| `start_date` | query | Yes | string (date) | Inclusive refund business date. The window must not exceed 31 days. |
| `end_date` | query | Yes | string (date) | Inclusive refund business date. |
| `order_id` | query | No | string | Exact opaque original order ID; optional. Omit to include returns with no completed original order. |
| `cursor` | query | No | string | Use the preceding response nextCursor unchanged with the same filters. |
| `limit` | query | No | integer |  |

## Success response

### 200 — A bounded page of individual refund events.

```json
{
  "data": {
    "restaurantId": "11111111-1111-4111-8111-111111111111",
    "period": {
      "startDate": "2026-07-01",
      "endDate": "2026-07-31",
      "timeZone": "Europe/Helsinki",
      "dayStartHour": 0
    },
    "policy": "refund-event-date/v1",
    "events": [],
    "nextCursor": null,
    "truncated": false,
    "legacyTiming": false,
    "incompleteEvidence": false
  }
}
```

## Error responses

### 400 — The request parameters are invalid.

```json
{
  "error": "invalid_request",
  "message": "The requested date range is invalid.",
  "request_id": "req_sandbox_invalid_request"
}
```

### 401 — The access token is missing, invalid, or expired.

```json
{
  "error": "invalid_token",
  "error_description": "The access token is invalid.",
  "request_id": "req_sandbox_invalid_token"
}
```

### 403 — The authorization has expired or does not include the required scope.

```json
{
  "error": "insufficient_scope",
  "error_description": "The operation requires an OAuth scope that is not granted.",
  "request_id": "req_sandbox_insufficient_scope"
}
```

### 429 — The partner request limit has been exceeded.

```json
{
  "error": "rate_limited",
  "request_id": "req_sandbox_rate_limited"
}
```

### 503 — The API or one of its required services is unavailable.

```json
{
  "error": "service_unavailable",
  "request_id": "req_sandbox_service_unavailable"
}
```

## Related

- [Quick start](https://docs.fiest.io/api/quickstart)
- [Stable API errors](https://docs.fiest.io/api/reference/errors)
- [OpenAPI 3.1 contract, YAML](https://docs.fiest.io/openapi.yaml)
- [OpenAPI 3.1 contract, JSON](https://docs.fiest.io/openapi.json)
- [Refund export and reconciliation](https://docs.fiest.io/api/refunds)