Skip to main content
GET
List Subscriptions
List items are a summary, not the full subscriptionEach item carries the fields needed to render a grid. Everything else — availability, retries, metadata, trial_period, payments, current_period_start/current_period_end, pending_plan_change, billing_phases and the rest of The Subscription Object — is only returned by Retrieve Subscription. Call it per item when you need any of them.
merchant_reference is not a filter on this endpointSending it has no effect: the parameter is ignored and the full, unfiltered page is returned. To look a subscription up by merchant reference, keep the id you received when you created it, or page through this endpoint and match client-side.

​
Scope and ordering

The list is always scoped to the single account in the x-account-code header — there is no cross-account variant. Results are ordered by created_at descending, so a subscription created while you page can shift items across page boundaries. For a stable sweep, filter with created_at_to fixed at the moment you started. Filters are combinable and all optional; each one narrows the result set further. With none set, subscriptions in every status are returned, including CANCELED and COMPLETED ones.

Authorizations

​
public-api-key
string
header
default:<Your public-api-key>
required
​
private-secret-key
string
header
default:<Your private-secret-key>
required

Headers

​
x-account-code
string
required

The account_id found in your Yuno Dashboard (UUID). Required — the list is always scoped to a single account. Omitting it returns 400 INVALID_PARAMETERS ("x-account-code header is required.").

Query Parameters

​
customer_id
string

Filter by the customer that owns the subscription (customer_payer.id, UUID). A value that isn't a UUID returns 400 BAD_REQUEST ("Invalid customer_id.").

Example:

"3t04911d-5df9-429e-8488-ad41abea1a2c"

​
status
string

Filter by status. Accepts several values separated by commas, matching any of them — ACTIVE,PAUSED. Values must be spelled exactly as in Subscription statuses; an unknown one returns 400 BAD_REQUEST ("Invalid status: FOO.").

Example:

"ACTIVE,PAUSED"

​
plan_id
string

Filter by the plan the subscription is linked to (UUID). A plan with no subscribers — or one that doesn't exist — returns an empty list, not an error. A value that isn't a UUID returns 400 BAD_REQUEST ("Invalid plan_id.").

Example:

"00000000-0000-4000-8000-000000000001"

​
created_at_from
string

Only return subscriptions created at or after this instant (ISO 8601 with offset, inclusive). A value that doesn't parse returns 400 BAD_REQUEST ("Invalid created_at_from.").

Example:

"2024-01-01T00:00:00Z"

​
created_at_to
string

Only return subscriptions created at or before this instant (ISO 8601 with offset, inclusive). A value that doesn't parse returns 400 BAD_REQUEST ("Invalid created_at_to.").

Example:

"2024-12-31T23:59:59Z"

​
payment_method_type
string

Filter by the subscription's payment method type, for example CARD.

Example:

"CARD"

​
page
integer
default:1

1-indexed page number. Must be >= 1, else 400 BAD_REQUEST ("The page must be greater than or equal to 1.").

Required range: x >= 1
​
size
integer
default:20

Page size. Must be between 1 and 100 inclusive, else 400 BAD_REQUEST ("The size must be greater than or equal to 1." if too low, "The size must be at most 100." if too high).

Required range: 1 <= x <= 100

Response

200

​
items
object[]
​
pagination
object