Subscriptions

A Subscription is the on-chain record of an active recurring stablecoin agreement. It is materialized by the indexer when a customer completes a subscription checkout and the first subscribeAndCharge transaction confirms on-chain.

Creation

Subscriptions are not created via a direct API call. To start one:

1. Call POST /subscription-checkouts to create an intent.
2. Redirect the customer to the returned checkout_url.
3. The customer signs subscribeAndCharge from their wallet.
4. The indexer materializes the Subscription and dispatches the subscription.created and subscription.charge_succeeded webhooks.

Pricing

A plan’s recurring price is price, declared on the originating subscription checkout. Every plan created today sets price_currency, and price is an integer in hundredths of that currency unit ("150000" is 1,500.00 ARS). Subscriptions predating fiat-only pricing can still carry price_currency: null, with price in the settlement token’s smallest units instead; they keep charging on those terms. The per-charge amount is dynamic: at each charge the merchant chooses the amount, signs it with signCharge, and submits it in the request body — bounded by cap_amount per call and by the per-window budget. Simple plans pass the subscription’s price; metered billing may charge several times within one window.

Fiat-priced plans convert the fiat price to a token amount at the live rate via POST /subscriptions/:id/charge-quote, then pass the quoted amount and quote code to charge. The quote mechanism depends on settlement type: a fiat-settled business gets a settlement-provider-minted price lock (price_lock_code), redeemed at ramp-off after the charge; a crypto-settled business gets an Exodus-minted reference quote (refq_ code, 120s TTL) that only proves the charged amount matched what the subscriber was shown — funds stay in stablecoin, nothing converts, no settlement configuration needed.

Merchant-Driven Actions

After creation, the merchant drives all subsequent state changes via the API. Each action is a signed request: the merchant uses @exodus/checkout-signer to produce a signature, posts it to the Exodus API, and Exodus submits the on-chain transaction.

Raising the cap is subscriber-authorized — the subscriber calls updateCap on-chain (observed by the indexer as the subscription.cap_updated webhook). A merchant key can only charge within the subscriber’s cap and budget, and cancel; it can never raise either ceiling.

Customer-Initiated Cancel

Customers cancel their own subscriptions from a hosted page:

https://checkout.exodus-int.com/cancel/:subscription_id

The page reads the on-chain subscription_id, requires the customer’s subscribing wallet to be connected, and lets them sign cancel(subscriptionId) directly. Surface this URL in your customer account UI for self-service cancellation. The customer pays the on-chain gas.

If the customer has lost access to their subscribing wallet, the page surfaces a “Lost wallet?” link. Exodus does not perform key recovery — recovery routes back to the merchant via the intent’s cancel_url, and the merchant cancels via POST /subscriptions/:id/cancel.

Statuses

Paused (in-band sub-state of active)

Subscriptions also carry a separate paused: boolean field — an in-band brake on the active state, not a status enum value. Recurring charges are merchant-driven (POST /subscriptions/:id/charge); Exodus does not auto-charge. paused is a dunning signal for your scheduler to skip or defer charges until the subscriber’s payment issue is resolved.

paused is visible on every GET /subscriptions/:id and GET /merchants/:merchantId/subscriptions response. Surface it in your dunning UI alongside the failed-charge ledger.

Cap Semantics

Every subscription has a cap_amount — the on-chain maximum the contract will allow per call. The merchant declares it as the intent’s cap in fiat (defaulting to budget when omitted); at subscribe time the quote converts it to the settlement token’s smallest units at the same rate as the charge amount, and the subscriber signs that converted figure. cap_amount is therefore always a token amount, fixed at subscribe and unaffected by later rate moves. After that it cannot be raised by the merchant — only the subscriber can change it, via the on-chain updateCap.

• charge enforces amount <= cap_amount per call. The API preflight rejects an over-cap charge with amount_exceeds_cap; one that races past the preflight reverts on-chain with ChargeAmountExceedsCap. Either way nothing is pulled until the subscriber raises the cap.
• The cap is the subscriber’s security dial: a per-charge amount past it is rejected rather than silently pulling more.

A merchant who wants headroom for future price increases should declare a generous cap (a multiple of price) at intent creation — its converted value is what the subscriber signs, and it cannot be raised afterwards. Headroom also absorbs adverse rate moves: the fiat price converts at the live rate on every charge, while cap_amount stays pinned at the rate that applied when the subscriber signed.

Budget Semantics

Beyond the per-call cap_amount, every subscription carries a per-cycle budget — the maximum a merchant may charge in total within one billing window. This is what lets one subscription support multiple charges per cycle (metered usage, threshold reloads, mid-cycle add-ons) instead of a single fixed pull. GET /subscriptions/:id surfaces the ceiling and its running totals as budget, spent_this_period, and remaining_budget.

• The window is tumbling, anchored to the subscription’s immutable on-chain start (startedAt): currentWindow = floor((now - startedAt) / period_duration) (integer division — same as the contract). It is never anchored to last_charged_at — re-anchoring to the merchant-movable last-charge time would let a merchant collapse two windows and pull 2 x budget on demand.
• cap_amount bounds each individual charge; budget bounds the sum of charges within a window. Both ceilings are enforced: a charge reverts if its amount exceeds cap_amount, or if it would push spent_this_period past budget.
• remaining_budget = budget - spent_this_period. spent_this_period resets to 0 at each window boundary.
• budget is subscriber-sovereign: the merchant declares it as the intent’s budget in fiat, the quote converts it to token units at the same rate as cap_amount, the customer signs that converted figure at subscribe, and can lower it anytime via the on-chain updateBudget (observed as the subscription.budget_updated webhook). The merchant can never raise it — same security dial as cap_amount.

The residual exposure is a single-boundary straddle: at most 2 x budget across one real window boundary, once per period_duration — irreducible for any tumbling window. A compromised merchant key is bounded by budget x periods-until-cancel, with cap_amount bounding any single pull and subscriber cancel / updateBudget as the escape.

Subscription Charges

A SubscriptionCharge is the per-attempt record of a charge against a subscription. Both succeeded and failed charges are persisted — failed attempts include a typed failure_reason for dunning, analytics, and CSV exports.

The same charge can be written by two paths — the API write path (POST /subscriptions/:id/charge persists the receipt synchronously) and the indexer backup path (the indexer ingests the on-chain SubscriptionCharged event). Rows are deduplicated by tx_hash. After receiving a subscription.charge_succeeded or subscription.charge_failed webhook, an immediate GET /merchants/:id/charges is guaranteed to include the new row.

Failed Charges

The Exodus API persists every charge that reached the chain boundary — succeeded, receipt-reverted, or rejected by the contract simulation (persisted with tx_hash: null) — in the subscription charges ledger above. API-side preflight rejections (subscription_cancelled, amount_exceeds_cap, budget_exceeded, signature failures) return a 4xx response and are not persisted. Common typed contract errors:

Succeeded charges fire the subscription.charge_succeeded webhook; failed charge attempts — simulation rejections included — fire subscription.charge_failed. Failed attempts are also visible via GET /merchants/:id/charges with status=failed for dunning and analytics.

Available Endpoints

• Retrieve a subscription
• List a merchant’s subscriptions
• Charge a subscription for the current period
• Quote the next charge for a subscription
• Cancel a subscription
• List a merchant’s subscription charges
• List a merchant’s deployed subscription managers

See also: Subscription Checkouts for the intent that creates a subscription.