Update a subscription charge's metadata
PATCH/merchants/{merchantId}/charges/{chargeId}Replace the metadata object on a subscription charge. Use this to attach a reconciliation reference (invoice, order, or ledger id) after the fact — in particular when a charge relay request failed after the on-chain charge settled, so the metadata never persisted. Discover the charge via the list endpoint (filter by subscription_id, match on charge_nonce or tx_hash). The metadata is replaced wholesale, not merged; send { "metadata": {} } to clear it.
Headers
| Header | Description | Required |
|---|---|---|
| Authorization | Bearer token with your secret API key | yes |
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| merchantId | string | yes | |
| chargeId | string | yes |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| metadata | object | yes | Flat map of merchant-defined references. Up to 50 keys; keys up to 40 characters; values are strings up to 500 characters (nested values are rejected). |
Example Request
Request
const response = await fetch('https://checkout-api.exodus-int.com/merchants/<merchantId>/charges/<chargeId>', {
method: 'PATCH',
headers: {
Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"metadata": {
"invoice_id": "inv_202605"
}
}),
});Responses
| Status | Description |
|---|---|
| 200 | The charge with its updated metadata. |
| 400 | Validation error |
| 401 | Missing or invalid authentication |
| 403 | API key lacks the required scope |
| 404 | Resource not found |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
| object | enum: subscription_charge | yes | |
| id | string | yes | |
| subscription_id | string | yes | |
| subscriber | string | yes | |
| external_customer_id | string | null | yes | |
| amount | string | yes | |
| fee | string | yes | |
| fiat_amount | string | null | yes | The subscription's fixed per-cycle fiat price, in fiat_currency's minor units (e.g. cents for USD, centavos for ARS). Set at subscription creation and identical on every charge — not a per-charge market rate, and not a confirmation from the settlement provider (see settlement_status). Null when the subscription is not fiat-denominated, and on failed charges (including on-chain reverts) and indexer-created charges — except the charge taken at subscribe time on a business that settles in fiat, which the subscribe endpoint writes onto the indexer's row when the indexer recorded it first. |
| fiat_currency | string | null | yes | ISO-4217 code that fiat_amount is denominated in. Null whenever fiat_amount is null. |
| settlement_status | string | null | yes | Fiat settlement leg state: pending, completed, or failed. Null when the business settles in crypto (fiat_amount is then the subscription's price only, with no settlement leg behind it), when the subscription is not fiat-denominated, and on failed charges (including on-chain reverts) and indexer-created charges — except the charge taken at subscribe time on a business that settles in fiat, which the subscribe endpoint writes onto the indexer's row when the indexer recorded it first. |
| 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": "subscription_charge",
"id": "subc_6789abcdef012345",
"subscription_id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
"subscriber": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
"external_customer_id": "cus_42",
"token_symbol": "USDC",
"token_decimals": 6,
"amount": "9990000",
"fee": "0",
"fiat_amount": "1250000",
"fiat_currency": "ARS",
"settlement_status": "completed",
"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"
}Error Response
Error (e.g. 400)
{
"error": {
"type": "validation_error",
"message": "amount must be a positive number",
"param": "amount"
}
}