> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyway.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# List refunds

> List the authenticated organization's refunds with filters, for reconciliation.

Authenticate with an API key that belongs to the target organization.

Each refund has the same fields as the `refund.succeeded` and `refund.failed`
[webhooks](https://docs.anyway.sh/api-reference/endpoint/webhooks.md), so you can reconcile events and API reads with
the same code. `status` is `succeeded`, `failed`, or `pending` (still awaiting review or
processing). No webhook is sent for `pending`; the refund sends `refund.succeeded` or
`refund.failed` when it ends.

To reconcile a period, filter by `date_from` and `date_to` and page through the results. To
see every refund on one order, filter by `order_id`. `totalRefundedCents` and `fullyRefunded`
describe the order at the time of the request. A webhook carries them as of its event, so once a later refund on the same order
succeeds, the API shows a higher total than that earlier webhook did.


## OpenAPI

````yaml api-reference/openapi.json GET /v1/refunds
openapi: 3.0.3
info:
  description: >-
    Organization-scoped commerce API for merchant backends: create and manage
    checkout sessions, and query commerce records.
  title: Anyway Merchant API
  contact: {}
  version: '1.0'
  x-source: anyway-backend-go
servers:
  - url: https://merchant-api-prod.anyway.sh
security: []
paths:
  /v1/refunds:
    get:
      tags:
        - refunds
      summary: List refunds
      description: >-
        Returns the org's refunds, newest first, in the same shape as the
        refund.succeeded / refund.failed webhooks. status is succeeded, failed
        or pending (awaiting review or processing). totalRefundedCents and
        fullyRefunded describe the order as of the request, so they can be
        higher than in an earlier webhook for the same refund if a later refund
        on the order succeeded.
      parameters:
        - description: Page number
          name: page
          in: query
          schema:
            type: integer
            default: 1
        - description: Page size (max 100)
          name: size
          in: query
          schema:
            type: integer
            default: 20
        - description: Filter by order ID (ORD_...)
          name: order_id
          in: query
          schema:
            type: string
        - description: succeeded, failed or pending
          name: status
          in: query
          schema:
            type: string
        - description: Refunds requested at or after this unix timestamp
          name: date_from
          in: query
          schema:
            type: integer
        - description: Refunds requested at or before this unix timestamp
          name: date_to
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/response.ApiResponse-merchantapi_PaginatedResponse-merchantapi_RefundResponse
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response.ApiResponse-any'
      security:
        - APIKeyAuth: []
components:
  schemas:
    response.ApiResponse-merchantapi_PaginatedResponse-merchantapi_RefundResponse:
      type: object
      properties:
        data:
          $ref: >-
            #/components/schemas/merchantapi.PaginatedResponse-merchantapi_RefundResponse
        error:
          $ref: '#/components/schemas/response.ErrorDetail'
        message:
          type: string
        success:
          type: boolean
    response.ApiResponse-any:
      type: object
      properties:
        data: {}
        error:
          $ref: '#/components/schemas/response.ErrorDetail'
        message:
          type: string
        success:
          type: boolean
    merchantapi.PaginatedResponse-merchantapi_RefundResponse:
      type: object
      properties:
        current:
          description: 'Deprecated: use page.'
          type: integer
          deprecated: true
        page:
          type: integer
        pages:
          type: integer
        records:
          type: array
          items:
            $ref: '#/components/schemas/merchantapi.RefundResponse'
        size:
          type: integer
        total:
          type: integer
    response.ErrorDetail:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    merchantapi.RefundResponse:
      type: object
      properties:
        amountCents:
          description: this refund, in the order's currency
          type: integer
        createdAt:
          description: when the refund was requested
          type: string
        currency:
          description: lowercase ISO 4217
          type: string
        failedAt:
          description: 'failed: when it was rejected or declined'
          type: string
        failureReason:
          description: >-
            FailureReason (failed only) is "rejected" (declined during Anyway's
            review)

            or "declined" (declined when processed).
          type: string
        fullyRefunded:
          type: boolean
        orderId:
          type: string
        orgId:
          type: string
        reason:
          type: string
          nullable: true
        refundId:
          description: Anyway RFN_ id
          type: string
        refundedAt:
          description: 'succeeded: when the payment partner confirmed it'
          type: string
        status:
          description: '"succeeded" | "failed"; Merchant API reads also "pending"'
          type: string
        totalRefundedCents:
          description: >-
            TotalRefundedCents sums every succeeded refund on the order (this
            one

            included when it succeeded); FullyRefunded is true once it reaches
            the

            order's total paid. A webhook carries both as of its event; a
            Merchant API

            read, as of the request. They differ once a later refund on the
            order succeeds.
          type: integer
  securitySchemes:
    APIKeyAuth:
      description: 'Merchant API key (format: ak_BASE64)'
      type: apiKey
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.