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-Customer-Secret: <customer_secret>' \ # Not required for hosted customers
     --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.

A 401 response would indicate that you are not authorised to make this request, if you believe this to be a mistake or are receiving persistent 500 responses please raise a support request.





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