Sign in

v1

latestOpenAPI 3.1.02026-07-262218115.4 KB

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

post/subscriptions/list

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
}