Subscription Finder

Retrieve Subscriptions

The GET v1/subscriptions endpoint provides a list of a customer's subscriptions based on their previous transactions.

This endpoint will return a list of the given customer's subscriptions between the provided X-From date and X-To date headers. An example of a 200 response can be seen below.

{
  "operation_id": "v1_subscriptions_get",
  "data": [
    {
      "subscription_type": "media_streaming",
      "period": "monthly",
      "categories": {
        "l1": "media_and_telecoms",
        "l2": "tv_streaming_services"
      },
      "merchant": {
        "id": "netflix",
        "name": "Netflix",
        "logo": "https://assets.thisisbud.com/netflix_logo_placeholder.jpeg"
      },
      "transactions": [
        {
          "transaction_id": "fdcc55c6-f347-4abc-8c66-61ff290d8bd4",
          "account_id": "an_account_id",
          "transaction_description": "Netflix",
          "provider": "Barclays",
          "date": "2022-03-21T01:00:00+0100",
          "amount": {
            "value": "9.99",
            "currency": "GBP"
          },
          "credit_debit_indicator": "Debit"
        },
        {
          "transaction_id": "hdcc55c6-f347-4abc-8c66-61ff290d8bd4",
          "account_id": "an_account_id",
          "transaction_description": "Netflix",
          "provider": "Barclays",
          "date": "2022-04-21T01:00:00+0100",
          "amount": {
            "value": "9.99",
            "currency": "GBP"
          },
          "credit_debit_indicator": "Debit"
        }
      ]
    },
    {
      "subscription_type": "unknown",
      "period": "unknown",
      "categories": {
        "l1": "general",
        "l2": "other_general"
      },
      "transactions": [
        {
          "transaction_id": "idcc55c6-f347-4abc-8c66-61ff290d8bd4",
          "account_id": "an_account_id",
          "transaction_description": "A Random Subscription Payment",
          "provider": "Barclays",
          "date": "2022-05-11T01:00:00+0100",
          "amount": {
            "value": "59.99",
            "currency": "GBP"
          },
          "credit_debit_indicator": "Debit"
        }
      ]
    }
  ],
  "metadata": {
    "results": 2,
    "from": "2022-03-19",
    "to": "2022-05-19"
  }
}

curl --request GET \
     --url https://api-sandbox.thisisbud.com/v1/subscriptions \
     --header 'X-Client-Id: <client_id>' \
     --header 'X-Customer-Id: <customer_id>' \
     --header 'X-From: 2023-01-01' \
     --header 'X-To: 2024-01-01' \
     --header 'accept: application/json'

This response will contain a list of a customer's subscriptions including the subscription_type, period, and merchant in addition to the transactions associated with that subscription. Currently, the following subcription_types are supported:

Media Streaming
Newspaper & Magazines
Food & Drink
Technology
Fitness & Gym
Charitable Donations
Unknown

Please note, not all regular payments are subscriptions, this means regular payments such as rent, mortgage or utility payments will not be returned by the subscription finder.

If you receive a 400 response like below, please check the headers you're sending in the request before trying again. If you continue to receive an error please consult the error responses guide.

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.