Correcting transactions merchants

Bud's merchant database is constantly improving and growing, however, it is inevitable that there will always be a few merchants that we have failed to or misidentified. This is why we have created customer initiated corrections, a way for you and your customers to provide feedback and correct a transaction or group of transactions.

We currently support corrections for merchants and categories. In this guide, we walk you through how you can interact with our merchant corrections APIs and give you inspiration for how you can build the best experiences for your customers when correcting a transaction.

Merchant Corrections

Customers can correct the merchant of a transaction using the Correct Transaction Merchant endpoint. This allows you to update the merchant identified for a transaction, add a merchant to a transaction or remove a merchant from a transaction. These actions can be completed for an individual transaction or for a group of transactions.

As part of the request we also allow customers to correct similar transactions. Setting the include_similar field to true we will also correct any similar and future similar transactions with the updated merchant. As a client, you can find a list of your customers similar transactions by using the Similar Transactions Including Merchants endpoint. When calling the endpoint if you provide a transaction_id we will then return a list of all the similar transactions for the given transaction_id.

📘

Please note, any corrections made to transactions will only immediately impact the customer making the correction. Customer corrections are stored and may be used in subsequent model retrains.

Finding the Correct Merchant

In order to update or add a merchant to a transaction you will need to know the name of the merchant in the database. You can search Bud's database for potential keyword matches using the Correction Merchant Search endpoint. This returns the top 5 closest merchants in our database to the keyword used in your search. For example, a search of Amazon will return results for Amazon Fresh, Amazon Prime, Amazon Music etc.

🚧

Please note, the merchant search endpoint is not to be used to try and recreate Bud's merchant database, there are rate limiting restrictions in place and clients may receive a 429 response if the endpoint is being called excessively.

Webhook

Clients can subscribe to the corrections.merchant.corrected webhook, this will notify you each time a transaction has had the merchant corrected, situations where this could occur include; when future transactions are ingested that are similar to existing transactions when the include_similar flag has been set to true, when a transaction that has been corrected gets updated such as moving from pending to booked or when new corrections are submitted. The webhook content will include both the transaction_id that has been corrected as well as the merchant that it has been corrected from and to. You can see an example of this webhook below.

{
  "customer_id": "db8345bd-a658-4e84-868f-9b4c22634f00",
  "corrections": [
    {
      "transaction_id": "d107794e-3b0b-47fc-9bd7-bf12d9700506",
      "attribute": "merchant",
      "from": "Amazon Prime",
      "to": "Amazon Fresh",
    },
    ...
  ],
  "completed_at": "2024-05-26T11:55:55Z"
}

{
  "customer_id": "db8345bd-a658-4e84-868f-9b4c22634f00",
  "corrections": [
    {
      "transaction_id": "d107794e-3b0b-47fc-9bd7-bf12d9700506",
      "attribute": "merchant",
      "from": "Amazon Prime",
      "to": "Amazon Fresh",
    },
    {
      "transaction_id": "03594bd8-25c3-4c9e-bdac-3dd95c2e59b0",
      "attribute": "merchant",
      "from": "Amazon Prime",
      "to": "Amazon Fresh",
    },
    {
      "transaction_id": "1f346d75-e3f9-486b-87de-e299dc8abfaa",
      "attribute": "merchant",
      "from": "Amazon Prime",
      "to": "Amazon Fresh",
    }
    ...
  ],
  "completed_at": "2024-05-26T11:55:55Z"
}

Customer Experience Best Practice

When displaying enriched transactions back to customers we always advise that you give customers the ability to correct transactions. By enabling the customer to correct transactions themselves it increases customer satisfaction and reduces the chance of the customer getting in contact with your support team. Our recommended entry point for this customer journey is when the customer is viewing an individual transaction.

In order to update or add a merchant the customer will need to provide a merchant that exists within Bud's merchant database, we suggest providing a free text input field and using the Correction Merchant Search endpoint to allow customers to search and find the merchant to which they would like to correct the transaction to.

Once the customer has chosen the new merchant it's important to also allow the customer to correct similar transactions.

You can create a list of similar transactions by calling the Similar Transactions Including Merchants endpoint. If the customer chooses to update all similar transactions then you can use the include_similar flag when calling the Correct Transaction Merchant endpoint, otherwise, we recommend sending a single API call with a list specifying the transaction_id's that the customer has selected.