List a merchant's subscription charges
GET/merchants/{merchantId}/chargesList a merchant's subscription charges — both succeeded and failed — in descending ingestion order. Use for health dashboards, dunning workflows (filter status=failed), and reconciliation. Filter by subscription, subscriber, status, chain, and date range.
Headers
| Header | Description | Required |
|---|---|---|
| Authorization | Bearer token with your secret API key | yes |
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| merchantId | string | yes |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| limit | integer | — | Rows per page, 1 to 100. Defaults to 50. Values outside the range are rejected rather than clamped. |
| starting_after | string | — | Cursor for forward pagination: an object id from a previous page. Returns results after it. Mutually exclusive with ending_before; sending both is a 400. |
| ending_before | string | — | Cursor for backward pagination: an object id from a previous page. Returns results before it. Mutually exclusive with starting_after; sending both is a 400. |
| subscriber | string | — | |
| subscription_id | string | — | |
| external_customer_id | string | — | |
| chain | string | — | |
| from | string · date-time | — | |
| to | string · date-time | — | |
| status | enum: succeeded | failed | — |
Example Request
Request
const response = await fetch('https://checkout-api.exodus-int.com/merchants/<merchantId>/charges?limit=50&starting_after=<starting_after>&ending_before=<ending_before>&subscriber=<subscriber>&subscription_id=<subscription_id>&external_customer_id=<external_customer_id>&chain=<chain>&from=<from>&to=<to>&status=succeeded', {
method: 'GET',
headers: {
Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
},
});Responses
| Status | Description |
|---|---|
| 200 | A paginated list of subscription charges. |
| 400 | Validation error |
| 401 | Missing or invalid authentication |
| 403 | API key lacks the required scope |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
| object | enum: list | yes | |
| data | object[] | yes | |
| has_more | boolean | yes |
data
| Field | Type | Required | Description |
|---|---|---|---|
| object | enum: subscription_charge | yes | |
| id | string | yes | |
| subscription_id | string | yes | |
| subscriber | string | yes | |
| amount | string | yes | |
| fee | string | yes | |
| tx_hash | string | null | yes | |
| chain | string | yes | |
| token_symbol | string | null | yes | |
| token_decimals | number | null | yes | |
| charge_nonce | number | yes | |
| charged_at | string | yes | |
| status | enum: succeeded | failed | yes | |
| failure_reason | string | null | yes | |
| block_number | string | yes | |
| metadata | object | null | yes | |
| created_at | string | yes |
Example Response
{
"object": "list",
"data": [
{
"object": "subscription_charge",
"id": "subc_6789abcdef012345",
"subscription_id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
"subscriber": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
"token_symbol": "USDC",
"token_decimals": 6,
"amount": "9990000",
"fee": "0",
"tx_hash": "0x8a9c67b2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
"chain": "eip155:1",
"charge_nonce": 3,
"charged_at": "2026-05-19T12:02:18Z",
"status": "succeeded",
"failure_reason": null,
"block_number": "12346789",
"metadata": {
"invoice_id": "inv_202605"
},
"created_at": "2026-05-19T12:02:18Z"
}
],
"has_more": false
}Error Response
Error (e.g. 400)
{
"error": {
"type": "validation_error",
"message": "starting_after and ending_before are mutually exclusive",
"param": "ending_before"
}
}