Skip to main content
GET
List subscriptions

Authorizations

X-Suby-Api-Key
string
header
required

Secret API key. sk_live_… (production) or sk_sandbox_… (sandbox).

Query Parameters

limit
integer
default:20

Page size (1–100).

Required range: 1 <= x <= 100
cursor
string

Opaque pagination cursor from a previous pagination.nextCursor.

customerId
string
Example:

"cus_abc123"

productId
string
Example:

"pro_abc123"

status
enum<string>
Available options:
INCOMPLETE,
TRIALING,
PENDING_3DS,
PENDING_REDIRECT,
ACTIVE,
PAST_DUE,
PAUSED,
CANCELED,
EXPIRED
expand
string

Comma-separated relations to join onto the subscription. Each is absent unless asked for, so a caller reconciling renewals by id pays for none of them. Every value names the field it fills.

  • product · the plan behind the subscription — name, description, image, its CURRENT price and cadence, its trial and agreed cycle count, and its status (an ARCHIVED plan keeps billing the people already on it).
  • customer · the buyer's id and email.
  • nextCharge · what the next renewal will take and when, sized the way the renewal itself sizes it (the agreed price through this subscription's own VAT context). null when nothing further is scheduled.
  • lifetime · settled-charge totals over the whole subscription, aggregated server-side rather than folded from a page of charges.
  • renewalAttempts · every renewal attempt, newest cycle first, with the issuer's own decline code and the payment behind it.
  • accesses · the entitlements this subscription granted and whether the customer ever claimed them.

product and customer are the only two the LIST accepts. The other four are per-subscription computations, and running them for every row of a page is four more round trips per subscription — so the list refuses them with 422 rather than accepting the word and returning nothing, which would read as "this subscription has none" on every row. Retrieve one subscription to get them.

An unrecognised value is refused with 422 rather than ignored.

Example:

"product,customer,nextCharge"

Response

Subscriptions retrieved

success
boolean
required
Example:

true

data
object
required

Endpoint-specific payload.

message
string