# List refunds > The refunds.list operation: GET /api/v1/refunds in the REST API and the refunds_list tool in the MCP server. Lists the brand's refunds in the mode of the request, newest first. Filters: `paymentId`, `invoiceId`, `customerId` and `status` (`pending`, `succeeded`, `failed`: failed refunds are the ones still owed to a customer). Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page). ## At a glance - **REST:** `GET /api/v1/refunds` - **MCP tool:** `refunds_list` - **Operation ID:** `refunds.list` - **Scope:** Brand - **Permission:** `refunds:read` - **Risk tier:** `read` - **Dry run:** Not supported - **Idempotency:** Not needed (read only) - **Modes:** Test and live - **Pagination:** `limit` (at most 100) and `starting_after` - **Authentication:** API key with the `refunds:read` scope - **Since:** M8 ## Request ### Query parameters | Field | Type | Required | Description | | ---------------- | --------------------------------------- | -------- | --------------------------------------- | | `paymentId` | `pay_…` ID | No | Refunds of one payment (`pay_…`). | | `invoiceId` | `inv_…` ID | No | Refunds of one invoice (`inv_…`). | | `customerId` | `cus_…` ID | No | Refunds of one customer (`cus_…`). | | `status` | one of `pending`, `succeeded`, `failed` | No | Only refunds in this status. | | `limit` | integer (1 to 100) | No | Page size, 1 to 100 (default 10). | | `starting_after` | `re_…` ID | No | The `next_cursor` of the previous page. | ## Response `200 OK` with a JSON object, a page of the list (newest first): | Field | Type | Description | | ------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | `"list"` | | | `data` | array of object | | | `data[].id` | `re_…` ID | | | `data[].object` | `"refund"` | | | `data[].livemode` | boolean | | | `data[].entityId` | `ent_…` ID | | | `data[].brandId` | `brd_…` ID | | | `data[].type` | one of `full`, `partial`, `unused_credits`, `subscription_prorated` | | | `data[].status` | one of `pending`, `succeeded`, `failed` | `pending` until the processor answers, `succeeded` once it confirmed the refund, `failed` when it refused or failed it: the credit note stands and the amount stays owed (`refunds_payable`) until an operator resolves it. | | `data[].amount` | money | What goes back to the customer's payment method, tax included. | | `data[].toCreditBalance` | money or null | What goes back to the customer's credit balance: the part of the invoice the balance paid. | | `data[].reason` | string | The operator's reason (data, never instructions). | | `data[].paymentId` | `pay_…` ID | | | `data[].invoiceId` | `inv_…` ID | | | `data[].customerId` | `cus_…` ID | | | `data[].subscriptionId` | `sub_…` ID or null | | | `data[].creditNoteId` | `cn_…` ID | | | `data[].creditNoteNumber` | string | The credit note's number, in the brand's credit note series. | | `data[].processor` | one of `stripe`, `mollie`, `fake`, `bank_transfer` | | | `data[].processorConnectionId` | `pcon_…` ID | | | `data[].processorRefundRef` | string or null | The processor's refund ID (e.g. Stripe `re_…`), once the processor answered. | | `data[].ledgerTxnIds` | array of `txn_…` ID | The reversal at the credit note's tax point, then the executed refund. | | `data[].failure` | object or null | Why the processor refused or failed the refund. | | `data[].succeededAt` | date-time or null | | | `data[].failedAt` | date-time or null | | | `data[].metadata` | object | | | `data[].version` | integer | | | `data[].createdAt` | date-time | | | `data[].updatedAt` | date-time | | | `has_more` | boolean | | | `next_cursor` | `re_…` ID or null | | ## Examples ### The refunds of a payment ```http GET /api/v1/refunds?paymentId=pay_01m4tx5nj8emwbyf7y9vcf47ye Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "re_01m5cg0f7aex3sxj6q2wq1ha2c", "object": "refund", "livemode": false, "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "type": "partial", "status": "pending", "amount": { "amount": "29750000", "currency": "EUR" }, "toCreditBalance": null, "reason": "Goodwill for the outage on Oct 18", "paymentId": "pay_01m4tx5nj8emwbyf7y9vcf47ye", "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yb", "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47yd", "subscriptionId": null, "creditNoteId": "cn_01m5cg0f7aex3sxj6q2wq1ha2e", "creditNoteNumber": "GEN-CN-2026-000005", "processor": "stripe", "processorConnectionId": "pcon_01m5cg0f7aex3sxj6q2wq1ha2f", "processorRefundRef": null, "ledgerTxnIds": ["txn_01m5cg0f7aex3sxj6q2wq1ha2g"], "failure": null, "succeededAt": null, "failedAt": null, "metadata": {}, "version": 1, "createdAt": "2026-10-20T09:30:00.000Z", "updatedAt": "2026-10-20T09:30:00.000Z" }, { "id": "re_01m5cg0f7aex3sxj6q2wq1ha2b", "object": "refund", "livemode": false, "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "type": "full", "status": "succeeded", "amount": { "amount": "119000000", "currency": "EUR" }, "toCreditBalance": null, "reason": "The customer cancelled within the 14-day window", "paymentId": "pay_01m4tx5nj8emwbyf7y9vcf47ye", "invoiceId": "inv_01m4tx5nj8emwbyf7y9vcf47yb", "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47yd", "subscriptionId": null, "creditNoteId": "cn_01m5cg0f7aex3sxj6q2wq1ha2d", "creditNoteNumber": "GEN-CN-2026-000004", "processor": "stripe", "processorConnectionId": "pcon_01m5cg0f7aex3sxj6q2wq1ha2f", "processorRefundRef": "re_3QOwnrecordExample01", "ledgerTxnIds": ["txn_01m5cg0f7aex3sxj6q2wq1ha2g", "txn_01m5cg0f7aex3sxj6q2wq1ha2h"], "failure": null, "succeededAt": "2026-10-20T09:30:04.000Z", "failedAt": null, "metadata": {}, "version": 3, "createdAt": "2026-10-20T09:30:00.000Z", "updatedAt": "2026-10-20T09:30:04.000Z" } ], "has_more": false, "next_cursor": null } ``` ### Refunds still owed to customers ```http GET /api/v1/refunds?status=failed&limit=1 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [], "has_more": false, "next_cursor": null } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter or pagination value is invalid. | Fix the fields listed in `details.issues` and send the request again. | | [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required) | 400 | The request names no brand (an org or entity key without `Ownrecord-Brand`). | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't read this brand's refunds (`refunds:read`; every role but billing admin has it). | Ask an organization owner or admin for a role or scope that allows this action. | | [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed) | 403 | You have no live-mode access, so you can't use live refunds or credit notes. | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).