> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payviox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Subscriptions
> List your subscriptions with the secret key. Filters: status (active, past_due, canceled, canceling = scheduled to end), search (ID, customer, email, order_id), customer (exact). Pagination with page/per_page (max 100), sorting by created_at, current_period_end, amount or unit_amount. Returns { data, total, page, per_page }
## Overview
Returns a page of your subscriptions. Use it to reconcile your own records, find a customer's subscription, or list the ones about to end.
Each item is a [Subscription object](/api/endpoints/get-subscription#the-subscription-object). All amounts are in **cents**.
## Authentication
This endpoint requires your **Secret API Key** (server-side only). See [Authentication](/api/authentication) for details.
```bash theme={null}
Authorization: Bearer sk_live_xxxxxxxxxxxx
```
## Query Parameters
Filter by status: `active`, `past_due`, `canceled`, or `canceling` — subscriptions not canceled yet but scheduled to end at `current_period_end` (`cancel_at_period_end: true`). Any other value is ignored.
`active` also returns subscriptions scheduled to end (they stay `active` until then), and `canceling` covers both `active` and `past_due` subscriptions scheduled to end.
Case-insensitive partial match on the subscription ID, customer, customer email or `order_id` (first 100 characters used).
Exact customer identifier, as passed in `customer` when creating the signup session.
Page number, starting at 1.
Results per page, up to `100`.
`created_at`, `current_period_end`, `amount` (your price) or `unit_amount` (what the customer pays). Any other value falls back to `created_at`.
`desc` or `asc`.
## Response Fields
Subscriptions of this page. See [the Subscription object](/api/endpoints/get-subscription#the-subscription-object).
Number of subscriptions matching the filters, across all pages.
Current page.
Page size actually applied.
## Example Requests
```bash cURL theme={null}
curl "https://api.payviox.com/subscriptions?status=active&customer=customer_abc123&per_page=50" \
-H "Authorization: Bearer sk_live_xxxxxxxxxxxx"
```
```javascript Node.js theme={null}
const params = new URLSearchParams({
status: 'canceling', // scheduled to end at current_period_end
sort_by: 'current_period_end',
sort_order: 'asc',
});
const response = await fetch(`https://api.payviox.com/subscriptions?${params}`, {
headers: { Authorization: `Bearer ${process.env.PAYVIOX_SECRET_KEY}` },
});
const { data, total } = await response.json();
console.log(`${total} subscriptions ending soon`);
```
```python Python theme={null}
import os
import requests
response = requests.get(
'https://api.payviox.com/subscriptions',
params={'status': 'past_due', 'page': 1, 'per_page': 100},
headers={'Authorization': f"Bearer {os.environ['PAYVIOX_SECRET_KEY']}"}
)
page = response.json()
for subscription in page['data']:
print(subscription['id'], subscription['customer'])
```
## Example Response
```json Success (200) theme={null}
{
"data": [
{
"id": "psub_8fKx2LmQp4ZrT7vW1nYc3aBd",
"status": "active",
"amount": 999,
"unit_amount": 1029,
"currency": "USD",
"interval": "month",
"interval_count": 1,
"interval_label": "every month",
"customer": "customer_abc123",
"customer_email": "john@example.com",
"order_id": "order_12345",
"items": [
{ "name": "Pro plan", "quantity": 1, "price": 999 }
],
"metadata": { "user_id": "usr_123" },
"payment_method": "credit",
"provider": "stripe",
"provider_subscription_id": "sub_1QxYz2AbCdEfGhIj",
"cycles_count": 2,
"current_period_end": "2026-12-13T10:30:00+00:00",
"cancel_at_period_end": false,
"canceled_at": null,
"canceled_by": null,
"cancel_requested_by": null,
"cancellation_reason": null,
"initial_session_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"management_url": "https://secure.payviox.com/subscription/k3Jd9QwL2xVb7NmP4tRz8YcF1sHg6UaE5oWi0qXn3BvM7ZpD",
"created_at": "2026-10-13T10:30:00+00:00"
}
],
"total": 1,
"page": 1,
"per_page": 50
}
```
```json Unauthorized (401) theme={null}
{
"error": "Unauthorized"
}
```
## OpenAPI
````yaml GET /subscriptions
openapi: 3.0.3
info:
title: Payviox API
description: Payment processing API
version: 1.0.0
servers:
- url: https://api.payviox.com
security:
- bearerAuth: []
paths:
/subscriptions:
get:
tags:
- Subscriptions
summary: List Subscriptions
description: >-
List your subscriptions, newest first by default. Requires your Secret
API Key.
operationId: listSubscriptions
parameters:
- name: status
in: query
required: false
schema:
type: string
enum:
- active
- past_due
- canceled
- canceling
description: >-
Filter by status. `canceling` = not canceled yet but scheduled to
end at `current_period_end` (`cancel_at_period_end: true`). Other
values are ignored.
- name: search
in: query
required: false
schema:
type: string
maxLength: 100
description: >-
Case-insensitive partial match on subscription ID, customer,
customer email or order_id
- name: customer
in: query
required: false
schema:
type: string
description: >-
Exact customer identifier, as passed when creating the signup
session
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
- name: per_page
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: Results per page (capped at 100)
- name: sort_by
in: query
required: false
schema:
type: string
enum:
- created_at
- current_period_end
- amount
- unit_amount
default: created_at
- name: sort_order
in: query
required: false
schema:
type: string
enum:
- desc
- asc
default: desc
responses:
'200':
description: Subscriptions retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionList'
'401':
description: Unauthorized (missing or invalid Secret API Key)
components:
schemas:
SubscriptionList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Subscription'
total:
type: integer
description: Number of subscriptions matching the filters
page:
type: integer
per_page:
type: integer
Subscription:
type: object
required:
- id
- status
- amount
- unit_amount
- currency
- interval
- interval_count
- interval_label
- order_id
- cycles_count
- cancel_at_period_end
- initial_session_id
- created_at
properties:
id:
type: string
description: Payviox subscription ID (`psub_` prefix)
status:
type: string
enum:
- active
- past_due
- canceled
description: >-
`active`: paid up, renews automatically (also while a cancellation
is scheduled, see `cancel_at_period_end`). `past_due`: the last
renewal charge failed and Stripe is retrying it. `canceled`: ended,
no further charges.
amount:
type: integer
description: Your price per period in cents — the `amount` of the signup session
unit_amount:
type: integer
description: >-
Amount charged to the customer at each renewal, in cents. Includes
the fees added for the customer at checkout, but not one-time add-on
fees (such as fraud screening) charged on the first payment only, so
it can be lower than the first charge.
currency:
type: string
description: Always `USD`
interval:
type: string
enum:
- day
- week
- month
- year
interval_count:
type: integer
interval_label:
type: string
description: Human-readable period, e.g. `every month`, `every 3 months`
customer:
type: string
nullable: true
description: Customer identifier from the signup session
customer_email:
type: string
nullable: true
description: Customer email, from the signup session or entered at checkout
order_id:
type: string
description: '`order_id` of the signup session. Renewals use `{order_id}-{cycle}`'
items:
type: array
items:
type: object
additionalProperties: true
description: Items of the signup session (one period)
metadata:
type: object
additionalProperties: true
description: Metadata of the signup session
payment_method:
type: string
enum:
- credit
- apple_pay
- google_pay
description: Method the customer subscribed with (read with `provider`)
provider:
type: string
description: Provider that charges the renewals (`stripe`)
provider_subscription_id:
type: string
nullable: true
description: >-
ID of the subscription on your Stripe account (`sub_...`). `null`
until Payviox has created it, usually within a minute of the first
payment.
cycles_count:
type: integer
description: >-
Billing cycles started so far, signup included (1 = signup only). A
renewal whose charge failed counts too.
current_period_end:
type: string
format: date-time
nullable: true
description: >-
End of the current billing period: date of the next renewal charge,
or the date a scheduled cancellation takes effect
cancel_at_period_end:
type: boolean
description: >-
`true` when the subscription is scheduled to end at
`current_period_end`
canceled_at:
type: string
format: date-time
nullable: true
description: When the subscription ended (`null` while not canceled)
canceled_by:
type: string
nullable: true
enum:
- api
- manager
- admin
- payer
- provider
- system
- null
description: >-
Who ended it: `api` (your backend), `manager` (your dashboard),
`admin` (Payviox support), `payer` (the customer, from the
management link), `provider` (on Stripe, e.g. after failed retries
or a cancellation in the Stripe dashboard), `system` (Payviox, e.g.
signup payment refunded or `setup_failed`). `null` until the
subscription is canceled.
cancel_requested_by:
type: string
nullable: true
enum:
- payer
- api
- manager
- admin
- system
- null
description: >-
Who scheduled the end-of-period cancellation: `payer` (the
customer), `api`, `manager` (your dashboard), `admin` (Payviox
support) or `system`. `null` when no cancellation is scheduled, or
when it was scheduled from your Stripe dashboard. Only the same side
can resume it: you (`api`, `manager`, `null`), the customer
(`payer`) or Payviox (`admin`, `system`).
cancellation_reason:
type: string
nullable: true
description: >-
Set as soon as a cancellation is requested or scheduled:
`requested_by_merchant`, `requested_by_customer`,
`initial_payment_refunded`, `admin` (canceled by Payviox support),
`setup_failed:`, or a Stripe reason such as `payment_failed`,
`cancellation_requested`, `provider` or `provider_deleted`. Treat
unknown values as informational.
initial_session_id:
type: string
description: Session ID of the signup payment
management_url:
type: string
nullable: true
description: >-
Customer self-service page (view, cancel at period end, undo). Share
it with your customer, e.g. in your confirmation email.
created_at:
type: string
format: date-time
example:
id: psub_8fKx2LmQp4ZrT7vW1nYc3aBd
status: active
amount: 999
unit_amount: 1029
currency: USD
interval: month
interval_count: 1
interval_label: every month
customer: customer_abc123
customer_email: john@example.com
order_id: order_12345
items:
- name: Pro plan
quantity: 1
price: 999
metadata:
user_id: usr_123
payment_method: credit
provider: stripe
provider_subscription_id: sub_1QxYz2AbCdEfGhIj
cycles_count: 2
current_period_end: '2026-12-13T10:30:00+00:00'
cancel_at_period_end: false
canceled_at: null
canceled_by: null
cancel_requested_by: null
cancellation_reason: null
initial_session_id: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
management_url: >-
https://secure.payviox.com/subscription/k3Jd9QwL2xVb7NmP4tRz8YcF1sHg6UaE5oWi0qXn3BvM7ZpD
created_at: '2026-10-13T10:30:00+00:00'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.