Customer Spend Reporting

​

Overview

1. Allow users to see spend by merchant or by category
2. Help users with revenue and runway calculations
3. Give users an overview over their cash-based P&L, for example to monitor spend on certain categories

​

Get started

​

For a batch of transactions, synchronously enrich all bank data (either business or consumer data)

1. Post Transactions: Send POST /transactions requests. Make sure that the end_user_id in the payload matches a canonical identifier for the consumer from your systems.
   1. Note: that in the payload, only amount and description are required.
   2. Note: If you receive transactions directly from Plaid, Ocrolus or in PDF, we allow you to just pass on the file without any manipulation. This replaces using the /transactions endpoint in this step. The endpoints you can use are:
      • Plaid - Assets Report
      • Plaid - Transactions Report
      • Ocrolus Report
      • PDF
2. Parse response: In the response to this POST request, you will receive back all items you need for a beautiful transaction feed!

{
    "transactions": [
        {
            ...
            "description_clean": "cleaner_description",
            "merchant": {
                "heron_id": "mrc_nF5uQ1LPBJn5REabCQGeTH",
                "name": "merchant_name",
                "url": "https://some_merchant_url.com",
                "logo_url": "https://url_to_logo.com/merchant_logo.png",
                "icon_url": "https://url_to_icon.com/merchant_icon.svg"
            },
            "payment_processor": {
                "heron_id": "mrc_98gzPbisCPwDkeU123pZ3h",
                "name": "Square",
                "url": "https://squareup.com/us/en"
            }
        }
    ]
}

​

How to display the enriched transactions

• You should display back the merchant.name where available.
• If no merchant.nameis available, display back either the payment_processor or the description_clean.
  • payment_processor is the name of the company that processed the payment, like Square, Stripe, Shopify, etc.
  • description_clean will always be a substring of the description, but without information about payment methods, store numbers, transaction dates, amounts, etc.

• You will receive back either a logo_url, an icon_url or both
• The logo is generally rectangular, and the icon is a square
• Both are either in png or svg format
• The icon/logo are hosted in one of our Google Cloud Storage buckets, and the URL is static with format:
  • Icon: https://storage.googleapis.com/heron-merchant-assets/icons/{merchant_heron_id}.{png|svg}
  • Logo: https://storage.googleapis.com/heron-merchant-assets/logos/{merchant_heron_id}.{png|svg}

• You will receive back a unique identifier, the heron_id, for each merchant. You can use this identifier as a basis for further logic. For example:
  • Allow your users to choose a custom category for a specific merchant, based on that merchant’s heron_id.
  • Show your users all spend with one merchant by aggregating all spend on one merchant heron_id.

• If categories are enabled for you, you will receive them back as a dictionary in the transactions object (see here). You can display back the label to your customer, or assign a static logo to each category instead.

​

Feedback

• Manual: You can send us free-form feedback in our shared Slack channel. We also share spreadsheets with customers that enable them to share feedback with us, which we can also make available via Slack.

​

How to use the output

• A standard use case would be to show your customer all spend per merchant. To do this, sum all spend for a given heron_id for a merchant.
• You can also build comparative statistics and recommendations on top: For example, for a customer with a given revenue, are they spending relatively more or less than others on a payroll provider?

• You can display back categories directly, or use the category labels to calculate items like a company’s P&L or historical revenue.
• You may want to use confidences to only show back transactions that are categorised with high accuracy. If the annotator on the category label is reconciled, your category model has been fine-tuned to have confidence values that map directly to accuracy. This means that for a category label with a confidence of 0.9, we’d expect the label to be accurate 90% of the time.
  • You can use these confidences to display back only labels with a certain probability of being correct, depending on your use case.
• If the annotator on the category label is either heuristics or predicted, your model is not fine-tuned for reliable confidences. If you still want to use confidences, please contact Heron.

{
	"categories": [
		{
			"annotator": "reconciled",
			"confidence": 0.91,
			"heron_id": "ctg_4q5tDaLi66h3EAWYTY11YC",
			"label": "Rent",
			"model_version": "0f74d346-10f8-454d-abc2-5980674e07b1"
		}
	]
}