---
title: "POST /subscriptions/list"
method: POST
path: "/subscriptions/list"
---

# POST /subscriptions/list

`POST /subscriptions/list`

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

## Request body

- object
  - `external_user_id` string, required — Your unique identifier for the user.
  - `merchant_id` integer — 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_paid` boolean — When provided, only subscriptions matching this paid/free status are returned.
  - `is_family_plan` boolean — When provided, only subscriptions matching this family-plan status are returned.
  - `is_cancellable` boolean — When provided, only subscriptions matching this cancellable status are returned.
  - `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.
  - `limit` integer — Maximum number of subscriptions to retrieve (min: 1, max: 100).

## Response `200`

Successful request.

- object
  - `subscriptions` Subscription[]
    - `id` string — Unique identifier for the subscription.
    - `external_id` string — External identifier for the subscription provided by the merchant.
    - `name` string — Human-readable subscription name as displayed by the merchant.
    - `description` string, nullable — Description of the subscription plan.
    - `merchant` SubscriptionMerchant — The merchant account linked by the user.
      - `id` integer — Unique identifier for the merchant.
      - `name` string — Name of the merchant.
      - `category` string — Category of the merchant.
      - `logo` string — URL of the merchant's logo.
      - `parent_merchant` MerchantFull
        - `id` integer — Unique identifier for the merchant.
        - `name` string — Name of the merchant.
        - `category` string — Category of the merchant.
        - `logo` string — URL of the merchant's logo.
    - `status` union — Status of the subscription.
      - 'ACTIVE' — Billing and access ongoing.
      - 'ACTIVE_CANCELLATION' — Cancelled, but still active until end of billing period.
      - 'ACTIVE_PLAN_CHANGE' — Plan change queued.
      - 'ACTIVE_SUSPENSION' — Service active but on a temporary grace period often due to payment failure. Likely to become suspended if payment is not made.
      - 'PENDING' — Not yet billed or activated.
      - 'PAUSED' — Temporarily paused by user.
      - 'CANCELLED' — Fully terminated.
      - 'SUSPENDED' — Service suspended by merchant, often due to payment failure.
      - 'UNRECOGNIZED' — Status could not be determined.
    - `billing_cycle` 'RECURRING_MONTHLY' | 'RECURRING_BIMONTHLY' | 'RECURRING_WEEKLY' | 'RECURRING_BIWEEKLY' | 'RECURRING_QUARTERLY' | 'RECURRING_SEMIANNUALLY' | 'RECURRING_ANNUALLY' | 'RECURRING_DAILY' | 'ONE_TIME' | 'UNRECOGNIZED' — Billing cycle of the subscription.
    - `next_billing_date` string, date, nullable — Date of the next scheduled charge in UTC. ISO 8601 format (YYYY-MM-DD).
    - `last_billing_date` string, date, nullable — Date of the most recent attempted charge in UTC. ISO 8601 format (YYYY-MM-DD).
    - `start_date` string, date, nullable — Start date for the subscription in UTC. ISO 8601 format (YYYY-MM-DD).
    - `expiration_date` string, date, nullable — Date of the loss of access to the subscription due to cancellation or other means in UTC. ISO 8601 format (YYYY-MM-DD).
    - `payment_method` SubscriptionPaymentMethod
      - `type` 'CARD' | 'THIRD_PARTY' | 'APPLE_PAY' | 'GOOGLE_PAY' | 'AMAZON_PAY' | 'PAYPAL' | 'CASH_APP' | 'VENMO' | 'AFFIRM' | 'KLARNA' | 'GIFT_CARD' | 'CASH' | 'BANK_ACCOUNT' | 'LOYALTY_POINTS' | 'UNRECOGNIZED' — Type of the payment method.
      - `brand` string, nullable — Brand of the payment method.
      - `last_four` string, nullable — Last 4 digits of the payment method, if a payment card.
    - `cancel_instructions` string, nullable — Instructions for cancelling the subscription, if available.
    - `is_paid` boolean, nullable — Whether the subscription is a paid plan or free.
    - `is_free_trial` boolean, nullable — Whether the subscription is currently in a free trial period.
    - `is_family_plan` boolean, nullable — Whether the subscription is a family plan.
    - `is_cancellable` boolean — Indicates whether the merchant has marked this subscription as cancellable.
    - `price` SubscriptionPrice
      - `total` string — Total price of the subscription.
      - `currency` string — Currency of the price. ISO 4217 format.
  - `next_cursor` string, nullable — 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.

## Other responses

- `400` — Bad request.
- `401` — Unauthorized request.
- `403` — Forbidden request.
- `500` — Internal server error.

---

[API](https://skmtc.net/knotapi/apis/knot-api.md) · [All operations](https://skmtc.net/knotapi/apis/knot-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/knotapi/knot-api/versions/4610832c2087/schema)