> ## 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.

# Quickstart

> Get started with SubscriptionManager to retrieve and manage subscription data from merchant accounts.

## Introduction

SubscriptionManager allows you to retrieve subscription information from a user's merchant accounts. There are two ways to retrieve subscriptions depending on your use case:

1. After provisioning your card to the merchant account with [CardSwitcher](/card-switcher/quickstart): the user authenticates to the merchant account, their card is provisioned, and their subscription data is returned in the [`CARD_UPDATED`](/card-switcher/webhook-events/card-updated) webhook event.
2. Without provisioning a card: the user authenticates to the merchant account and their subscription data is returned in the [`NEW_SUBSCRIPTIONS_AVAILABLE`](/subscription-manager/webhook-events/new-subscriptions-available) webhook event.

<Info>
  SubscriptionManager must be enabled for your account. Reach out to the Knot team to get started.
</Info>

## Getting Started

<Tabs>
  <Tab title="CardSwitcher" icon="credit-card">
    If you have already integrated [CardSwitcher](/card-switcher/quickstart), you can receive subscription data as part of the card switch flow without any additional client-side integration.

    ### Receive Subscription IDs

    When a card is successfully updated, the [`CARD_UPDATED`](/card-switcher/webhook-events/card-updated) webhook will include subscription IDs in `data.subscriptions`:

    ```json theme={"system"}
    {
      "event": "CARD_UPDATED",
      ...
      "data": {
        "card_id": "123456789",
        "subscriptions": [
          { "id": "ka8sdf0asdfm10as0a0sdfja7ssa8" },
          { "id": "8asdh29qjss923kd0d920skd8sjd8" }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Without provisioning a card" icon="link">
    Use this approach when you want to retrieve subscription data without provisioning a card to the user's merchant account. For example, you may choose this option when the user's card is already present on the merchant account or you have not issued the user a card at all, but they want to take advantage of subscription management functionality.

    ### Set Up

    <Steps>
      <Step title="Access your customer dashboard" icon="table-columns" titleSize="h4">
        Ensure you have access to your [Customer Dashboard](https://dashboard.knotapi.com) and retrieve your `client_id` and `secret`, which you will use as the basic auth username and password for your API key respectively. Note that your `client_id` and `secret` vary between the `development` and `production` environments.
      </Step>

      <Step title="Install the SDK" icon="mobile" titleSize="h4">
        Install and import an SDK for your platform: [iOS](/sdk/ios), [Android](/sdk/android), [React Native](/sdk/react-native), [Flutter](/sdk/flutter), or [Web](/sdk/web).
      </Step>

      <Step title="Subscribe to webhooks" icon="webhook" titleSize="h4">
        Register a webhook endpoint in the [Customer Dashboard](https://dashboard.knotapi.com/developers/webhooks) and subscribe to the [webhook events](/webhooks) your backend needs to receive.
      </Step>
    </Steps>

    ### Start the Flow

    <Steps>
      <Step title="Retrieve available merchants" icon="list-ul" titleSize="h4">
        Call [List Merchants](/api-reference/merchants/list-merchants) to retrieve a list of merchants that are available for the SubscriptionManager product by passing `type = subscription_manager`. These are merchants you can display in your app and allow users to link. More [here](/link/retrieving-and-listing-merchants) on natively displaying available merchants.

        You will be notified via the [`MERCHANT_STATUS_UPDATE`](/link/webhook-events/merchant-status-update) webhook when the availability of merchants change by product & platform, so it is not necessary to call [List Merchants](/api-reference/merchants/list-merchants) each time users interact with your app.

        <Note>
          Merchant IDs are static and remain constant across all environments.
        </Note>
      </Step>

      <Step title="Call the API to create a session" icon="code" titleSize="h4">
        With your `client_id` and `secret` for the `development` environment, call [Create Session](/api-reference/sessions/create-session) with `type: link` to create a session used when invoking the SDK. This will allow the user to link their merchant account without provisioning a card.
      </Step>

      <Step title="Initialize the SDK and handle callbacks" icon="play" titleSize="h4">
        Initialize the SDK with the `session_id` retrieved from [Create Session](/api-reference/sessions/create-session) and a merchant `Id` retrieved from [List Merchants](/api-reference/merchants/list-merchants) in `KnotConfiguration`. The SDK is where users will interact with the Knot UI to authenticate to various merchants. All login flows, including step-up authentication, are handled within the SDK.

        Wire up `onSuccess`, `onError`, `onExit`, and `onEvent` to react to client-side events as the user moves through the flow. See further details on callback events for [iOS](/sdk/ios#events), [Android](/sdk/android#events), [React Native](/sdk/react-native#events), [Flutter](/sdk/flutter#events), and [Web](/sdk/web).

        **Tag your entry points.** To provide better visibility into conversion across different entry points, the Knot SDK supports an `entryPoint` parameter when invoking the SDK. This value is returned in the down-funnel [`AUTHENTICATED`](/link/webhook-events/authenticated) webhook event, allowing you to measure conversion by entry point in your analytics tool of choice.

        Pass a distinct `entryPoint` value for each entry point location where the Knot SDK is invoked in your app. Common examples: `onboarding`, `home`, `push-notif-X`, `in-app-lifecycle-card-X`.

        <Tip>
          Tagging entry points is strongly recommended to future-proof visibility into your implementation and allow for downstream conversion optimizations.
        </Tip>
      </Step>

      <Step title="Login" icon="arrow-right-to-bracket" titleSize="h4">
        **In the development environment,** use testing credentials to login to a merchant account and simulate retrieving subscriptions.
      </Step>

      <Step title="Handle authenticated event" icon="arrow-right" titleSize="h4">
        Ingest the [`AUTHENTICATED`](/link/webhook-events/authenticated) webhook to notify your backend that the merchant account is successfully linked to Knot and that the connection status is `connected`.

        You can also use [Get Merchant Accounts](/api-reference/accounts/get-accounts) to retrieve this and other merchant accounts, as well as their connection status.
      </Step>
    </Steps>

    ### Receive Subscription IDs

    After the user authenticates, Knot automatically pulls subscription data from the merchant account. Listen for the [`NEW_SUBSCRIPTIONS_AVAILABLE`](/subscription-manager/webhook-events/new-subscriptions-available) webhook to be notified of subscriptions on the merchant account.

    ```json theme={"system"}
    {
      "event": "NEW_SUBSCRIPTIONS_AVAILABLE",
      ...
      "data": {
        "subscriptions": [
          { "id": "ka8sdf0asdfm10as0a0sdfja7ssa8" },
          { "id": "8asdh29qjss923kd0d920skd8sjd8" }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

### Retrieve Full Subscription Details

Upon receiving the webhook, call [Get Subscription By ID](/api-reference/products/subscriptions/get-by-id) for each ID in `data.subscriptions` to retrieve the full [subscription object](/api-reference/products/subscriptions/subscription-object).

## Get Ongoing Updates

### New subscriptions

To be notified when new subscriptions are detected on a merchant account, listen to the [`NEW_SUBSCRIPTIONS_AVAILABLE`](/subscription-manager/webhook-events/new-subscriptions-available) webhook. You will receive this event each time a new subscription is found on the merchant account.

Upon receiving the [`NEW_SUBSCRIPTIONS_AVAILABLE`](/subscription-manager/webhook-events/new-subscriptions-available) webhook, make a request to [Get Subscription By ID](/api-reference/products/subscriptions/get-by-id) for each ID in `data.subscriptions`, passing the ID received in the webhook as a path parameter.

### Updated subscriptions

<Note>
  Receiving updated subscription information is entirely optional and may not be relevant for your use case.
</Note>

To be notified about updates to existing subscriptions, listen to the [`UPDATED_SUBSCRIPTIONS_AVAILABLE`](/subscription-manager/webhook-events/updated-subscriptions-available) webhook. You will receive this event for a merchant account each time there are existing subscriptions for which data has changed (e.g. a price change or status update).

Upon receiving the [`UPDATED_SUBSCRIPTIONS_AVAILABLE`](/subscription-manager/webhook-events/updated-subscriptions-available) webhook, make a request to [Get Subscription By ID](/api-reference/products/subscriptions/get-by-id) for each ID in `data.subscriptions`, passing the ID received in the webhook as a path parameter.

## Cancel a Subscription

Once a user has linked a merchant account, they can cancel a subscription or bill associated with that merchant account. Follow the steps below to determine whether cancellation is available and to execute it.

<Steps>
  <Step title="Display the subscription in your app">
    Call [Get Merchant Accounts](/api-reference/accounts/get-accounts) with the user's `external_user_id` and `merchant_id` to check whether cancellation is supported for that merchant account.

    ```bash theme={"system"}
    curl --request GET \
      --url 'https://development.knotapi.com/accounts/get?external_user_id=15d036d8-0ae5-41bb-84fa-88f839465e5e&merchant_id=45' \
      --header 'Authorization: Basic Y2xpZW50X2lkOnNlY3JldA=='
    ```

    In the response, check that the merchant account's `connection.scopes` array contains an object with `"type": "cancel"` **and** that the subscription's [`is_cancellable`](/api-reference/products/subscriptions/get-by-id#response-is-cancellable) field is `true`. Only when both conditions are met should you display a cancel button to the user.

    ```json theme={"system"}
    // Example connection object from Get Merchant Accounts response
    {
      "connection": {
        "status": "connected",
        "scopes": [
          { "type": "update_card" },
          { "type": "cancel" }
        ]
      }
    }
    ```
  </Step>

  <Step title="Call the Cancel Subscription endpoint">
    When the user taps the cancel button, call [Cancel Subscription](/api-reference/products/subscriptions/cancel) with the subscription ID to cancel the subscription or bill within seconds. Subscribe to the [`CANCELLATION_SUCCEEDED`](/subscription-manager/webhook-events/cancellation-succeeded) and [`CANCELLATION_FAILED`](/subscription-manager/webhook-events/cancellation-failed) webhooks to be notified of the outcome.
  </Step>
</Steps>

## Handle disconnected merchant accounts

If for example a user changes their password to a merchant account, the [Get Merchant Accounts](/api-reference/accounts/get-accounts) endpoint will `connection.status: disconnected` and you'll be notified via the [`ACCOUNT_LOGIN_REQUIRED`](/link/webhook-events/account-login-required) webhook event. When this occurs, subscription data will not be refreshed (e.g. in case there is a plan or status change) and you will not be able to make requests to [Cancel Subscription](/api-reference/products/subscriptions/cancel) without the user relinking their merchant account.

You'll want to display a UX in your app to allow users to reconnect their account. For example, you may choose to display a button that says "Reconnect" or "Refresh" depending on the exact UX. When the user clicks the button, call [Create Session](/api-reference/sessions/create-session) with `type: link` and invoke the SDK to allow the user to reconnect their merchant account.

<Note>
  To test this behavior in development, use the [Disconnect Account](/api-reference/development/disconnect-account) endpoint.
</Note>

## Testing

To test SubscriptionManager in the `development` environment, use one of the merchants below. The following is a subset of merchants available for testing - it is not the full list of supported merchants.

* Verizon
* T-Mobile
* Spectrum
* Xfinity Internet
* Xfinity Mobile
* Apple
* Netflix
* Disney+
* Hulu
* Spotify

**Via CardSwitcher:** Perform a card switch via [CardSwitcher](/card-switcher/quickstart) with one of the merchants above. Testing docs [here](/card-switcher/testing). The resulting `CARD_UPDATED` webhook will include subscription IDs that you can then use to test retrieval of the full subscription details.

**Without provisioning a card:** Create a session with `type: link`, initialize the SDK with a test merchant, and authenticate using testing credentials `user_good`/ `pass_good`. The [`NEW_SUBSCRIPTIONS_AVAILABLE`](/subscription-manager/webhook-events/new-subscriptions-available) webhook will fire and include subscription IDs that you can then use to test retrieval.