Correcting transaction 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 will also correct any similar and future similar transactions with the updated merchant. As a client, you can find a list of your customer's 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.

Adding a Custom Merchant

If Bud does not have the merchant your customer is looking for within its database you can add a Custom Merchant. Custom Merchants exist only for a single customer and allow the customer to specify the exact name. You can create a Custom Merchant by calling the Create a new custom merchant endpoint, when doing so you will be required to provide the customer_id and the name of the merchant, additionally, your customers can also choose to provide a suggested_url and whether the merchant is online_or_billing_only. Once the custom merchant is created it will have its own custom_merchant_id, this can be used as the merchant_id within the Merchant Corrections endpoint. The custom merchant will also appear, alongside Bud merchants, when querying the Merchant Search endpoint.

Please note, all Custom Merchants created will have a placeholder logo associated with them. As Bud expands the merchant database it will occasionally be necessary for custom merchants from multiple customers to be merged within a single merchant in Bud's database, at this point any transactions that been corrected to the Custom Merchant will be updated with the new merchant details.

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.

If the merchant that the customer is looking for is not already in Bud's database you can allow your customer to add it by calling the Create a new custom merchant endpoint.

In order to provide as rich an experience as possible, when a customer is creating a custom merchant you should allow them to specify a website and whether the merchant is online only in addition to the name.

Once the customer has chosen the new merchant (whether that be from Bud's existing database or a custom merchant) it's important also to 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.