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, and rolling state used for charge scheduling (next_charge_at, charge_nonce).

Headers

Header	Description	Required
Authorization	Bearer token with your API key	yes

Path Parameters

Name	Type	Description	Required
id	string	The subscription ID (e.g. `sub_abc123def456`).	yes

Example Request

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

Response

SUCCESSFUL RESPONSE

{
  "object": "subscription",
  "id": "sub_abc123def456",
  "status": "active",
  "subscription_checkout_id": "schk_1234567890abcdef",
  "onchain_id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
  "subscriber": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
  "external_customer_id": "cus_42",
  "chain": "eip155:1",
  "subscription_manager_address": "0xA1B2C3D4E5F6789012345678901234567890ABCD",
  "token_symbol": "USDC",
  "token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "charge_amount": "9990000",
  "cap_amount": "120000000",
  "period_duration": 2592000,
  "charge_nonce": 3,
  "charge_amount_update_nonce": 0,
  "cancel_at_period_end": false,
  "last_charged_at": "2026-04-19T12:02:18Z",
  "next_charge_at": "2026-05-19T12:02:18Z",
  "metadata": { "external_plan_ref": "pro_monthly" },
  "created_at": "2026-02-19T12:02:18Z",
  "cancelled_at": null
}

Field reference

Field	Description
`onchain_id`	The on-chain `subscriptionId` (bytes32 hex). Pass to all signing helpers and signed-request bodies.
`subscription_manager_address`	Contract address on `chain`. Pass to `signCharge`, `signChargeAdHoc`, `signCancelSubscription`, `signUpdateChargeAmount`.
`chain`	CAIP-2 identifier (e.g. `eip155:1`). Pass to all signing helpers.
`charge_nonce`	Pre-increment nonce shared by `charge` and `charge_adhoc`. Pass to the next call to `signCharge` or `signChargeAdHoc`. Advances by 1 after every on-chain charge call (succeeded or failed).
`charge_amount_update_nonce`	Pre-increment nonce for `updateChargeAmount`. Pass to `signUpdateChargeAmount`.
`cancel_at_period_end`	Off-chain honor flag set by a `cancel` call with `cancel_at_period_end=true`. The merchant scheduler MUST honor it.
`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`.

Errors

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