Spending patterns

Learn how you can retrieve your users' spending habits

Overview

Okra’s Spending Patterns uses machine learning to analyze your users’ spending habits. Learn how you can get a clear breakdown of what your users’ spend on, and the frequency of their expenses.


How it works

Spending Patterns is a user-permissioned product. Your users can grant access to their transaction data, which the Okra API then retrieves and sends to the Natural Language Understanding unit. The NLU processes this data to determine your users' spending patterns.

The NLU analyzes and groups transaction data into spending patterns and payment methods.

Spending patterns

Patterns are data points and keywords that show what your user spends on, and the frequency of these expenses. Patterns include:

  • Named Entities are keywords and sub-texts that the API identifies in transaction descriptions. These include transaction beneficiary, utility keywords, the reason for transaction, NUBAN, and spending habits.
  • Spending keywords are texts that show what your users have spent on. These include gifts, vacations, gym membership, cable tv, and so on.
  • Transaction chunks are transactions that are part of a larger transaction chain. The NLU identifies and tracks these transaction chains. These include partial payments and purchases made in several instalments.

The Spending Patterns Engine consumes these data points and keywords to assign each transaction into a spending category.

Click to see all spending categories

CategoryDescription
DebtDebit transactions that are repayments of loans or mortgages.
FoodFood and food-related expeneses. Restaurants, groceries, and take-outs belong to this category.
EntertainmentTransactions spent on entertainment activities such as club entrance fees or movie tickets.
GamblingTransactions spent on gambling activities such as lottery or BetWay.
GiftsExpenses such as Christmas gifts or gift cards.
DonationsTransactions that are of charitable nature, such as tithes, Sunday offerings, church pledges, or donations to charities.
SavingsTracks keywords related to investments and savings, such as fixed deposits, trust funds, and ajo savings.
HousingTransactions spent on rent, mortgages, home decor, plumbing, gardening, or similar.
MedicalGroups medical expenses such as hospital bills or pharmacy bills.
TravelTransactions spent on flight tickets, hotel reservations, or similar.
UtilitiesTransactions spent on utilities such as internet access, cable TV, or power bills.
InsuranceGroups insurance related expenses and transactions.
TransportationCollects transportation expenses such as BRT subscriptions, Uber, and Bolt receipts.
Personal careGroups transactions related to selfcare, such as gym membership or spa fees.
TaxesTax-related expenses.
PetCollects expenses such as pet food or veterinary services.
SubscriptionsCollects subscription fees for services such as Netflix, Spotify, Apple Music, or Prime Video.
FamilyCollects expenses related to the household and family. These include school fees, toys, diapers, nursery fees, or allowance.
MiscellaneousCollects transactions that do not fit into any other category. These include transactions related to bank charges, card maintenance fees, alert charges, or bank commission fees.

In some cases the Spending Patterns Engine cannot clearly assign data points and keywords to any of the spending categories. When data is too ambiguous to categorize into a certain spending category, the NLU assigns the transactions into additional pattern groups like transfers, cash_withdrawals, ussd_payments, or pos_web_payments.


Payment methods

Payment methods are data points that show the payment channel and the amount of each transaction. This data consists of:

  • Payment method keywords that show whether a particular debit transaction was via ATM, web or PoS, mobile or web application, or USSD.
  • Transaction amounts that are used to calculate sums, percentages, and amount of times a specific payment method is used.

How to use

Okra recommends that you leverage the Spending Patterns API in this order:

  1. Use the process spending patterns operation to analyze the transaction data of a user.

The response of this operation contains processed data split into spending categories and payment methods.

  1. Use the get spending patterns operations to retrieve already processed spending pattern data faster.

The get by ID and get by customer operations enable you to fetch data for a single user. You can also utilize the get by record and get by date operations to retrieve data in bulk for multiple users. You can even retrieve spending pattern data for all users in your project in a single request through the get all operation.


Key features of the Spending Patterns API

Evaluating Spending Patterns Models

