List refunds · Ownrecord docs

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`	400	A filter or pagination value is invalid.	Fix the fields listed in `details.issues` and send the request again.
`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`	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`	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: api_version_unsupported, authentication_required, api_key_invalid, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

The refunds of a payment#

Refunds still owed to customers#

Errors#