> ## 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
Transaction files are for creating and updating transactions that are managed by your institution for your users.
All date fields ending with `_on` are expected as an ISO 8601 formatted date only with no timestamp (for example, `2024-04-20`).
## Transaction Fields
| Field | Data Type (Max) | Description |
| :----------------------- | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_guid` | String | The unique identifier for the account this transaction belongs to. Defined by MX. |
| `account_id` | String | The unique partner-defined identifier for the account this transaction belongs to. |
| `amount` | Decimal | The amount is always unsigned. The `type` will determine how the transaction affects the account. Max length is 10,2. See [Number Limits](/api-reference/more-apis/batch-api#number-limits). |
| `category_guid` | String | The unique identifier for the transaction category. Defined by MX. |
| `category_name` | String | The transaction category given as a human-readable string. This may be null in a response. |
| `category` | String | The transaction category given as an enumerated value. This may be null in a response. If provided with a create or update request, it will be ignored if not valid for the user. If not provided with a create or update request, MX will categorize the transaction automatically. See [Default Categories](/api-reference/more-apis/mdx/mdx-real-time/reference/transactions/transaction-fields#transaction-categories) for a list of all transaction categories. |
| `check_number` | String | The check number. |
| `currency_code` | String | The ISO 4217 three-character currency code. |
| `description` | String | A human-readable description of the transaction. Max length is 1024.
**Warning:** Unescaped XML or JSON characters will a Real Time integration. See [Escaped Characters](/api-reference/more-apis/mdx/mdx-real-time/#escaped-characters) for more information. |
| `guid` | String | The unique identifier for the transaction. Defined by MX. |
| `id` | String | The unique partner-defined identifier for the transaction. The `id` can't begin with `TRN-` as this is reserved for the system. It must be unique for all transactions belonging to an account as it's used for matching purposes. Transactions should always be returned with the same ID, even if transactional information has changed (type, amount, description, dates) since the previous account synchronization. It's permissible for the transaction ID to change when a transaction changes from `PENDING` to `POSTED` status if the previous transaction ID can't be maintained. It can include numbers, letters, dash, and underscore. Max Length is 1024. |
| `is_international` | Boolean | This indicates whether the transaction is international, as determined by the data provider. Defaults to `null` when not provided. This field should only be set to `true` or `false` if the value is explicitly known by the data provider. Otherwise it should be omitted or set to `null`. |
| `latitude` | Decimal | The latitude of the location where the transaction occurred. The number is a signed decimal (e.g. 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 (e.g. Rio de Janeiro's longitude is -43.2075000 and Tokyo's longitude is 139.691706). |
| `member_guid` | String | The unique identifier for the member. Defined by MX. |
| `member_id` | String | The unique partner-defined identifier for the member. |
| `memo` | String | The memo is additional descriptive information about the transaction. Max length is 1024. |
| `merchant_category_code` | String | The merchant category code. |
| `merchant_guid` | String | The unique identifier for the merchant associated with the transaction. Defined by MX. |
| `merchant_location_guid` | String | The unique identifier for the merchant location associated with the transaction. Defined by MX. |
| `metadata` | String | Additional information you can store on the transaction. |
| `posted_at` | Integer | The date and time the transaction was posted. You're **required** to apply any applicable timezone offset to ensure Unix Epoch values are UTC-based. Each transaction is **required** to have a valid date for either `posted_at` or `posted_on` if the status is `POSTED`. Optional if the status is `PENDING`. |
| `posted_on` | String | The date the transaction was posted. Each transaction is required to have a valid date for either `posted_at` or `posted_on` if the status is `POSTED`. Optional if the status is `PENDING`. |
| `running_balance` | Decimal | The available balance of the related account at the time this transaction was posted. This field is only viable for transactions in the `POSTED` state. Max length is 14,2. See [Number Limits](/api-reference/more-apis/batch-api#number-limits). |
| `status` | String | One of `PENDING` or `POSTED`. A read request might contain a `null` status. |
| `transacted_at` | Integer | The date and time the transaction took place. You're **required** to apply any applicable timezone offset to ensure Unix Epoch values are UTC-based. Each transaction is required to have a valid date for either `transacted_at` or `transacted_on`. |
| `transacted_on` | String | The date the transaction took place. Each transaction is required to have a valid date for either `transacted_at` or `transacted_on`. |
| `type` | String | One of `DEBIT` or `CREDIT`. A `CREDIT` increases the user's net worth. A `DEBIT` decreases the user's net worth. This applies to all account types. |
| `user_guid` | String | The unique identifier for the user the transaction belongs to. Defined by MX. |
| `user_id` | String | The unique partner-defined identifier for the user associated with the transaction. |
## Transaction File Parameters
The `action` field tells us what data operation to perform for each row in the file. Options are `upsert` (an insert/update depending on if the object already exists) and `delete` (which will destroy the record). If no action is provided the default action is `upsert`.
The `skip_webhook` parameter prevents a webhook being sent for the action effected by each row. Accepted values are `true` or `false`. If `skip_webhook` is not provided, MX will default to your internal batch configuration setting.
| Field | Required for Upsert? | Required for Delete? | Type |
| :----------------------------------------------------------------------------- | :------------------- | :------------------- | :------ |
| `id` | **Yes** | **Yes** | String |
| `user_id` | **Yes** | **Yes** | String |
| `member_id` | **Yes** | **Yes** | String |
| `account_id` | **Yes** | **Yes** | String |
| `action` | **Yes** | No | String |
| `amount` | **Yes** | No | Decimal |
| `description` | **Yes** | No | String |
| `posted_at` (One of either `posted_at` or `posted_on` is required) | **Yes** | No | String |
| `posted_on` (One of either `posted_at` or `posted_on` is required) | **Yes** | No | String |
| `status` | **Yes** | No | String |
| `transacted_at` (One of either `transacted_at` or `transacted_on` is required) | **Yes** | No | String |
| `transacted_on` (One of either `transacted_at` or `transacted_on` is required) | **Yes** | No | String |
| `type` | **Yes** | No | String |
| `currency_code` | No | No | String |
| `is_international` | No | No | String |
| `latitude` | No | No | String |
| `longitude` | No | No | String |
| `memo` | No | No | String |
| `merchant_category_code` | No | No | String |
| `metadata` | No | No | String |
| `skip_webhooks` | No | No | Boolean |
## Sample File
The following is a sample Transactions batch CSV file.
```text CSV theme={null}
"action","id","user_id","member_id","account_id","amount","description","posted_on","status","transacted_on"
"upsert","T-1234-10112024","U-39XBF7","M-39XBF7","A-1234-Chk",12.00,"POS Walmart Pharmacy","2024-10-11","POSTED","2024-10-11"
"upsert","T-4567-10122024","U-39XBF7","M-39XBF7","A-1234-Chk",150.00,"Transfer to Savings",,"PENDING","2024-10-12"
```