Skip to main content
POST
/
subscriptions
/
list
curl --request POST \
  --url https://development.knotapi.com/subscriptions/list \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "external_user_id": "abc"
}
'
{
  "subscriptions": [
    {
      "id": "13da3c28-a068-4642-9ce2-b730cfda5f5f",
      "external_id": "a9x7bq2lmw5p",
      "name": "Disney+, Hulu Bundle Premium",
      "description": "Ad-free streaming with Disney+ and Hulu",
      "merchant": {
        "id": 18,
        "name": "Hulu",
        "category": "Streaming",
        "logo": "https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png"
      },
      "status": "ACTIVE",
      "billing_cycle": "MONTHLY",
      "next_billing_date": "2026-02-10",
      "last_billing_date": "2026-01-10",
      "start_date": "2025-06-15",
      "expiration_date": null,
      "cancel_instructions": "You can cancel your subscription at any time from your account settings. Your cancellation will take effect at the end of your current billing period.",
      "is_paid": true,
      "is_family_plan": false,
      "is_cancellable": true,
      "price": {
        "total": "11.99",
        "currency": "USD"
      }
    },
    {
      "id": "7a2e9f14-b532-48d1-ae73-c9f2d8e61b4a",
      "external_id": "sp_sub_8x2k4m",
      "name": "Premium Individual",
      "description": "Ad-free music streaming for one account",
      "merchant": {
        "id": 13,
        "name": "Spotify",
        "category": "Streaming",
        "logo": "https://knot.imgix.net/merchants/spotify-logo.png"
      },
      "status": "ACTIVE",
      "billing_cycle": "MONTHLY",
      "next_billing_date": "2026-03-10",
      "last_billing_date": "2026-02-10",
      "start_date": "2024-09-01",
      "expiration_date": null,
      "cancel_instructions": "You can cancel your subscription at any time from your account settings.",
      "is_paid": true,
      "is_family_plan": false,
      "is_cancellable": true,
      "price": {
        "total": "12.99",
        "currency": "USD"
      }
    }
  ],
  "next_cursor": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "limit": 100
}

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password. Use your client_id as the username and your secret as the password value.

Body

application/json

The input parameters required for listing subscriptions.

​
external_user_id
string
required

Your unique identifier for the user.

Example:

"abc"

​
merchant_id
integer

The unique ID of a merchant. When provided, only subscriptions for that merchant's linked account are returned.

Example:

18

​
status
enum<string>

When provided, only subscriptions with this status are returned.

Available options:
ACTIVE,
ACTIVE_CANCELLATION,
ACTIVE_PLAN_CHANGE,
ACTIVE_SUSPENSION,
PENDING,
PAUSED,
CANCELLED,
SUSPENDED,
UNRECOGNIZED
Example:

"ACTIVE"

​
is_paid
boolean

When provided, only subscriptions matching this paid/free status are returned.

Example:

true

​
is_family_plan
boolean

When provided, only subscriptions matching this family-plan status are returned.

Example:

false

​
is_cancellable
boolean

When provided, only subscriptions matching this cancellable status are returned.

Example:

true

​
cursor
string

Cursor token pointing to the last subscription retrieved. The /subscriptions/list endpoint uses cursor-based pagination to track which subscriptions have already been seen, minimizing data redundancy.

On the first call, the endpoint returns all subscriptions paginated. In subsequent calls, only subscriptions after the next cursor are provided.

Example:

"eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"

​
limit
integer
default:100

Maximum number of subscriptions to retrieve (min: 1, max: 100).

Example:

100

Response

Successful request.

​
subscriptions
object[]
​
next_cursor
string | null

Cursor token for the next page of subscriptions. null when there are no more subscriptions to retrieve.

​
limit
integer

Number of subscriptions returned based on the limit provided.

Example:

100