Quote the next charge for a subscription

POST/subscriptions/{subscriptionId}/charge-quote

Quote the next charge for a subscription. Crypto-priced plans return the fixed amount; fiat-priced plans return a locked rate and a price_lock_code to submit with the charge.

Headers

Header	Description	Required
Authorization	Bearer token with your secret API key	yes

Path Parameters

Name	Type	Required	Description
subscriptionId	string	yes

Example Request

Request

const response = await fetch('https://checkout-api.exodus-int.com/subscriptions/<subscriptionId>/charge-quote', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
  },
});

Responses

Status	Description
200	The charge quote, including any locked rate.
400	Validation error
401	Missing or invalid authentication
403	API key lacks the required scope
404	Resource not found

Response body

Field	Type	Required
object	enum: subscription_charge_quote	yes
subscription_id	string	yes
amount	string	yes
price_lock_code	string \| null	yes
rate	string \| null	yes
expires_at	string \| null	yes

Example Response

{
  "object": "subscription_charge_quote",
  "subscription_id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
  "amount": "9990000",
  "price_lock_code": null,
  "rate": null,
  "expires_at": null
}

Error Response

Error (e.g. 400)

{
  "error": {
    "type": "validation_error",
    "message": "amount must be a positive number",
    "param": "amount"
  }
}

Quote Semantics

No request body and no signature — this call moves no funds.

Token-priced plans (price_currency: null) echo the plan’s price as amount, with price_lock_code, rate, and expires_at all null. You can skip the quote entirely and sign price directly.
Fiat-priced plans on a fiat-settled business convert the fiat price to a settlement-token amount at the live rate via the settlement provider and lock that rate: pass the returned amount and price_lock_code to POST /subscriptions/:id/charge before expires_at. The provider commits to converting at that rate through ramp-off.
Fiat-priced plans on a crypto-settled business (currently ARS-priced plans only) convert the fiat price to a settlement-token amount via an Exodus-minted reference quote instead: same response shape, but price_lock_code carries a refq_-prefixed code with a 120-second TTL. A reference quote doesn’t commit anyone to a conversion, it only proves the charged amount matches what the subscriber was shown. Funds settle in the token the subscriber paid with, nothing converts, and no fiat settlement configuration is needed.

The subscription id is the on-chain bytes32 hex id — obtain it from GET /merchants/:merchantId/subscriptions, the subscription.created webhook, or the subscription_checkout.completed webhook.

The quote binds the price_lock_code to the exact amount it returned, whether it’s a provider-minted price lock or an Exodus-minted reference quote. Charging a different amount under that lock is rejected with quote_amount_mismatch; charging after expires_at is rejected with quote_expired — re-quote and re-sign.

Errors

Status	Type	Description
400	`invalid_request`	Fiat-priced plan on a fiat-settled business without a fiat settlement configuration (“Charge quote is only available for fiat settlements”).
422	`invalid_request`	`price_currency_not_quotable` — fiat-priced plan on a crypto-settled business, but `price_currency` isn’t a quotable currency (currently only ARS is).
404	`not_found`	Subscription ID does not exist or belongs to another merchant.
500	`invalid_request`	`pricing_unconfigured` — reference-quote path, the Exodus pricing server isn’t configured. Merchant-side retry won’t help.
502	`invalid_request`	Fiat-settled: the settlement provider failed to create the price lock. Crypto-settled: `rate_unavailable`, the Exodus pricing server didn’t return a usable rate. Retry either case.

Token-priced plans never fail on settlement configuration — the quote is a passthrough of price.

Charge a subscription List a merchant's subscriptions