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
Category | Description |
---|---|
Debt | Debit transactions that are repayments of loans or mortgages. |
Food | Food and food-related expeneses. Restaurants, groceries, and take-outs belong to this category. |
Entertainment | Transactions spent on entertainment activities such as club entrance fees or movie tickets. |
Gambling | Transactions spent on gambling activities such as lottery or BetWay. |
Gifts | Expenses such as Christmas gifts or gift cards. |
Donations | Transactions that are of charitable nature, such as tithes, Sunday offerings, church pledges, or donations to charities. |
Savings | Tracks keywords related to investments and savings, such as fixed deposits, trust funds, and ajo savings. |
Housing | Transactions spent on rent, mortgages, home decor, plumbing, gardening, or similar. |
Medical | Groups medical expenses such as hospital bills or pharmacy bills. |
Travel | Transactions spent on flight tickets, hotel reservations, or similar. |
Utilities | Transactions spent on utilities such as internet access, cable TV, or power bills. |
Insurance | Groups insurance related expenses and transactions. |
Transportation | Collects transportation expenses such as BRT subscriptions, Uber, and Bolt receipts. |
Personal care | Groups transactions related to selfcare, such as gym membership or spa fees. |
Taxes | Tax-related expenses. |
Pet | Collects expenses such as pet food or veterinary services. |
Subscriptions | Collects subscription fees for services such as Netflix, Spotify, Apple Music, or Prime Video. |
Family | Collects expenses related to the household and family. These include school fees, toys, diapers, nursery fees, or allowance. |
Miscellaneous | Collects 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:
- 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.
- 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:
Attribute | Type | Description |
---|---|---|
summary | object | Provides an overview of the transactions that the API uses for calculating spending patterns. |
breakdown | array of objects | Provides details about each spending category and payment method that the API processed. |
Attributes within summary
summary
Attribute | Type | Description |
---|---|---|
confidence | float | Shows estimated level of accuracy in classifying transaction data into spending categories and payment methods. |
cashflow | float | Returns the calculated difference between total_inflow and total_outflow . This number can be negative. |
timeline_in_months | integer | Shows the total number of months for which the API calculates the spending patterns. |
total_inflow | float | Denotes the total credit amount for an account within a set timeline. |
total_outflow | float | Denotes the total debit amount for an account within a set timeline. |
total_transactions | integer | Shows the total number of debit transactions for an account within a set timeline. |
transactions_recognized | integer | Denotes the number of transactions that the API accurately recognized and classified into an appropriate category. |
Attributes within breakdown
breakdown
Attribute | Type | Description |
---|---|---|
spending_categories | object | Provides high-level details about transactions that belong to the same spending category. |
payment_methods | object | Provides high-level details about transactions that used the same payment method. |
Attributes within spending_categories
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:
Attribute | Type | Description |
---|---|---|
type | string, enum | Identifies a spending category. Click to see the list of spending categories. |
details | object | Returns numeric details of a user’s transactions that belong to the same spending category. |
Attributes of details
details
Attribute | Type | Description |
---|---|---|
count | integer | Denotes the total number of transactions classified into a specific spending category. |
percentage | float | Shows the percentage of your users’ total expenses that belong to a specific spending category. |
sum | float | Denotes the total amount of money that was spent in a specific spending category. |
Attributes within payment_methods
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:
Attribute | Type | Description |
---|---|---|
type | string, enum | Identifies a payment method. Possible values: atm , mobile_web_app , ussd , web_pos . |
details | object | Returns numeric details of a user’s transactions that used the same payment method. |
Attributes of details
details
Attribute | Type | Description |
---|---|---|
count | integer | Denotes the total number of transactions classified into a specific payment method. |
percentage | float | Shows the percentage of your users’ total expenses that this payment method was used in. |
sum | float | Denotes 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.
Updated 4 months ago