Skip to main content
GET
/
api
/
reserves
# List all reserves
curl "https://api.swiftpay.cx/api/reserves?limit=20" \
  -H "Authorization: Bearer mp_live_your_api_key"

# Filter by status

curl "https://api.swiftpay.cx/api/reserves?status=active&limit=50" \
 -H "Authorization: Bearer mp_live_your_api_key"

# Paginate

curl "https://api.swiftpay.cx/api/reserves?cursor=cursor_abc123" \
 -H "Authorization: Bearer mp_live_your_api_key"

// List active reserves
const response = await fetch(
  'https://api.swiftpay.cx/api/reserves?status=active&limit=50',
  {
    headers: {
      'Authorization': 'Bearer mp_live_your_api_key'
    }
  }
);

const reserves = await response.json();

// Display upcoming releases
reserves.data.items.forEach(reserve => {
  const releaseAt = new Date(reserve.releaseAt);
  const amount = (reserve.reserveAmountInCents / 100).toFixed(2);
  console.log(`$${amount} releasing on ${releaseAt.toLocaleDateString()}`);
});
import requests

# List active reserves
response = requests.get(
    'https://api.swiftpay.cx/api/reserves',
    headers={'Authorization': 'Bearer mp_live_your_api_key'},
    params={'status': 'active', 'limit': 50}
)

reserves = response.json()

for reserve in reserves['data']['items']:
    amount = reserve['reserveAmountInCents'] / 100
    print(f"${amount:.2f} - Status: {reserve['status']}")
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "res_abc123",
        "paymentId": "sess_xyz789",
        "originalAmountInCents": 10000,
        "reserveAmountInCents": 10000,
        "reservePercentage": 10,
        "status": "active",
        "releasedAmountInCents": 0,
        "releaseAt": "2024-02-15T00:00:00Z",
        "releasedAt": null,
        "reservedAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "res_def456",
        "paymentId": "sess_uvw123",
        "originalAmountInCents": 5000,
        "reserveAmountInCents": 3000,
        "reservePercentage": 10,
        "status": "partially_released",
        "releasedAmountInCents": 2000,
        "releaseAt": "2024-02-10T00:00:00Z",
        "releasedAt": null,
        "reservedAt": "2024-01-10T14:20:00Z"
      }
    ],
    "nextCursor": "cursor_xyz789"
  }
}

List Reserves

Returns a paginated list of individual reserve records for your business.

Request

Authorization
string
required
Bearer token with your API key
status
string
Filter by status: active, partially_released, released, consumed
limit
integer
default:"20"
Number of results per page (1-100)
cursor
string
Pagination cursor for next page

Response

success
boolean
Whether the request was successful
data
object
# List all reserves
curl "https://api.swiftpay.cx/api/reserves?limit=20" \
  -H "Authorization: Bearer mp_live_your_api_key"

# Filter by status

curl "https://api.swiftpay.cx/api/reserves?status=active&limit=50" \
 -H "Authorization: Bearer mp_live_your_api_key"

# Paginate

curl "https://api.swiftpay.cx/api/reserves?cursor=cursor_abc123" \
 -H "Authorization: Bearer mp_live_your_api_key"

// List active reserves
const response = await fetch(
  'https://api.swiftpay.cx/api/reserves?status=active&limit=50',
  {
    headers: {
      'Authorization': 'Bearer mp_live_your_api_key'
    }
  }
);

const reserves = await response.json();

// Display upcoming releases
reserves.data.items.forEach(reserve => {
  const releaseAt = new Date(reserve.releaseAt);
  const amount = (reserve.reserveAmountInCents / 100).toFixed(2);
  console.log(`$${amount} releasing on ${releaseAt.toLocaleDateString()}`);
});
import requests

# List active reserves
response = requests.get(
    'https://api.swiftpay.cx/api/reserves',
    headers={'Authorization': 'Bearer mp_live_your_api_key'},
    params={'status': 'active', 'limit': 50}
)

reserves = response.json()

for reserve in reserves['data']['items']:
    amount = reserve['reserveAmountInCents'] / 100
    print(f"${amount:.2f} - Status: {reserve['status']}")
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "res_abc123",
        "paymentId": "sess_xyz789",
        "originalAmountInCents": 10000,
        "reserveAmountInCents": 10000,
        "reservePercentage": 10,
        "status": "active",
        "releasedAmountInCents": 0,
        "releaseAt": "2024-02-15T00:00:00Z",
        "releasedAt": null,
        "reservedAt": "2024-01-15T10:30:00Z"
      },
      {
        "id": "res_def456",
        "paymentId": "sess_uvw123",
        "originalAmountInCents": 5000,
        "reserveAmountInCents": 3000,
        "reservePercentage": 10,
        "status": "partially_released",
        "releasedAmountInCents": 2000,
        "releaseAt": "2024-02-10T00:00:00Z",
        "releasedAt": null,
        "reservedAt": "2024-01-10T14:20:00Z"
      }
    ],
    "nextCursor": "cursor_xyz789"
  }
}

Reserve Statuses

StatusDescription
activeReserve is locked, awaiting release date
partially_releasedSome funds consumed by refund, remainder still locked
releasedFull amount released to available balance
consumedEntire reserve used for refund/chargeback
For a detailed explanation of the reserve lifecycle and how they affect your balance, see the Understanding Reserves guide.