Retrieve a paginated list of subscriptions for your business.

You can filter subscriptions by customer email, subscription code, plan code, active state, and creation date range.

-H "x-api-key: your_secret_key".

{{host}}/v1/subscriptions

Query Parameters

Status	Data Type	Description
order	enum	allowed values are ASC or DESC
page	integer	Specify exactly what page you want to retrieve. If not specified we use a default value of 1
limit	integer	Specify how many records you want to retrieve per page. maximum record per page is 100
query	string	Filter by customer email or subscription code or Plan code
status	boolean	Filter by active entitlement state. true returns active subscriptions, false returns inactive subscriptions.
startDate	date	Filter date range by date of which subscription was created eg. 2017-05-16T00:30:13+01:00
endDate	date	Filter date range by date of which subscription was created eg. 2017-05-16T00:30:13+01:00

Sample Request

GET /v1/subscriptions?page=1&limit=20&order=DESC&[email protected]

Sample Response

{
  "page": 1,
  "limit": 20,
  "total": 1,
  "pageCount": 1,
  "hasPreviousPage": false,
  "hasNextPage": false,
  "data": [
    {
      "id": "sub_uuid",
      "code": "SUB_xxx",
      "status": "ACTIVE",
      "isActive": true,
      "paymentMethod": "card",
      "startDate": "2026-06-01T00:00:00.000Z",
      "previousPaymentDate": "2026-06-01T00:00:00.000Z",
      "nextPaymentDate": "2026-07-01T00:00:00.000Z",
      "retryCount": 0,
      "maxRetryCount": 3,
      "gracePeriodDays": 3,
      "invoiceLimit": 12,
      "invoicesPaid": 1,
      "customer": {
        "id": "customer_uuid",
        "email": "[email protected]"
      },
      "plan": {
        "id": "plan_uuid",
        "code": "PLN_xxx",
        "name": "Pro Monthly",
        "interval": "monthly",
        "amount": 5000,
        "localCurrency": "NGN"
      }
    }
  ]
}

Notes

Results are scoped to the authenticated business.
Test keys return test-mode subscriptions; live keys return live-mode subscriptions.
Use status=true only when you want subscriptions where isActive is true.
For product access checks, use both status and isActive.

Grant Access When

status = ACTIVE
isActive = true

Do Not Grant Access When

status = PAST_DUE
status = CANCELLED
status = COMPLETED

For NON_RENEWING, access may continue until the current paid period ends.