Quote the next charge for a subscription

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. Fiat-priced plans may pass an optional amount in fiat minor units to quote an ad-hoc charge; omitted, the stored plan price is quoted. Every fiat quote is checked against the subscription's cap_amount and the remaining per-window budget at quote time.

Headers

Path Parameters

Request Body

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',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amount": "3490000"
  }),
});

Responses

Response body

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 signature — this call moves no funds. The body is optional: fiat-priced plans may pass amount, in minor units of the plan’s price_currency, to quote an ad-hoc charge instead of the stored price. Omit it to quote the plan price. Token-priced plans take no body.

• 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.

Variable Charges

A fiat-priced plan doesn’t have to charge price every cycle. Pass the amount you want to charge this cycle as amount in the quote body, then sign and submit the token amount the quote returns. Each quote is bound to the amount it converted, so a new amount always means a new quote.

{ "amount": "349000" }

{
  "object": "subscription_charge_quote",
  "subscription_id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
  "amount": "2406897",
  "price_lock_code": "refq_9f3a2b7c4d1e8a05b6c7d2f1",
  "rate": "1450",
  "expires_at": "2026-09-10T15:04:12Z"
}

import { CheckoutSigner } from '@exodus/checkout-signer';
 
const headers = { Authorization: `Bearer ${process.env.API_KEY}` };
const signer = new CheckoutSigner();
 
// The subscription's on-chain id, from the subscription_checkout.completed webhook
const subscriptionId = '0x9f3a2b...';
 
const sub = await fetch(`https://checkout-api.exodus-int.com/subscriptions/${subscriptionId}`, {
  headers,
}).then((r) => r.json());
 
// Quote this cycle's amount in fiat minor units — ARS 3,490.00 here
const quote = await fetch(`https://checkout-api.exodus-int.com/subscriptions/${sub.id}/charge-quote`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: '349000' }),
}).then((r) => r.json());
 
// Sign the quoted token amount, not the fiat amount
const { signature } = signer.signCharge(sub, { amount: BigInt(quote.amount) });
 
// Submit the same token amount with the quote code before expires_at
await fetch(`https://checkout-api.exodus-int.com/subscriptions/${sub.id}/charge`, {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json', 'X-Signature': signature },
  body: JSON.stringify({ amount: quote.amount, price_lock_code: quote.price_lock_code }),
});

Every quote is checked against the subscriber’s ceilings before any funds move, ad-hoc, stored-price and token-priced alike. The quote rejects with amount_exceeds_cap when the token amount it would return is above cap_amount, so a stored-price quote whose conversion drifts over the cap is rejected too. It rejects with budget_exceeded when that amount would push spent_this_period past budget, or when the window is already fully spent. The charge re-checks both, since spend can accrue between quote and charge. Both ceilings are fixed by the subscriber at subscribe time and the merchant can never raise them, so a plan that expects to reprice needs cap and budget headroom declared on the subscription checkout up front.

Quote errors on charge

A charge that fails after the quote was accepted (insufficient balance, an on-chain revert, any error past the binding checks) releases the quote. The same price_lock_code stays valid until expires_at, so a retry can resubmit the same amount, price_lock_code, and signature without re-quoting. Only the codes above require a fresh quote; if a retry comes back with quote_already_used, treat it the same way.

Errors on this endpoint

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