Charge a subscription
POST/subscriptions/{subscriptionId}/chargeCharge an active subscription. Sign the charge amount together with the subscription's current charge_nonce; Exodus submits the on-chain charge and pays the gas. Quote first: amount is the token amount the charge quote returned and price_lock_code is its code. Each charge is bounded by the per-call cap_amount and the per-cycle budget, so multiple charges may run within a period until the budget is exhausted. Succeeded charges are recorded in the charges ledger and dispatched via the subscription.charge_succeeded webhook.
Headers
| Header | Description | Required |
|---|---|---|
| Authorization | Bearer token with your secret API key | yes |
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| subscriptionId | string | yes |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| amount | string | yes | The amount to charge, in the settlement token's smallest units, identical to the amount signed. This is the amount the charge quote returned, verbatim. On a legacy token-denominated plan (no price_currency) it is any amount within cap_amount and the remaining per-window budget. |
| price_lock_code | string | — | The price_lock_code of the charge quote whose amount is being charged. Required on fiat-priced plans, which is every plan that can be created today; the schema keeps it optional only for legacy token-denominated plans. The quote is bound to this subscription and to amount, and a missing, mismatched, expired or already-used code is rejected. A code minted for another subscription is reported as not found. Ignored on a legacy token-denominated plan. |
| metadata | object | — | 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.com/subscriptions/<subscriptionId>/charge', {
method: 'POST',
headers: {
Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
"amount": "9990000",
"price_lock_code": "refq_3f9a1c7d2e5b8064",
"metadata": {
"invoice_id": "inv_202605"
}
}),
});Responses
| Status | Description |
|---|---|
| 200 | The charge result — status is always succeeded on a 200 (failures throw error responses). Fetch the subscription for the updated budget and scheduling state. |
| 400 | Validation error |
| 401 | Missing or invalid API key, missing X-Signature header, or the X-Signature was not produced by the merchant signer registered for the subscription's chain ("Invalid merchant signature"). A present but wrong-size X-Signature is rejected as a 400 with param: X-Signature; it must be a 64-byte (Solana) or 65-byte (EVM) hex string. |
| 403 | API key lacks the required scope |
| 404 | Resource not found |
| 409 | The subscription or the quote is in a state that refuses the charge. subscription_cancelled: the subscription is cancelled or cancelling. quote_expired: the price_lock_code passed its expires_at. quote_already_used: the price_lock_code was already reserved or consumed by another request. Re-quote and re-sign for either quote code. charge_already_recorded: a charge is already recorded for this charge_nonce; a retry at that nonce gets this answer once the charge is indexed, unless it reuses the same price_lock_code (quote_already_used). data carries subscription_id, charge_id, status (always succeeded), tx_hash and charge_nonce of the recorded charge. Do not resubmit. already_submitted: an earlier request already used this charge_nonce (a charge, a cancel or a migration) and is not recorded yet, so this request was not applied and no failed charge is recorded. data carries subscription_id, charge_nonce and tx_hash: the hash of the newest charge that the API sent, that mined and is not recorded yet, else null. Do not resubmit: wait for the webhook, or fetch the subscription, before sending another request. |
| 422 | The charge cannot be processed as sent. A price_currency the business cannot quote carries code: price_currency_not_quotable (type: invalid_request). On a fiat-settled business, a stablecoin amount below the settlement floor of 1.00 USD, or the provider's higher minimum, carries code: amount_below_settlement_minimum with data.minimum_usd (type: invalid_request), and one above the provider's settlement maximum, when it declares one, carries code: amount_above_settlement_maximum with data.maximum_usd (type: invalid_request); the price_lock_code is not reserved. The other configuration and request-shape rejections carry no code (type: invalid_request): fiat settlement not configured, price_currency differs from the settlement currency, price_lock_code missing on a fiat-priced plan, fiat amount (plan price or quoted amount) exceeds the safe range for fiat settlement, merchant signer not configured. Ceilings: amount_exceeds_cap, budget_exceeded, missing_budget_state. Quote binding: quote_amount_mismatch, quote_asset_mismatch, quote_not_found; re-quote and re-sign. Compliance screening (type: cannot_process): flagged, either because the subscriber failed screening or because the merchant's settlement address is under a compliance hold after an out-of-band rotation; the hold clears when the merchant rotates to a different address that passes screening. Revert decoded before submission: code is the contract error name (BudgetExceeded, ChargeAmountExceedsCap, InsufficientBalance, InsufficientAllowance, SubscriptionNotActive, SubscriptionNotFound, InvalidSignature); the failed charge is recorded in the charges ledger unless a read of the chain shows the nonce already spent; at a spent nonce the API answers 409 charge_already_recorded or 409 already_submitted instead, as the 409 response describes. If that read fails, the API answers 503 and records no failed charge. A contract revert the API cannot name carries code: UnknownRevert. The failed charge is recorded the same way, and subscription.charge_failed fires. The API records at most one such failed charge, and fires one webhook, per subscription, charge_nonce and revert in each clock hour (UTC); the revert is its error selector, plus its message for a require revert. A replay with the same revert in that hour answers the same 422 and records nothing. On a fiat-priced plan the quote is released, so the same price_lock_code can be sent again until expires_at. TokenNotSettleableOnChain: the subscription's chain and token cannot be settled by the business's settlement provider; the failed charge is recorded in the charges ledger and subscription.charge_failed fires. A failed charge consumes no charge_nonce and no budget. A retry can succeed once the cause is resolved, except after SubscriptionNotActive or SubscriptionNotFound. After TokenNotSettleableOnChain, a retry will not succeed unless the settlement provider adds the pair; contact support. Post-submission revert on EVM, and the Solana program errors the API recognises: OnChainRevert; the failed charge is recorded with its tx_hash unless a read of the chain shows the nonce already spent; at a spent nonce the API answers 409 charge_already_recorded or 409 already_submitted instead, as the 409 response describes. If that read fails, the API answers 503 and records no failed charge, even though the transaction mined: the charges ledger does not show that reverted tx_hash, no subscription.charge_failed fires for it, and a retry sends a new transaction. An empty revert can answer 422 or 500 depending on whether the chain's RPC returns revert data. A chain error with no revert data, an EnforcedPause revert, or a revert the node returns when the signed charge is sent, returns the 500 described below. |
| 500 | Relayer wallet not configured on this environment (no code); the quote is released, so once the environment is fixed the same amount, price_lock_code and signature stay valid until expires_at. charge_persist_failed: the charge landed on-chain but its receipt could not be recorded; data carries subscription_id, charge_nonce and tx_hash. Do not resubmit: the charge appears once indexed, and metadata can be attached afterwards through the charge metadata endpoint. Any other unexpected failure inside the charge relay, including a chain error with no revert data, an EnforcedPause revert, or a revert the node returns when the signed charge is sent, returns "Internal server error" with no code (a receipt-wait failure after broadcast returns the 504 below instead); the quote is not released on that path, so re-quote before retrying. |
| 503 | type: service_unavailable. No code: the relayer is paused by operators or, on EVM, cannot pay gas right now, or the merchant's settlement address is awaiting a compliance re-screen after an out-of-band rotation, or the address the merchant's payment factory holds on-chain differs from the one Exodus has screened (message The settlement address on this chain differs from the one Exodus has screened; the relay refuses until the rotation monitor screens it or the merchant rotates that chain through the settlement endpoint), or the subscription manager points at a payment factory that is neither the screened one nor the target of a signer rotation in progress (message The subscription manager on this chain points at a payment factory Exodus has not screened; retry the signer rotation or rotate the manager back), or one of those on-chain reads failed (message Settlement address check is temporarily unavailable; retry later), or a chain read failed that the relay needs to classify a revert or to check an earlier charge at the same charge_nonce (no failed charge is recorded and no webhook fires). The quote is released, so retry later with the same amount, price_lock_code and signature until expires_at. code: subscription_manager_paused: the merchant's subscription manager is paused on-chain; retrying will not succeed until the manager's pauser unpauses it. The pause may be Exodus-initiated as an incident response, so confirm the cause with support before unpausing. |
| 504 | code: tx_pending: the transaction was broadcast but the relay could not read its receipt within the wait (the wait timed out, or the RPC failed while polling). data carries subscription_id, charge_nonce and tx_hash. Do not resubmit: the charge appears in the ledger and subscription.charge_succeeded fires once it is indexed.
If the transaction reverts or never mines instead, no charge is recorded and no webhook fires: the nonce stays unconsumed, the subscription stays chargeable and the quote is deleted 72 hours after it expires, so confirm the hash on-chain before you re-quote.
A retry of the same charge:
- On a fiat-priced plan, a retry with the same price_lock_code is refused with 409 quote_already_used (after the charge is indexed too), because the quote stays held; once the quote is deleted it gets 422 quote_not_found.
- Any other retry sent before this transaction confirms answers 504 tx_pending with the same tx_hash and is not broadcast again. If the chain has no record of the transaction 5 minutes after it was sent, a retry is broadcast as a new transaction.
- Once the transaction mined, a retry gets 409 charge_already_recorded once the charge is indexed, before or after the indexer advanced the nonce, and 409 already_submitted while it is not indexed yet, with this hash in data.tx_hash; no failed charge is recorded and no webhook fires for that retry.
- A retry whose chain error carries no revert data returns the 500 described above instead, also with no failed charge.
- A migration or a cancel can also spend the nonce: the retry gets 409 already_submitted until the indexer records it, then 401 after a migration or 409 subscription_cancelled after a cancel. |
Response body
| Field | Type | Required | Description |
|---|---|---|---|
| subscription_id | string | yes | |
| charge_nonce | number | yes | |
| amount | string | yes | |
| tx_hash | string | yes | |
| status | enum: succeeded | yes | |
| metadata | object | null | yes |
Example Response
{
"subscription_id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
"charge_nonce": 3,
"amount": "9990000",
"tx_hash": "0x7e81c228fc4fcf0372a86ce6f8bbc457210a8b51fc30dee5557280e5153c9f06",
"status": "succeeded",
"metadata": {
"invoice_id": "inv_202605"
}
}Error Response
Error (e.g. 400)
{
"error": {
"type": "validation_error",
"message": "amount must be a positive number",
"param": "amount"
}
}Quote first
Every plan created today is fiat-priced, so a charge is a two-call sequence. Fetch a charge quote for the plan’s price or for an ad-hoc fiat amount, sign the token amount it returns, then submit that same amount together with the quote’s price_lock_code. The quote page carries the full quote-and-sign example.
Do not sign the subscription’s price. That value is in price_currency’s minor units, not settlement-token units, so signing it produces an amount that is wrong by orders of magnitude.
price_lock_code is listed as optional in the request schema because token-priced plans
(price_currency: null) predate quoting and still charge without one. For a fiat-priced plan it
is required, and omitting it is rejected with 422 price_lock_code is required for fiat-priced subscription charges.
Sign with the subscription’s current charge_nonce, read from GET /subscriptions/:id right before signing. Every succeeded charge increments it.
Retrying a charge
Once a charge_nonce is used on-chain, a retry at it is not applied: Exodus records no failed charge and sends no webhook. The response says what used it:
409 charge_already_recordedwhen Exodus has a succeeded charge at thatcharge_nonce.error.datacarriessubscription_id,charge_id,status(alwayssucceeded),tx_hashandcharge_nonce. Do not resubmit.subscription.charge_succeededhas fired or is being delivered.409 already_submittedwhen Exodus has not recorded what used thecharge_nonceyet. The message is “A request for this subscription was already submitted and is being confirmed. This one was not applied. Wait for the webhook, or fetch the subscription, before sending another request.”error.datacarriessubscription_id,charge_nonceandtx_hash. On a fiat-priced plan,tx_hashis the hash of the newest charge Exodus sent that went through on-chain and is not recorded yet; otherwise it isnull. Wait for the webhook, or fetch the subscription, before you send another request.
Only a retry at the subscription’s current charge_nonce, or at the charge_nonce of its latest recorded charge, gets one of these 409s. A retry signed at an older charge_nonce gets 401 Invalid merchant signature.
A cancel or a move to a new subscriber wallet can also use the charge_nonce, and then no charge exists at it. Until Exodus records the cancel or the move, the retry gets 409 already_submitted, usually with tx_hash: null. Once the subscription is cancelling or cancelled, the retry gets 409 subscription_cancelled. After the move, it gets 401 Invalid merchant signature; re-read the subscription and sign with its current charge_nonce.
On a fiat-priced plan, a retry with the same price_lock_code as a charge Exodus sent gets 409 quote_already_used instead, or 422 quote_not_found once Exodus deletes the quote.
In two rare cases a retry at a used charge_nonce gets no 409. When the chain error carries no revert data, the response is a 500 and no failed charge is recorded. When Exodus cannot read the subscription’s on-chain charge_nonce after the rejection, it records a failed charge and sends subscription.charge_failed, so you can receive both subscription.charge_succeeded and subscription.charge_failed for one charge_nonce. Treat subscription.charge_succeeded as the outcome.
Rejections
The quote binds price_lock_code to this subscription, its token and chain, and the exact amount it returned. A charge that breaks the binding is rejected with one of the codes in the quote page’s quote errors on charge table; re-quote and re-sign after any of them. A charge that fails after the quote was accepted (a typed simulation failure or an on-chain revert) usually releases it, so a retry can resubmit the same amount, price_lock_code and signature until expires_at. If the retry is rejected with a quote error, re-quote and re-sign. A TokenNotSettleableOnChain failure also releases the quote, but a retry will not succeed unless the settlement provider adds the pair; contact support. See retry guidance for each failure_reason.
The subscriber’s ceilings are enforced before anything is relayed. amount_exceeds_cap returns cap_amount; budget_exceeded returns spent_this_period and budget. Both fire at quote time and again at charge time, since spend can accrue between the two calls. Neither ceiling can be raised by the merchant; see cap and budget semantics. A charge whose signature does not verify gets 401 Invalid merchant signature before either ceiling and before screening.
On a fiat-settled business, a fiat-priced plan’s USDC or USDT amount below the settlement floor of 1.00 USD, or the provider’s higher minimum, is rejected with 422 amount_below_settlement_minimum (type: invalid_request). error.data carries subscription_id and minimum_usd, the floor that applied (for example "1.00"). The check runs before the quote is reserved, so the price_lock_code is not used up.
On the same plans, a USDC or USDT amount above the provider’s settlement maximum, when it declares one (999.99 USD for USD settlement), is rejected with 422 amount_above_settlement_maximum (type: invalid_request). error.data carries subscription_id and maximum_usd, the maximum that applied (for example "999.99"). This check also runs before the quote is reserved.
A charge the contract rejects at simulation, or that reverts on-chain, is persisted as a failed charge with a typed failure_reason and fires subscription.charge_failed, unless its charge_nonce was already used on-chain (see retrying a charge); see failed charges. On a fiat-priced plan of a fiat-settled business, the API also refuses a charge with TokenNotSettleableOnChain when the settlement provider cannot settle the subscription’s chain and token. The response is 422 with code: TokenNotSettleableOnChain. Nothing is broadcast, but the API persists that refusal as a failed charge and fires subscription.charge_failed. The other API-side rejections above are not persisted.
Rarely, Exodus sends the charge but cannot confirm it in time. The response is then a 504 with code: tx_pending, and data carries subscription_id, charge_nonce and tx_hash. Do not resubmit. The charge appears in the charges ledger and subscription.charge_succeeded fires once Exodus indexes it. If the transaction fails or never goes through, Exodus records no charge and sends no webhook. The charge_nonce stays unused and the subscription stays chargeable.
Check the tx_hash before you re-quote and re-sign. A retry of the same request fails. On a fiat-priced plan, it gets 409 quote_already_used, and 422 quote_not_found once Exodus deletes the quote, up to 72 hours after its expires_at. On a token-priced plan, it gets 409 already_submitted until Exodus records the charge, and 409 charge_already_recorded after. Neither records a failed charge or fires subscription.charge_failed.
On a fiat-priced plan, Exodus marks the price_lock_code as used after it records a succeeded charge. If that step fails, the API still returns the success response and fires subscription.charge_succeeded. Before, this case returned a 500 and sent no webhook, although the charge went through on-chain.
