> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Transactions Overview
> Transactions represent any instance in which money moves into or out of an account.
This could be a purchase at a business, a payroll deposit, a transfer from one account to another, an ATM withdrawal, and so on. Transactions are created automatically when a member is successfully aggregated.
Each `transaction` belongs to only one `account`.
With these endpoints you can:
* List transactions by account, by member, by tag.
* List all transactions associated with a user.
* Read and update a transaction.
* (With Extended Transaction History) Access up to 24 months of data associated with a particular member for some institutions.
* Split a transaction and create two or more child transactions that are branched from a previous transaction.
* Create a manual transaction associated with a manual account.
* Delete a manual transaction, a transaction rule, or a split transaction.
## Transactions Fields
| Field | Data Type | Description |
| :-------------------------- | :-------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_guid` | String | The unique identifier for the `account` associated with the `transaction`. Defined by MX. |
| `account_id` | String | The unique partner-defined identifier for the `account` associated with the `transaction`. This can only be set for partner-managed accounts. It should be ignored for user-managed transactions, even in occasional cases where it may return with a value. |
| `amount` | Decimal | The monetary amount of the `transaction`. |
| `category` | String | The category of the `transaction`. |
| `category_guid` | String | The unique identifier for the `category` assigned to the `transaction`. |
| `check_number_string` | String | The check number for the `transaction`. |
| `created_at` | String | The date and time the `transaction` was created. |
| `currency_code` | String | The three-character ISO 4217 currency code, e.g. `USD`. |
| `date` | String | The date on which the transaction took place. This is the field used when searching for transactions by date. This field is generally the same as `transacted_at`, but uses `posted_at` as a fallback. |
| `description` | String | A human-readable version of the `original_description` field described below, for example "Grocery World," "Jim's Bar and Tavern." This is provided by the MX Platform. |
| `guid` | String | The unique identifier for the `transaction`. Defined by MX. |
| `id` | String | The unique partner-defined identifier for the `transaction`. This can only be set for partner-managed transactions. It should be ignored for user-managed transactions, even in occasional cases where it may return with a value. |
| `is_bill_pay` | Boolean | This indicates whether the `transaction` represents a bill pay. |
| `is_direct_deposit` | Boolean | This indicates whether the `transaction` represents a direct deposit. |
| `is_expense` | Boolean | This indicates whether the `transaction` represents an expense. |
| `is_fee` | Boolean | This indicates whether the `transaction` represents a fee. |
| `is_income` | Boolean | This indicates whether the `transaction` represents income. |
| `is_international` | Boolean | If the transaction is international as defined by the data provider, this field will be `true`. If the data provider determines it is not international then it will be `false`. It will be `null` if the data provider does not have this information. |
| `is_manual` | Boolean | This indicates whether the transaction is manually created and belongs to a manual account. |
| `is_overdraft_fee` | Boolean | This indicates whether the `transaction` represents an overdraft fee. |
| `is_payroll_advance` | Boolean | This indicates whether the `transaction` represents a payroll advance. |
| `is_recurring` | Boolean | **This field should be ignored. If this information is required, please reach out to MX to discuss an alternative.** |
| `is_subscription` | Boolean | This indicates whether the transaction represents a payment for a subscription service such as Netflix or Audible. |
| `latitude` | Decimal | The latitude of the location where the `transaction` occurred. The number is a signed decimal (for example Rio de Janeiro's latitude is -22.9027800 and Tokyo's latitude is 35.689488). |
| `localized_description` | String | A human-readable description of the transaction, provided in a local language. |
| `localized_memo` | String | Additional descriptive information about the transaction, provided in a local language. |
| `longitude` | Decimal | The longitude of the location where the `transaction` occurred. The number is a signed decimal (for example Rio de Janeiro's longitude is -43.2075000 and Tokyo's is 139.691706). |
| `member_guid` | String | The unique identifier for the `member` associated with the `transaction` Defined by MX. |
| `member_is_managed_by_user` | Boolean | This indicates whether the associated `member` is managed by the user or the MX partner. Members created with the managed member feature will have this field set to false. |
| `memo` | String | This field contains additional descriptive information about the `transaction`. |
| `merchant_category_code` | Integer | The ISO 18245 category code for the transaction. |
| `merchant_guid` | String | The unique identifier for the `merchant` associated with this transaction. Defined by MX. |
| `merchant_location_guid` | String | The unique identifier for the `merchant_location` associated with this transaction. Defined by MX. |
| `original_description` | String | The original description of the transaction as provided by our data feed. See `description` above for more information. |
| `posted_at` | String | The date and time the transaction was posted to the account. |
| `status` | String | The status of the transaction. This will be either `POSTED` or `PENDING`. |
| `top_level_category` | String | The parent category assigned to this transaction's category. |
| `transacted_at` | String | The date and time the transaction took place. |
| `type` | String | The type of transaction. This will be either `CREDIT` or `DEBIT`. |
| `updated_at` | String | The date and time the transaction was last updated. |
| `user_guid` | String | The unique identifier for the `user` associated with this `transaction`. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the `user` associated with the `transaction`. |
## Transaction Statuses
The status field may either be `PENDING` or `POSTED`.
All transaction data on our systems represent what we get through our data feed which depends on what institutions make available for aggregation.
Many institutions do not provide data for pending transactions; transactions from those accounts always have a status of `POSTED`.
When we do receive data for pending transactions, a single transaction may be updated from `PENDING` to `POSTED` and keep the same `GUID`. This is done through various matching methods performed automatically by MX.
If a single transaction can't be updated, the `PENDING` transaction will often be deleted and replaced with a new `POSTED` transaction (with a new `GUID`) when it is sent to us; this is the most common scenario when pending data is available.
In unusual circumstances, there may be separate `PENDING` and `POSTED` transactions on MX systems for up to 14 days. All `PENDING` transactions are deleted after 14 days as a failsafe.
## Transaction Categories
* Auto Insurance
* Auto Payment
* Gas & Fuel
* Parking
* Public Transportation
* Ride Sharing
* Service & Parts
* Gas & Electric
* Internet
* Mobile Phone
* Phone
* Television
* Trash
* Water
* Advertising
* Legal
* Office Supplies
* Printing
* Shipping
* Books & Supplies
* Student Loan
* Tuition
* Arts
* Movies & DVDs
* Music
* Newspapers & Magazines
* Sports
* ATM Fee
* Bank Fee
* Finance Charge
* Late Fee
* Overdraft
* Service Fee
* Trade Commissions
* Financial Advisor
* Life Insurance
* Investment
* Alcohol & Bars
* Coffee Shops
* Fast Food
* Groceries
* Restaurants
* Charity
* Gift
* Dentist
* Doctor
* Eye Care
* Gym
* Health Insurance
* Pharmacy
* Sports
* Furnishings
* Home Improvement
* Home Insurance
* Home Services
* Home Supplies
* Lawn & Garden
* Mortgage & Rent
* Bonus
* Interest Income
* Paycheck
* Reimbursement
* Rental Income
* Buy
* Deposit
* Dividend & Cap Gains
* Sell
* Withdrawal
* Baby Supplies
* Babysitter & Daycare
* Child Support
* Kids Activities
* Toys
* Hair
* Laundry
* Spa & Massage
* Pet Food & Supplies
* Pet Grooming
* Veterinary
* Books
* Clothing
* Electronics & Software
* Hobbies
* Sporting Goods
* Federal Tax
* Local Tax
* Property Tax
* Sales Tax
* State Tax
* Credit Card Payment
* Transfer
* Air Travel
* Hotel
* Rental Car & Taxi
* Vacation
## Enhanced Transactions
The [Enhance Transactions endpoint](/api-reference/platform-api/reference/enhance-transactions), categorizes, cleanses, and classifies transactions. These transactions are not persisted or stored on the MX platform. Use this endpoint to:
* Improve customer insights by understanding spending behavior.
* Enhance transaction categorization with merchant details and classifications.
* Enable better financial forecasting through repeating transaction detection.
* Unlock more geolocation metadata.
### Enhanced Transaction Fields
| Field | Data Type | Definition |
| :-------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `amount` | Decimal | The monetary amount of the `transaction`. |
| `categorized_by` | Integer | The method used to determine the category assigned to the `transaction`. |
| `category` | String | The category of the `transaction`. |
| `category_guid` | String | The unique identifier for the `category` assigned to the `transaction`. |
| `described_by` | Integer | The method used to describe the `transaction`. |
| `description` | String | A human-readable version of the `original_description` field described below, for example "Sam's Club," "Johnny's Tavern." This is provided by the MX Platform. |
| `extended_transaction_type` | String | The transaction type assigned by the partner. |
| `id` | String | The unique partner-defined identifier for the `transaction`. |
| `is_bill_pay` | Boolean | This indicates whether the `transaction` represents a bill pay. |
| `is_direct_deposit` | Boolean | This indicates whether the `transaction` represents a direct deposit. |
| `is_expense` | Boolean | This indicates whether the `transaction` represents an expense. |
| `is_fee` | Boolean | This indicates whether the `transaction` represents a fee. |
| `is_income` | Boolean | This indicates whether the `transaction` represents income. |
| `is_international` | Boolean | If the transaction is international as defined by the data provider, this field will be `true`. If the data provider determines it is not international then it will be `false`. It will be `null` if the data provider does not have this information. |
| `is_overdraft_fee` | Boolean | This indicates whether the `transaction` represents an overdraft fee. |
| `is_payroll_advance` | Boolean | This indicates whether the `transaction` represents a payroll advance. |
| `is_subscription` | Boolean | This indicates whether the transaction represents a payment for a subscription service such as Netflix or Audible. |
| `memo` | String | This field contains additional descriptive information about the `transaction`. |
| `merchant_category_code` | Integer | The ISO 18245 category code for the transaction. |
| `merchant_guid` | String | The unique identifier for the `merchant` associated with this transaction. Defined by MX. |
| `merchant_location_guid` | String | The unique identifier for the `merchant_location` associated with this transaction. Defined by MX. |
| `original_description` | String | The original description of the transaction as provided by our data feed. See `description` above for more information. |
| `type` | String | The type of transaction. This will be either `CREDIT` or `DEBIT`. |
### Optional Enhancement Query Parameter
Append the `includes` query parameter to fetch additional transaction metadata:
* Repeating Transactions: Identifies transactions with predictable recurrence patterns (for example Bill, Income, Subscription)
* Merchants: Enhances transactions with merchant name
* Classifications: Provides more insight into the type of money movement that is occurring on the transaction, whether it be retail or investments.
* Geolocation: Provides geographic metadata to enhance fraud detection and customer analytics (beginning with state, soon to include city, zip)
**Opt-In Mechanism**
These updates do not affect existing API consumers. Clients can opt in to these enhancements by appending the includes query parameter to their transaction API requests.
Examples:
* To retrieve all available enhancements, append: `?includes=repeating_transactions,merchants,classifications,geolocations`
* You may also select specific enhancements. For example:
* To request only Repeating Transactions and Geolocation data: `?includes=repeating_transactions,geolocations`
* To request only Classification data: `?includes=classifications`
The appending add-on to the existing transaction endpoints can only be applied to:
* [List transactions by account](/api-reference/platform-api/reference/list-transactions-by-account)
* [List transactions by member](/api-reference/platform-api/reference/list-transactions-by-member)
* [List transactions by tag](/api-reference/platform-api/reference/list-transactions-by-tag)
* [List transactions](/api-reference/platform-api/reference/list-transactions)
* [Read transaction](/api-reference/platform-api/reference/read-transaction)
- The appending add-on is format sensitive.
- Clients can combine any subset of these enhancements as needed.
- These enhancements provide additional insights without modifying existing API behavior.
- The includes parameter supports future extensibility, allowing MX to introduce new optional fields without breaking compatibility.
### Enhanced Endpoints Data Fields
| Field | Type | Description |
| :--------------------------- | :----- | :--------------------------------------------------------------------------------------------------------------------------- |
| `guid` | String | Unique identifier for the repeating transaction, beginning with the prefix RPT- |
| `repeating_transaction_type` | Enum | Type of recurrence (for example BILL, SUBSCRIPTION, INCOME, UNKNOWN). |
| `recurrence_type` | Enum | The frequency at which a transaction is expected to repeat based on historical patterns. See Recurrence Types for full list. |
| Field | Type | Description |
| :------------ | :----- | :----------------------------------------------------------------- |
| `name` | String | Name of the merchant. |
| `guid` | String | Unique identifier for the merchant, beginning with the prefix MCH- |
| `logo_url` | String | The URL for a 100px x 100px logo for the merchant. |
| `website_url` | String | The URL for the merchant's website, such as `https://www.mx.com` |
| Field | Type | Description |
| :------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent_class` | String | Specifies the overarching category of the money movement within the transaction. See the full list of Classification Values and definitions below. |
| `guid` | String | Unique identifier for the classification, beginning with the prefix MNC- |
Classification values specify the overarching category of the money movement within the transaction.
| Value | Description |
| :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Payroll | Payroll deposits, typically from an employer or payroll provider. |
| Deposit | Money incoming from outside of the user's account(s). |
| Savings | Identified as money transfers tied to a savings account, including automated savings transfers or manual deposits to designated savings funds. |
| Transfer | Funds moved between accounts owned by the same individual. This is the default classification for non-specific transfers. |
| Refunds | Funds are credited back to the account, usually resulting from returns, merchant reversals, or reimbursements. |
| Spend | Identified as expenditures, including purchases at merchants or service providers. If a transaction cannot be assigned to a specific spending category, it defaults to this classification. |
| Investment | Related to investment accounts that do not fall under more specific classifications such as buy, sell, income, fees, or corporate actions. This classification includes general investment transactions and portfolio adjustments. |
| Buy | Asset purchases within an investment account. These transactions typically indicate the acquisition of securities, stocks, ETFs, or other financial instruments. |
| Sell | Asset sales within an investment account, representing the liquidation of previously acquired securities. |
| Income | Investment-related income, such as dividends, interest payments, or capital gains distributions. |
| Fees, Expenses | Charges incurred within an investment account, including brokerage fees, advisor fees, and other associated expenses. |
| Corporate Actions | Events initiated by publicly traded companies that impact security holders, including stock splits, mergers, and dividends. |
| Other | Transactions that do not fall into any predefined investment classification. This may include adjustments, transfers within investment accounts, or unclassified financial events. |
| Field | Type | Description |
| :------------ | :----- | :-------------------- |
| `country` | String | Country name. |
| `state` | String | State/Province name. |
| `city` | String | Region/city name. |
| `postal_code` | String | Postal code/zip code. |
## Repeating Transactions
Repeating Transactions empowers you to deliver insights into recurring financial obligations (bills, subscriptions) and income streams. By identifying patterns in transaction data, your users can gain clarity on cash flow, enabling proactive budgeting and personalized financial experiences.
* Dynamic Recurrence Detection: Automatically identifies transactions occurring 3+ times using machine learning.
* Predictive Analytics: Predicts upcoming expenses and income for improved budgeting.
* Multi-Channel Integration: Access via dedicated endpoints or enriched transaction data.
* The API supports a 13-month lookback period for historical data retrieval.
* Merchant must appear in ≥50 MX transactions to be considered repeatable.
### Repeating Transactions Endpoints
Available endpoints:
* [List Repeating Transactions](/api-reference/platform-api/reference/repeating-transactions)
* [Get a Repeating Transaction](/api-reference/platform-api/reference/specific-repeating-transaction)
### Repeating Transaction Fields
| Field | Type | Description |
| :--------------------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `guid` | String | Unique identifier for the repeating transaction, beginning with the prefix RPT-. Note: This field appears on transaction endpoints where the optional query parameter is defined. |
| `user_guid` | String | Unique identifier for the user. |
| `account_guid` | String | Associated account identifier. |
| `description` | String | Merchant or bill description. |
| `amount` | Number | Transaction amount. |
| `last_posted_date` | Date | Last occurrence date. |
| `predicted_occurs_on` | Date | Predicted next occurrence. |
| `transaction_type` | Enum | DEBIT or CREDIT. |
| `recurrence_type` | Enum | The frequency at which a transaction is expected to repeat based on historical patterns. See Supported Recurrence Types for full list. Note: This field appears on transaction endpoints where the optional query parameter is defined. |
| `repeating_transaction_type` | Enum | BILL, SUBSCRIPTION, INCOME, UNKNOWN. Note: This field appears on transaction endpoints where the optional query parameter is defined. |
| `merchant_guid` | String | Identifier for the associated merchant. |
### Supported Recurrence Types
| Recurrence Type | Description |
| :-------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
| `EVERY_WEEK` | The transaction occurs on a weekly basis. |
| `EVERY_OTHER_WEEK` | The transaction repeats every two weeks. |
| `TWICE_A_MONTH` | The transaction repeats twice a month. |
| `EVERY_MONTH` | The transaction occurs once a month, on or around the same date. |
| `EVERY_OTHER_MONTH` | The transaction repeats every two months. |
| `EVERY_QUARTER` | The transaction recurs every three months. |
| `EVERY_OTHER_QUARTER` | The transaction repeats every six months. |
| `EVERY_YEAR` | The transaction occurs annually on or around the same date. |
| `UNKNOWN` | The transaction is identified as recurring, but the system is unable to confidently determine a specific frequency pattern. |