The Spending Patterns API combines two machine learning models to classify transactions into spending patterns and payment methods groups. The API uses a confidence score to indicate an estimated level of accuracy in classifying transaction data. The confidence score is the number of correctly classified transactions expressed as a percentage.

The NLU uses accuracy, recall, and precision to evaluate the performance of the system by deriving values from a confusion matrix. The NLU uses separate confusion matrices for spending patterns and for payment methods.

  • TP: True positive - the number of transactions correctly classified into any of the spending categories
  • FN: False Negative - the number of transactions incorrectly classified as not part of any of the spending categories
  • FP: False Positive - the number of transactions incorrectly classified into any of the spending categories
  • TN: True Negative - the number of transactions correctly classified as not part of any of the spending categories

📘

Spending patterns confidence score = (TP + TN) / (FP + FN + TP + TN) * 100

  • TP: True positive - the number of transactions correctly classified as any of the known payment methods
  • FN: False Negative - the number of transactions incorrectly classified as different from the known payment methods
  • FP: False Positive - the number of transactions incorrectly classified as any of the known payment methods
  • TN: True Negative - the number of transactions correctly classified as different from the known payment methods

📘

Payment method confidence score = (TP + TN) / (TP + TN + FP + FN) * 100

Based on the resulting confidence scores, the API calculates an average confidence score to indicate an estimated level of accuracy in classifying transaction data. This average confidence score is the weighted sum of the spending patterns and payment methods confidence score. The weighting indicators alpha and beta represent the number of transactions classified as either a spending pattern or a payment method, expressed as decimal percentages. For example, if 55 out of your user’s 100 transactions are classified as spending patterns, then alpha = 0.55.

📘

Average confidence score = (alpha * Spending patterns confidence) + (beta * Payment method confidence)


Attributes of the spending patterns objects

The Spending Patterns API returns these objects:

AttributeTypeDescription
summaryobjectProvides an overview of the transactions that the API uses for calculating spending patterns.
breakdownarray of objectsProvides details about each spending category and payment method that the API processed.

Attributes within summary

AttributeTypeDescription
confidencefloatShows estimated level of accuracy in classifying transaction data into spending categories and payment methods.
cashflowfloatReturns the calculated difference between total_inflow and total_outflow. This number can be negative.
timeline_in_monthsintegerShows the total number of months for which the API calculates the spending patterns.
total_inflowfloatDenotes the total credit amount for an account within a set timeline.
total_outflowfloatDenotes the total debit amount for an account within a set timeline.
total_transactionsintegerShows the total number of debit transactions for an account within a set timeline.
transactions_recognizedintegerDenotes the number of transactions that the API accurately recognized and classified into an appropriate category.

Attributes within breakdown

AttributeTypeDescription
spending_categoriesobjectProvides high-level details about transactions that belong to the same spending category.
payment_methodsobjectProvides high-level details about transactions that used the same payment method.

Attributes within spending_categories

The Spending Patterns API groups transaction data into spending categories. The spending_categories object returns this data, grouped by spending categories. Each spending category object has these attributes:

AttributeTypeDescription
typestring, enumIdentifies a spending category. Click to see the list of spending categories.
detailsobjectReturns numeric details of a user’s transactions that belong to the same spending category.

Attributes of details

AttributeTypeDescription
countintegerDenotes the total number of transactions classified into a specific spending category.
percentagefloatShows the percentage of your users’ total expenses that belong to a specific spending category.
sumfloatDenotes the total amount of money that was spent in a specific spending category.

Attributes within payment_methods

The Spending Patterns API determines what payment methods were used in the user’s transaction history. The payment_methods object returns this data, grouped by payment methods. Each payment method object has these attributes:

AttributeTypeDescription
typestring, enumIdentifies a payment method. Possible values: atm, mobile_web_app, ussd, web_pos.
detailsobjectReturns numeric details of a user’s transactions that used the same payment method.

Attributes of details

