Plans

List plans by merchant

GET /v0/plans/:merchant

Returns all plans for the merchant across all modules they own.

Auth: API key or SIWE session

Path parameters:

Parameter	Type	Description
merchant	string	Merchant wallet address (0x…)

Query parameters:

Parameter	Type	Required	Description
chain_id	number	No	Chain ID to filter. Defaults to the indexer's configured chain.

Response fields:

Field	Type	Description
plan_id_on_chain	string	On-chain plan ID
module_address	string	SubscriptionModule contract address
merchant_address	string	Merchant wallet address
token_address	string	Payment token contract address
price	string	Amount charged per billing cycle, in token base units
token_decimals	number | null	Token decimal places (e.g. 6 for USDC)
token_symbol	string | null	Token symbol (e.g. "USDC")
billing_interval	string	Billing interval in seconds
grant_amount	string	Credit grant amount (for credit modules)
name	string | null	Human-readable plan name
description	string | null	Plan description
active	boolean	Whether the plan is accepting new subscribers
created_at	string	ISO 8601 creation timestamp

info

price and billing_interval are returned as strings because they are bigint values on-chain. Parse with BigInt() in JavaScript or handle as strings to avoid precision loss.

Example request:

const res = await fetch(
  'https://api.amser.io/v0/plans/0xMerchantAddress',
  {
    headers: {
      'Authorization': `Bearer ${process.env.AMSER_API_KEY}`,
    },
  }
);
const plans = await res.json();

Example response:

[
  {
    "plan_id_on_chain": "1",
    "module_address": "0xabcdef1234567890abcdef1234567890abcdef12",
    "merchant_address": "0x2222222222222222222222222222222222222222",
    "token_address": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
    "price": "10000000",
    "token_decimals": 6,
    "token_symbol": "USDC",
    "billing_interval": "2592000",
    "grant_amount": "0",
    "name": "Pro Plan",
    "description": "Monthly pro subscription",
    "active": true,
    "created_at": "2026-01-15T12:00:00.000Z"
  }
]

In this example, the price of "10000000" with token_decimals: 6 represents 10 USDC. The billing interval of "2592000" seconds is 30 days.

---

Get plan by ID

GET /v0/plans/:merchant/:id

Returns a single plan by its on-chain plan ID.

Auth: API key or SIWE session

Path parameters:

Parameter	Type	Description
merchant	string	Merchant wallet address (0x…)
id	string	On-chain plan ID

The response shape is identical to a single element from the list endpoint.

---

List plans by module

GET /v0/modules/:moduleAddress/plans

Returns all plans for a specific module address. This is the correct endpoint for frontends building a public pricing page — it does not require authentication.

Auth: None required (public endpoint — plan data is public)

Path parameters:

Parameter	Type	Description
moduleAddress	string	SubscriptionModule contract address (0x…)

Query parameters:

Parameter	Type	Required	Description
chain_id	number	No	Chain ID to filter

The response shape is the same array format as the merchant list endpoint.

Example request:

const res = await fetch(
  'https://api.amser.io/v0/modules/0xModuleAddress/plans'
);
const plans = await res.json();

Related

• Subscriptions — Subscription state and authorization checks
• Activity — Payment history and failure tracking
• Merchant Integration — End-to-end setup including plan creation