Get Subscription

GET/subscriptions/:id

Description

Retrieve the current state of an on-chain subscription, including the on-chain subscriber address, the contract address on the chosen chain, rolling state used for charge scheduling (next_charge_at, charge_nonce), and per-cycle budget tracking (budget, spent_this_period, remaining_budget).

Headers

Header	Description	Required
Authorization	Bearer token with your API key	yes

Path Parameters

Name	Type	Description	Required
id	string	The on-chain subscription ID (bytes32 hex, e.g. `0x9f3a...`). Obtain it from `GET /subscriptions`, the `subscription.created` webhook, or the `subscription_checkout.completed` webhook.	yes

Example Request

const response = await fetch('https://checkout-api.exodus-int.com/subscriptions/0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a', {
  headers: {
    Authorization: 'Bearer sk_live_xxxxxxxxxxxxxxxx',
  },
});

Response

SUCCESSFUL RESPONSE

{
  "object": "subscription",
  "id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
  "status": "active",
  "subscriber": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
  "asset": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "token_symbol": "USDC",
  "token_decimals": 6,
  "cap_amount": "120000000",
  "charge_amount": "9990000",
  "period_duration": 2592000,
  "budget": "300000000",
  "spent_this_period": "29970000",
  "remaining_budget": "270030000",
  "last_charged_at": "2026-04-19T12:02:18Z",
  "next_charge_at": "2026-05-19T12:02:18Z",
  "charge_nonce": 3,
  "paused": false,
  "created_at": "2026-02-19T12:02:18Z",
  "subscription_manager_address": "0xa1b2c3d4e5f6789012345678901234567890abcd",
  "chain": "eip155:1",
  "cancel_url": "https://merchant.com/cancelled",
  "subscription_checkout_id": "schk_1234567890abcdef",
  "flagged": false
}

Field reference

Field	Description
`id`	The on-chain `subscriptionId` (bytes32 hex). This is the subscription’s `id`. Pass it to all signing helpers and as the `:id` path param on every action endpoint.
`asset`	CAIP-19 asset id — `<chain>/<namespace>:<reference>` (e.g. `eip155:1/erc20:0xa0b8…`). `chain` is the CAIP-2 prefix, `namespace` is `erc20` (EVM) or `token` (Solana SPL), `reference` is the token contract / mint. EVM references render lowercase regardless of stored casing. The chain comes from the subscription’s `subscription_manager`, not a separate field on the asset.
`token_symbol`	Display symbol for the asset (e.g. `USDC`).
`token_decimals`	Token decimal precision (number).
`subscription_manager_address`	Contract address on `chain`. Pass to `signCharge` and `signCancelSubscription`.
`chain`	CAIP-2 identifier (e.g. `eip155:1`). Pass to all signing helpers.
`flagged`	Compliance screening flag. When `true`, the API blocks charges on this subscription.
`charge_amount`	The fixed per-cycle amount (settlement-token smallest units). Pass to `signCharge`.
`budget`	Subscriber-signed ceiling on the total charged within the current tumbling window (settlement-token smallest units). `cap_amount` bounds each individual `charge`; `budget` bounds their per-window sum. Set by the subscriber at subscribe, lowered anytime via the hosted `updateBudget` flow — merchant-immutable. `null` on subscriptions predating the budget model.
`spent_this_period`	Running total already charged inside the current window. Resets to `0` when the window rolls over to the next `period_duration`. `null` when `budget` is `null`.
`remaining_budget`	`budget - spent_this_period` for the current window — headroom left before the next window opens. `null` when `budget` is `null`.
`charge_nonce`	Pre-increment nonce consumed by `charge`. Pass to the next call to `signCharge`. Advances by 1 after every on-chain charge call (succeeded or failed).
`paused`	In-band sub-state of `active`. `true` after a subscriber-fault revert (`InsufficientBalance`, `InsufficientAllowance`) or any receipt revert; the scheduler skips charges while `true`. Cleared on the next successful charge.
`last_charged_at`	Block timestamp of the most recent successful cycle charge. `null` until first charge confirms.
`next_charge_at`	Block timestamp at which the next cycle charge becomes eligible. Calls to `charge` before this revert with `PeriodNotElapsed`.

The subscription stores a fixed charge_amount (settlement-token smallest units), charged each cycle. Pass it to signCharge with the current charge_nonce. Subscriptions are token-denominated today; FIAT-denominated pricing is coming soon.

Per-cycle budget

budget caps the total a merchant may charge within one billing window, so a single subscription can absorb multiple metered pulls (usage drawdown, threshold reloads, mid-cycle add-ons) rather than one fixed charge.

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 the merchant-movable last_charged_at.
cap_amount bounds each individual charge; budget bounds the per-window sum.
remaining_budget = budget - spent_this_period; spent_this_period resets to 0 at each window boundary.

See Budget Semantics for the full model.

Errors

Status	Code	Description
404	`not_found`	Subscription ID does not exist.
403	`forbidden`	Subscription belongs to another merchant.