> ## Documentation Index > Fetch the complete documentation index at: https://docs.knotapi.com/llms.txt > Use this file to discover all available pages before exploring further. # List Subscriptions > List a user's subscriptions using cursor-based pagination. ## OpenAPI ````yaml POST /subscriptions/list openapi: 3.1.0 info: title: Knot API description: An API to interact with the Knot merchant connectivity platform. version: 1.0.0 servers: - url: https://development.knotapi.com description: Development server security: - basicAuth: [] paths: /subscriptions/list: post: description: List a user's subscriptions using cursor-based pagination. operationId: subscriptions_list requestBody: description: The input parameters required for listing subscriptions. content: application/json: schema: type: object properties: external_user_id: type: string description: Your unique identifier for the user. example: abc merchant_id: type: integer description: >- The unique ID of a merchant. When provided, only subscriptions for that merchant's linked account are returned. example: 18 status: type: string description: >- When provided, only subscriptions with this status are returned. example: ACTIVE enum: - ACTIVE - ACTIVE_CANCELLATION - ACTIVE_PLAN_CHANGE - ACTIVE_SUSPENSION - PENDING - PAUSED - CANCELLED - SUSPENDED - UNRECOGNIZED is_paid: type: boolean description: >- When provided, only subscriptions matching this paid/free status are returned. example: true is_family_plan: type: boolean description: >- When provided, only subscriptions matching this family-plan status are returned. example: false is_cancellable: type: boolean description: >- When provided, only subscriptions matching this cancellable status are returned. example: true cursor: type: string description: >- 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: type: integer description: >- Maximum number of subscriptions to retrieve (min: 1, max: 100). example: 100 default: 100 required: - external_user_id examples: AllSubscriptions: summary: List all subscriptions value: external_user_id: abc FilterByMerchant: summary: List subscriptions for a specific merchant value: external_user_id: abc merchant_id: 18 responses: '200': description: Successful request. content: application/json: schema: type: object properties: subscriptions: type: array items: $ref: '#/components/schemas/Subscription' next_cursor: type: - string - 'null' description: >- Cursor token for the next page of subscriptions. `null` when there are no more subscriptions to retrieve. limit: type: integer description: >- Number of subscriptions returned based on the limit provided. example: 100 examples: AllSubscriptions: summary: Example subscriptions response. value: 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 parent_merchant: null 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. 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 parent_merchant: null status: ACTIVE billing_cycle: RECURRING_MONTHLY next_billing_date: '2026-03-10' last_billing_date: '2026-02-10' start_date: '2024-09-01' 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. is_paid: true is_family_plan: false is_cancellable: true price: total: '12.99' currency: USD next_cursor: eyJpZCI6MjI3ODEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0 limit: 100 FilterByMerchant: summary: Example filtered-by-merchant response. value: 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 parent_merchant: null 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. is_paid: true is_family_plan: false is_cancellable: true price: total: '11.99' currency: USD next_cursor: null limit: 100 '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: UserNotFound: summary: User not found value: error_type: USER_ERROR error_code: USER_NOT_FOUND error_message: The user was not found. Please check the ID provided. MerchantAccountNotFound: summary: Merchant account not found value: error_type: MERCHANT_ACCOUNT_ERROR error_code: MERCHANT_ACCOUNT_NOT_FOUND error_message: >- The merchant account was not found. Please check the merchant_id provided. ExternalUserIdRequired: summary: external_user_id is required value: error_type: INVALID_REQUEST error_code: INVALID_FIELD error_message: The external_user_id field is required. LimitNotInteger: summary: limit must be an integer value: error_type: INVALID_REQUEST error_code: INVALID_FIELD error_message: The limit must be an integer. LimitMoreThanOne: summary: The limit must be at least 1. value: error_type: INVALID_REQUEST error_code: INVALID_FIELD error_message: The limit must be at least 1. LimitLessThanHundred: summary: The limit may not be greater than 100. value: error_type: INVALID_REQUEST error_code: INVALID_FIELD error_message: The limit may not be greater than 100. InvalidCursorFormat: summary: Cursor format is invalid value: error_type: INVALID_REQUEST error_code: INVALID_FIELD error_message: The provided cursor is invalid. InvalidStatus: summary: status is invalid value: error_type: INVALID_REQUEST error_code: INVALID_FIELD error_message: The selected status is invalid. InvalidIsPaid: summary: is_paid must be a boolean value: error_type: INVALID_REQUEST error_code: INVALID_FIELD error_message: The is_paid field must be true or false. InvalidIsCancellable: summary: is_cancellable must be a boolean value: error_type: INVALID_REQUEST error_code: INVALID_FIELD error_message: The is_cancellable field must be true or false. '401': description: Unauthorized request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: AuthFailed: summary: Auth failed value: error_type: INVALID_INPUT error_code: INVALID_API_KEYS error_message: Invalid client_id or secret provided. '403': description: Forbidden request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: NoAccess: summary: No access value: error_type: INVALID_REQUEST error_code: NO_ACCESS error_message: Please contact Knot for access to this endpoint. '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/Error' examples: InternalServerError: summary: Unexpected server error value: message: Server Error components: schemas: Subscription: type: object properties: id: type: string description: Unique identifier for the subscription. example: 13da3c28-a068-4642-9ce2-b730cfda5f5f external_id: type: string description: External identifier for the subscription provided by the merchant. example: a9x7bq2lmw5p name: type: string description: Human-readable subscription name as displayed by the merchant. example: Disney+, Hulu Bundle Premium description: type: - string - 'null' description: Description of the subscription plan. example: Ad-free streaming with Disney+ and Hulu merchant: $ref: '#/components/schemas/SubscriptionMerchant' status: type: string description: Status of the subscription. example: ACTIVE oneOf: - const: ACTIVE title: ACTIVE description: Billing and access ongoing. - const: ACTIVE_CANCELLATION title: ACTIVE_CANCELLATION description: Cancelled, but still active until end of billing period. - const: ACTIVE_PLAN_CHANGE title: ACTIVE_PLAN_CHANGE description: Plan change queued. - const: ACTIVE_SUSPENSION title: ACTIVE_SUSPENSION description: >- Service active but on a temporary grace period often due to payment failure. Likely to become suspended if payment is not made. - const: PENDING title: PENDING description: Not yet billed or activated. - const: PAUSED title: PAUSED description: Temporarily paused by user. - const: CANCELLED title: CANCELLED description: Fully terminated. - const: SUSPENDED title: SUSPENDED description: Service suspended by merchant, often due to payment failure. - const: UNRECOGNIZED title: UNRECOGNIZED description: Status could not be determined. billing_cycle: type: string enum: - RECURRING_MONTHLY - RECURRING_BIMONTHLY - RECURRING_WEEKLY - RECURRING_BIWEEKLY - RECURRING_QUARTERLY - RECURRING_SEMIANNUALLY - RECURRING_ANNUALLY - RECURRING_DAILY - ONE_TIME - UNRECOGNIZED description: Billing cycle of the subscription. example: RECURRING_MONTHLY next_billing_date: type: - string - 'null' format: date description: >- Date of the next scheduled charge in UTC. ISO 8601 format (YYYY-MM-DD). example: '2026-02-10' last_billing_date: type: - string - 'null' format: date description: >- Date of the most recent attempted charge in UTC. ISO 8601 format (YYYY-MM-DD). example: '2026-01-10' start_date: type: - string - 'null' format: date description: >- Start date for the subscription in UTC. ISO 8601 format (YYYY-MM-DD). example: '2025-06-15' expiration_date: type: - string - 'null' format: date description: >- Date of the loss of access to the subscription due to cancellation or other means in UTC. ISO 8601 format (YYYY-MM-DD). example: null payment_method: $ref: '#/components/schemas/SubscriptionPaymentMethod' cancel_instructions: type: - string - 'null' description: Instructions for cancelling the subscription, if available. example: >- 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: type: - boolean - 'null' description: Whether the subscription is a paid plan or free. example: true is_free_trial: type: - boolean - 'null' description: Whether the subscription is currently in a free trial period. example: false x-mint: post: - coming soon is_family_plan: type: - boolean - 'null' description: Whether the subscription is a family plan. example: false is_cancellable: type: boolean description: >- Indicates whether the merchant has marked this subscription as cancellable. example: true price: $ref: '#/components/schemas/SubscriptionPrice' example: 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 Error: type: object properties: error_type: type: string description: Type of error. enum: - INVALID_INPUT - INVALID_REQUEST - USER_ERROR - SESSION_ERROR - MERCHANT_ACCOUNT_ERROR - MERCHANT_ERROR - SUBSCRIPTION_ERROR - TRANSACTION_ERROR - CART_ERROR example: INVALID_REQUEST error_code: type: string description: Error code. enum: - INVALID_API_KEYS - INVALID_FIELD - INVALID_JWE - INVALID_CURSOR_FORMAT - USER_NOT_FOUND - MERCHANT_ACCOUNT_NOT_FOUND - MERCHANT_ACCOUNT_DISCONNECTED - SESSION_NOT_FOUND - EXTEND_NOT_SUPPORTED - MERCHANT_UNAVAILABLE - NO_ACCESS - TRANSACTION_NOT_FOUND - NO_TRANSACTIONS - SUBSCRIPTION_NOT_FOUND - ONGOING_OPERATION - CART_NOT_FOUND - FULFILLMENT_NOT_FOUND example: INVALID_FIELD error_message: type: string description: Detailed error message. example: The limit may not be greater than 10. SubscriptionMerchant: type: object description: The merchant account linked by the user. properties: id: type: integer description: Unique identifier for the merchant. example: 18 name: type: string description: Name of the merchant. example: Hulu category: type: string description: Category of the merchant. example: Streaming logo: type: string description: URL of the merchant's logo. example: >- https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png parent_merchant: oneOf: - $ref: '#/components/schemas/MerchantFull' - type: 'null' description: >- Parent merchant of the merchant account linked by the user, or `null` when the linked merchant has no parent. E.g. `Google` is the parent of `YouTube TV` and `Amazon` is the parent of `Prime Video`. SubscriptionPaymentMethod: type: object properties: type: type: string enum: - CARD - THIRD_PARTY - APPLE_PAY - GOOGLE_PAY - AMAZON_PAY - PAYPAL - CASH_APP - VENMO - AFFIRM - KLARNA - GIFT_CARD - CASH - BANK_ACCOUNT - LOYALTY_POINTS - UNRECOGNIZED description: Type of the payment method. example: CARD brand: type: - string - 'null' description: Brand of the payment method. example: VISA last_four: type: - string - 'null' description: Last 4 digits of the payment method, if a payment card. example: '1234' example: type: CARD brand: VISA last_four: '1234' SubscriptionPrice: type: object properties: total: type: string description: Total price of the subscription. example: '11.99' currency: type: string description: Currency of the price. ISO 4217 format. example: USD MerchantFull: type: object properties: id: type: integer description: Unique identifier for the merchant. example: 18 name: type: string description: Name of the merchant. example: Hulu category: type: string description: Category of the merchant. example: Streaming logo: type: string description: URL of the merchant's logo. example: >- https://knot.imgix.net/merchants/KBQ5j6cN010PPpwbO7RpKGyDrCpsZ91FRhwnZp5u.png securitySchemes: basicAuth: type: http scheme: basic description: >- Basic authentication header of the form `Basic `, where `` is the base64-encoded string `username:password`. Use your `client_id` as the `username` and your `secret` as the `password` value. ````