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.

​
Get ongoing updates

​
New subscriptions

To be notified when new subscriptions are detected on a merchant account, listen to the 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 webhook, make a request to Get Subscription By ID for each ID in data.subscriptions, passing the ID received in the webhook as a path parameter.

​
Updated subscriptions

Receiving updated subscription information is entirely optional and may not be relevant for your use case.
To be notified about updates to existing subscriptions, listen to the 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 webhook, make a request to Get Subscription 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, 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