> ## 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 merchant accounts when a card is provisioned via [CardSwitcher](/card-switcher/quickstart). When enabled, the [`CARD_UPDATED`](/card-switcher/webhook-events/card-updated) webhook will include a `subscriptions` array containing IDs for subscriptions detected on the merchant account.

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

## 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" }
    ]
  }
}
```

## Retrieve Full Subscription Details

For each subscription ID, call [Get Subscription By ID](/api-reference/products/subscriptions/get-by-id) 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 to the Knot platform through [CardSwitcher](/card-switcher/quickstart), 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>

## Testing

To test SubscriptionManager in the `development` environment, first perform a card switch via [CardSwitcher](/card-switcher/quickstart) with one of the merchants below. The resulting [`CARD_UPDATED`](/card-switcher/webhook-events/card-updated) webhook will include subscription IDs that you can then use to test retrieval. 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