Search refunds

Operation ID: searchRefunds

Group: Accounting › Refunds

Open in the interactive reference

POST /accounting/refunds/search

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches refunds. A refund must match every filter you send. Unlike GET accounting/refunds, which takes one status, this endpoint takes several approval statuses at once and can filter by the refund's id.

GET accounting/refunds and GET accounting/refunds/:id return the same fields for each refund.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.

Request body

Required, application/json: searchRefundsInput.

Field Type Required Description
id string no Limits results to the refund with this identifier.
status array<any> no Limits results to refunds in any of these approval states. Omit or pass an empty array to return every state. Example: ["pendingApproval","revise"].
paymentId string no Limits results to refunds against this source payment. See id on GET accounting/payments/:id.
customerId string no Limits results to refunds for this customer. See id on GET accounting/customers/:id. Example: "9c2a6a10-7d34-4c8e-9b21-5a0f3e6d81b7".
refundDate object no Limits results to refunds whose refundDate falls in this range. Both bounds are inclusive. Omit either bound to leave that side open.
refundDate.start date no The earliest refundDate to include, inclusive. Format YYYY-MM-DD.
refundDate.end date no The latest refundDate to include, inclusive. Format YYYY-MM-DD.
lastModifiedDate object no Limits results to refunds whose lastModifiedDate falls in this range, in UTC. Both bounds are inclusive. Omit either bound to leave that side open. Format YYYY-MM-DDTHH:mm:ss.sssZ.
lastModifiedDate.start string no The earliest change time to include, inclusive.
lastModifiedDate.end string no The latest change time to include, inclusive.
page object no The pagination controls. Omit for the first page. Example: {"size":50}.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit for the first page.
page.size number no The number of refunds per page. Defaults to 50. A value above 200 is treated as 200, not rejected. 
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": [
    "pendingApproval",
    "revise"
  ],
  "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerId": "9c2a6a10-7d34-4c8e-9b21-5a0f3e6d81b7",
  "refundDate": {
    "start": "2026-01-15",
    "end": "2026-01-15"
  },
  "lastModifiedDate": {
    "start": "<start>",
    "end": "<end>"
  },
  "page": {
    "size": 50
  }
}

Response

200 Success

Under data (searchRefundsOutput):

Field Type Required Description
items array<object> yes The refunds that match, most recently created first. An empty array when nothing matches. Example: [{"id":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","refundNumber":"REF-1042","refundDate":"2026-08-01","approvalStatus":"approved","refundType":"ach","currency":"USD","amount":"150.00","unappliedAmount":"0.00","customerId":"9c2a6a10-7d34-4c8e-9b21-5a0f3e6d81b7","customerName":"Northwind Traders","entityId":"1a24d5e9-3b7d-4f80-9c6d-2e8f70b13a45","paymentId":"5a0f3e6d-81b7-4c8e-9b21-9c2a6a107d34","paymentNumber":"PMT-7781","lastModifiedDate":"2026-08-01T09:12:44.000Z"}].
items[].id string yes The unique identifier for the refund.
items[].refundNumber string no The refund number, unique within the tenant, for example 'REF-1042'.
items[].refundDate date yes The date the refund was issued. Format YYYY-MM-DD.
items[].approvalStatus string no The approval status. Possible values: 'draft', 'pendingApproval', 'revise', 'approved', 'rejected'.
items[].refundType string yes The payment method used for the refund. Possible values: 'check', 'ach', 'wire', 'creditCard', 'directDebit', 'sepaCreditTransfer'.
items[].currency string yes The currency of the refund. Every amount on it is in this currency. Format ISO 4217, for example 'USD'.
items[].amount decimal yes The refund amount, in the refund currency.
items[].unappliedAmount decimal no The unapplied balance remaining on the source payment, in the refund currency.
items[].refundNote string no A free-form note attached to the refund. Absent when none was set.
items[].customerId string yes The customer receiving the refund. See id on GET accounting/customers/:id.
items[].customerName string no The name of the customer receiving the refund.
items[].entityId string yes The legal entity issuing the refund. See id on GET base/entities.
items[].paymentId string yes The source payment being refunded. See id on GET accounting/payments/:id.
items[].paymentNumber string no The number of the source payment being refunded.
items[].lastModifiedDate date-time yes The date and time the refund last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
pagination object yes The pagination cursor for this page. Example: {"hasMore":false}.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean yes True when more matches remain beyond this page. 
{
  "data": {
    "items": [
      {
        "id": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
        "refundNumber": "REF-1042",
        "refundDate": "2026-08-01",
        "approvalStatus": "approved",
        "refundType": "ach",
        "currency": "USD",
        "amount": "150.00",
        "unappliedAmount": "0.00",
        "customerId": "9c2a6a10-7d34-4c8e-9b21-5a0f3e6d81b7",
        "customerName": "Northwind Traders",
        "entityId": "1a24d5e9-3b7d-4f80-9c6d-2e8f70b13a45",
        "paymentId": "5a0f3e6d-81b7-4c8e-9b21-9c2a6a107d34",
        "paymentNumber": "PMT-7781",
        "lastModifiedDate": "2026-08-01T09:12:44.000Z"
      }
    ],
    "pagination": {
      "hasMore": false
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Statuses