AttributeTypeDescription
countintegerDenotes the total number of transactions classified into a specific payment method.
percentagefloatShows the percentage of your users’ total expenses that this payment method was used in.
sumfloatDenotes the total amount of money that was spent through this payment method.

Sample objects

Process spending patterns

curl -X POST https://api.okra.ng/v2/spending-patterns/simple
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <AccessToken>'
-d '{
    "customer_id": "614220f94833f507dc0dd9da"
    }'
{
    "data": {
        "spending_pattern": {
            "summary": {
                "cashflow": 50.97,
                "confidence": 99.92,
                "timeline_in_months": 24,
                "total_inflow": 2671075.77,
                "total_outflow": 2671024.8,
                "total_transactions": 728,
                "transactions_recognized": 728
            },
            "breakdown": {
                "payment_methods": [
                    {
                        "details": {
                            "count": 272,
                            "percentage": 50.16,
                            "sum": 1080154.69
                        },
                        "type": "ussd"
                    },
                    {
                        "details": {
                            "count": 340,
                            "percentage": 27.37,
                            "sum": 589554.35
                        },
                        "type": "mobile_web_app"
                    },
                    {
                        "details": {
                            "count": 116,
                            "percentage": 22.47,
                            "sum": 483844
                        },
                        "type": "web_pos"
                    }
                ],
                "spending_categories": [
                    {
                        "details": {
                            "count": 126,
                            "percentage": 60.3,
                            "sum": 1298510.75
                        },
                        "type": "transfers"
                    },
                    {
                        "details": {
                            "count": 464,
                            "percentage": 1.38,
                            "sum": 29880.02
                        },
                        "type": "miscellaneous"
                    },
                    {
                        "details": {
                            "count": 116,
                            "percentage": 25.47,
                            "sum": 548483.27
                        },
                        "type": "food"
                    },
                    {
                        "details": {
                            "count": 22,
                            "percentage": 12.84,
                            "sum": 276600
                        },
                        "type": "savings_investment"
                    }
                ]
            },
            "projects": [
                "1ff62b99aea7a57a5c3baa01"
            ],
            "records": [
                "13d929755427220b4befb1bb"
            ],
            "_id": "13d9297994ecb0cb5b9257b2",
            "customer": "116febac3f956e001e5b4854",
            "env": "production",
            "__v": 0,
            "created_at": "2023-02-07T16:10:00.059Z",
            "last_updated": "2023-02-07T16:10:00.059Z"
        },
        "record": "13d929755427220b4befb1bb",
        "receipt": {
            "status": true,
            "msg": "Receipt has been successfully created",
            "data": {
                "receipt": {
                    "adjustment": {
                        "receipts": []
                    },
                    "charge_breakdown": {
                        "vat": 0
                    },
                    "breakdown": {
                        "discount": 0,
                        "billable_products": []
                    },
                    "billingStatus": true,
                    "adjusted": null,
                    "adjusted_receipt": false,
                    "paid": false,
                    "fixed": false,
                    "adjusted_type": null,
                    "method": "wallet",
                    "charge": 62.25,
                    "wallet_balance": 40073.85,
                    "addons": [],
                    "archived": false,
                    "micro_lending": false,
                    "ussd_pricing": false,
                    "ussd_pricing_discount": 0,
                    "micro_lending_discount": 0,
                    "_id": "13d9297b5427220b4befb1bd",
                    "plan_term": "postpaid",
                    "owner": "5da6358130a943486f33dced",
                    "type": "spending-pattern",
                    "currency": "NGN",
                    "plan": "payg",
                    "plan_type": "1da478aa9ce2295ff32a5131",
                    "record": "13e277d45e94b5001103cc72",
                    "created_at": "2023-02-07T16:10:00.121Z",
                    "last_updated": "2023-02-07T16:10:00.121Z",
                    "__v": 0
                }
            }
        }
    }
}

For more request and response examples, check out the /spending-patterns endpoint in the API reference.