List Refunds

List Refunds

GET /v1/refunds

Returns a list of refunds for your organization. Supports filtering by status and processor, with offset-based pagination.

Authentication

Requires a Bearer token in the Authorization header.

Authorization: Bearer rk_live_your_api_key_here

Query Parameters

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | status | string | No | All | Filter by status: pending, processing, completed, failed, cancelled | | processor | string | No | All | Filter by payment processor name (e.g., stripe) | | limit | integer | No | 25 | Number of results to return. Min: 1, Max: 100. | | offset | integer | No | 0 | Number of results to skip for pagination. Min: 0. |

Response

Success (200)

{
  "data": [
    {
      "id": "ref_abc123def456",
      "organizationId": "org_xyz789",
      "externalRefundId": "re_1N4HcTKz9cXRvFYs",
      "transactionId": "ch_1N4HbSKz9cXRvFYr",
      "amount": 2500,
      "currency": "usd",
      "reason": "product_defective",
      "status": "completed",
      "processor": "stripe",
      "metadata": null,
      "initiatedBy": "api",
      "createdAt": "2026-02-22T10:30:00.000Z",
      "updatedAt": "2026-02-22T10:32:15.000Z"
    },
    {
      "id": "ref_ghi789jkl012",
      "organizationId": "org_xyz789",
      "externalRefundId": null,
      "transactionId": "ch_2M3GaSJy8bWqEXQp",
      "amount": 4999,
      "currency": "usd",
      "reason": "duplicate_charge",
      "status": "pending",
      "processor": "stripe",
      "metadata": {
        "ticketId": "SUP-1234"
      },
      "initiatedBy": "mcp",
      "createdAt": "2026-02-22T11:00:00.000Z",
      "updatedAt": "2026-02-22T11:00:00.000Z"
    }
  ]
}

Validation Error (400)

{
  "error": {
    "message": "Limit must be between 1 and 100",
    "code": "validation_error"
  }
}

Filtering Examples

By Status

GET /v1/refunds?status=completed
GET /v1/refunds?status=pending
GET /v1/refunds?status=failed

By Processor

GET /v1/refunds?processor=stripe

Combined Filters

GET /v1/refunds?status=completed&processor=stripe&limit=50

Pagination

Use limit and offset for pagination. The response returns up to limit results starting from offset.

GET /v1/refunds?limit=10&offset=0    # First page
GET /v1/refunds?limit=10&offset=10   # Second page
GET /v1/refunds?limit=10&offset=20   # Third page

When the response contains fewer results than the limit, you have reached the last page.

SDK Example

import RefundKit from '@refundkit/sdk';

const rk = new RefundKit({ apiKey: process.env.REFUNDKIT_API_KEY! });

// List completed refunds
const { data, error } = await rk.refunds.list({
  status: 'completed',
  limit: 10,
});

if (error) {
  console.error(error.message);
} else {
  console.log(`Found ${data.length} completed refunds`);
  for (const refund of data) {
    console.log(`  ${refund.id}: ${refund.amount} ${refund.currency}`);
  }
}

Paginating All Results

import type { Refund } from '@refundkit/sdk';

async function fetchAllRefunds(rk: RefundKit): Promise<Refund[]> {
  const results: Refund[] = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const { data, error } = await rk.refunds.list({ limit, offset });
    if (error) throw error;

    results.push(...data);

    if (data.length < limit) break;
    offset += limit;
  }

  return results;
}

cURL Example

# List all pending refunds, 10 per page
curl "https://api.refundkit.dev/v1/refunds?status=pending&limit=10&offset=0" \
  -H "Authorization: Bearer rk_live_your_api_key_here"