Skip to main content

​
Introduction

SubscriptionManager allows you to retrieve subscription information from merchant accounts when a card is provisioned via CardSwitcher. When enabled, the CARD_UPDATED webhook will include a subscriptions array containing IDs for subscriptions detected on the merchant account.
SubscriptionManager must be enabled for your account. Reach out to the Knot team to get started.

​
Receive Subscription IDs

When a card is successfully updated, the CARD_UPDATED webhook will include subscription IDs in data.subscriptions: 
{
  "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 to retrieve the full subscription object.

​
Cancel a Subscription

Once a user has linked a merchant account to the Knot platform through CardSwitcher, 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.
1

Display the subscription in your app

Call Get Merchant Accounts with the user’s external_user_id and merchant_id to check whether cancellation is supported for that merchant account.
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 field is true. Only when both conditions are met should you display a cancel button to the user.
// Example connection object from Get Merchant Accounts response
{
  "connection": {
    "status": "connected",
    "scopes": [
      { "type": "update_card" },
      { "type": "cancel" }
    ]
  }
}
2

Call the Cancel Subscription endpoint

When the user taps the cancel button, call Cancel Subscription with the subscription ID to cancel the subscription or bill within seconds. Subscribe to the CANCELLATION_SUCCEEDED and CANCELLATION_FAILED webhooks to be notified of the outcome.

​
Testing

To test SubscriptionManager in the development environment, first perform a card switch via CardSwitcher with one of the merchants below. The resulting 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