KNknotapi

List Subscriptions

Changed on

List a user's subscriptions using cursor-based pagination.

post/subscriptions/list

Request

  • Base URL
    https://development.knotapi.com
  • URL
    https://development.knotapi.com/subscriptions/list
  • Auth
    HTTP basic

Request body

external_user_idstring required

Your unique identifier for the user.

merchant_idinteger

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

status'ACTIVE' | 'ACTIVE_CANCELLATION' | 'ACTIVE_PLAN_CHANGE' | 'ACTIVE_SUSPENSION' | 'PENDING' | 'PAUSED' | 'CANCELLED' | 'SUSPENDED' | 'UNRECOGNIZED'

When provided, only subscriptions with this status are returned.

is_paidboolean

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

is_family_planboolean

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

is_cancellableboolean

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

cursorstring

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.

limitinteger

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

Example request

{
  "external_user_id": "abc",
  "merchant_id": 18,
  "status": "ACTIVE",
  "is_paid": true,
  "is_cancellable": true,
  "cursor": "eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
  "limit": 100
}

Response

Successful request.

next_cursorstring nullable

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

limitinteger

Number of subscriptions returned based on the limit provided.

Example response

{
  "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": "RECURRING_MONTHLY",
      "next_billing_date": "2026-02-10",
      "last_billing_date": "2026-01-10",
      "start_date": "2025-06-15",
      "expiration_date": null,
      "payment_method": {
        "type": "CARD",
        "brand": "VISA",
        "last_four": "1234"
      },
      "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. You'll continue to have access until May 30, 2026. You will not be charged again unless you restart your subscription.",
      "is_paid": true,
      "is_family_plan": false,
      "is_cancellable": true,
      "price": {
        "total": "11.99",
        "currency": "USD"
      }
    }
  ],
  "limit": 100
}

Changes

  • f10ecfa12c00Revision changes
    • warning

      added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new CANCELLABLE_SUBSCRIPTION_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status

    • warning

      added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status

    • warning

      added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status

    • warning

      added the new ENVIRONMENT_MISMATCH enum value to the response property for the response status

    • warning

      added the new INSUFFICIENT_ROLE enum value to the response property for the response status

    • warning

      added the new INSUFFICIENT_ROLE enum value to the response property for the response status

    • warning

      added the new INSUFFICIENT_ROLE enum value to the response property for the response status

    • warning

      added the new INSUFFICIENT_ROLE enum value to the response property for the response status

    • warning

      added the new INSUFFICIENT_SCOPE enum value to the response property for the response status

    • warning

      added the new INSUFFICIENT_SCOPE enum value to the response property for the response status

    • warning

      added the new INSUFFICIENT_SCOPE enum value to the response property for the response status

    • warning

      added the new INSUFFICIENT_SCOPE enum value to the response property for the response status

    • warning

      added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status

    • warning

      added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status

    • warning

      added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status

    • warning

      added the new INVALID_ACCESS_TOKEN enum value to the response property for the response status

    • warning

      added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status

    • warning

      added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status

    • warning

      added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status

    • warning

      added the new MULTIPLE_CANCELLABLE_SUBSCRIPTIONS_FOUND enum value to the response property for the response status

    • warning

      added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status

    • warning

      added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status

    • warning

      added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status

    • warning

      added the new RATE_LIMIT_EXCEEDED enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_ERROR enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_ERROR enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_ERROR enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_ERROR enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status

    • warning

      added the new REQUEST_LOG_QUERY_TIMEOUT enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_ALREADY_EXISTS enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_ERROR enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_LIMIT_REACHED enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status

    • warning

      added the new WEBHOOK_ENDPOINT_NOT_FOUND enum value to the response property for the response status