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": "tv_and_film",
      "period": "monthly",
      "categories": {
        "l1": "bills",
        "l2": "tv_broadband_and_phone"
      },
      "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

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 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.