Endpoint

Retrieve a refund

GET/v1/refunds/{id}

Returns one refund by its id, as the refund object. With expand, a field that holds an id holds that object instead.

Scope a restricted key needs: refunds:read
Publishable key: Not allowed: secret or restricted key only
Idempotency-Key: Not used. A GET is already safe to repeat.

Parameters

Parameters of Retrieve a refund
Parameter	Type and place	Meaning
`id`required	stringpath	The id of the refund.
`expand`	stringquery	Comma-separated fields to expand (Filtering, sorting and expanding), up to 5, one level deep: `order`, `payment`. Each field needs the read scope that its object's own GET needs (`customers:read` for a customer, `payments:read` for a payment); without it the call answers `insufficient_scope` naming that scope, and nothing is expanded.
`Orrerie-Version`	stringheader	API version date. Default: the version the key was created with. Example `2026-10-11`.

Example request

curl

curl https://api.orrerie.com/v1/refunds/rf_z20ve49yz5hve8f0xsdchj2v \
  -H "Authorization: Bearer $ORRERIE_SECRET_KEY"

JavaScript

const response = await fetch("https://api.orrerie.com/v1/refunds/rf_z20ve49yz5hve8f0xsdchj2v", {
  headers: {
    Authorization: `Bearer ${process.env.ORRERIE_SECRET_KEY}`,
  },
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

Python

import os
import requests

response = requests.get(
    "https://api.orrerie.com/v1/refunds/rf_z20ve49yz5hve8f0xsdchj2v",
    headers={"Authorization": f"Bearer {os.environ['ORRERIE_SECRET_KEY']}"},
    timeout=30,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

PHP

<?php
$request = curl_init('https://api.orrerie.com/v1/refunds/rf_z20ve49yz5hve8f0xsdchj2v');
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('ORRERIE_SECRET_KEY'),
    ],
]);
$body = curl_exec($request);
if ($body === false) {
    throw new RuntimeException(curl_error($request));
}
$result = json_decode($body, true);
if (curl_getinfo($request, CURLINFO_HTTP_CODE) >= 400) {
    throw new RuntimeException($result['error']['code'] . ': ' . $result['error']['message']);
}
print_r($result);

Responses

`200` OK

The answer is the refund object. Headers: Orrerie-Request-Id.

Example response, 200

{
  "id": "rf_z20ve49yz5hve8f0xsdchj2v",
  "object": "refund",
  "livemode": true,
  "created": "2026-10-12T10:00:00.000Z",
  "updated": "2026-10-12T10:13:40.000Z",
  "status": "confirmed",
  "pending_reason": null,
  "order": "ord_0zymngngvf12b8b2cra7tb8e",
  "payment": "pay_2pe50hae6w2jk4sp1rcq5pae",
  "amount": "5.00",
  "currency": "USD",
  "reason": "requested_by_customer",
  "note": "One bag arrived damaged",
  "rate_basis": "order_rate",
  "deduct_network_fee": false,
  "source": {
    "wallet": "wal_bsfw07hymawmda7gg8jsyy3g",
    "asset": "base:usdc",
    "amount": "5.000000"
  },
  "destination": {
    "address": "0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB",
    "asset": "ethereum:usdc",
    "network": "ethereum",
    "supplied_by": "payer_claim",
    "saved_address": null
  },
  "address_claim": {
    "sent_to": "jane@example.com",
    "sent_at": "2026-10-12T09:40:00.000Z",
    "claimed_at": "2026-10-12T10:00:00.000Z",
    "expires_at": "2026-10-26T09:40:00.000Z"
  },
  "approvable_at": null,
  "delivery": {
    "rail": "relay",
    "amount_estimated": "4.930000",
    "route_fee": {
      "amount": "0.07",
      "currency": "USD"
    },
    "fee_bearer": "recipient"
  },
  "network_fee": {
    "amount": "0.000002100000000000",
    "asset": "base:eth",
    "value": {
      "amount": "0.01",
      "currency": "USD"
    },
    "paid_by": "fee_account"
  },
  "requested_by": {
    "type": "api_key",
    "id": "key_6e3gg2c6ea176xxdek2nar6v"
  },
  "approved_by": "mem_ceh1wpzdrpk13cnpcjy9w0fa",
  "approval_url": "https://merchant.orrerie.com/approve/rf_z20ve49yz5hve8f0xsdchj2v",
  "approval_expires_at": "2026-10-19T10:00:00.000Z",
  "transaction_hash": "0x1f3cb18e896256d7d6bb8c11a6ec71f005c75de05e39beae5d93bbd1e2c8b7a9",
  "failure_code": null,
  "cancellation_reason": null,
  "approved_at": "2026-10-12T10:12:00.000Z",
  "sent_at": "2026-10-12T10:12:09.000Z",
  "confirmed_at": "2026-10-12T10:13:40.000Z",
  "metadata": {}
}

Any other status: an error

A status of 400 or above answers with the error object. Branch on its code, never on its message.

Errors

This call has no error of its own. It answers with the errors every call can answer with: a bad key, a missing scope, an object that does not exist, the rate limit. Every error code has its own entry.