--- updatedAt: 2026-09-24T13:30:26.000Z agentTools: projectIndex: https://developers.addepar.com/llms.txt --- # Transactions Transactions record the movement of value into and out of positions. Every buy, sell, contribution, distribution, and fee in a portfolio is a transaction. They are the source data for performance calculations, cost basis, and gain/loss reporting. Transactions always reference a position (via owner + owned entity relationships), and the sum of all transactions on a share-based or value-based position determines its current holding quantity. ![](https://files.readme.io/3aed8ff-Transactions.png "Transactions.png") ## How transactions work A transaction records a single financial event at a point in time. It connects to the ownership graph through three relationships: | Relationship | What it references | Required | | :-------------- | :------------------------------------------------------------------- | :------- | | `owner` | The entity that holds the position (e.g., an account) | Yes | | `owned` | The entity being traded or held (e.g., a stock) | Yes | | `cash_position` | The position between the owner and its cash entity (for cash impact) | No | The transaction `type` determines what kind of event occurred (buy, sell, contribution, distribution, etc.) and which fields are required. See [Transaction Types](/docs/transaction-types) for the full list with required fields per type. **Key constraint:** Transactions cannot target snapshots or valuations through this endpoint. Use the [Snapshots API](/docs/snapshots) for those. **Cancellation vs deletion:** Setting `cancellation: true` on a transaction reverses its financial effect and changes its type to "Cancellation," but preserves it in the audit trail. Deleting a transaction removes it entirely. Use cancellation for corrections that need to be traceable; use deletion for data entry errors that should not appear in any report. ## Overview | | | | :--------------- | :---------------------------------------------------------------------------------- | | **Base route** | `/v1/transactions` | | **Produces** | JSON | | **Pagination** | No (use [Transactions Query](/docs/transactions-query) for filtered bulk retrieval) | | **Batch limit** | 500 transactions per POST, PATCH, or DELETE request | | **OAuth scopes** | `TRANSACTIONS` or `TRANSACTIONS_WRITE` | > 📘 Access requirements > > **API Access:** Create, edit, and delete. > **Portfolio Access:** Determines which entities' transactions are accessible. > **Transaction permission:** Create, edit, and delete permissions required. > **Online transaction details:** Required to update and delete online (custodian-fed) transactions. ## Resource attributes | Attribute | Description | | :------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | **String** -- Transaction classification. See [Transaction Types](/docs/transaction-types). Example: `"buy"` | | `currency` | **String** -- ISO 4217 currency code for the cash side. Required. Example: `"USD"` | | `trade_date` | **String** -- Date the transaction occurred. Required. Format: `YYYY-MM-DD`. Example: `"2020-09-25"` | | `units` | **Number** -- Share count. Required for share-based assets. Example: `24.48` | | `amount` | **Number** -- Cash value. Required for valuations and value-based assets (except distributions and cash dividends). Example: `1000` | | `cancellation` | **Boolean** -- Whether this transaction is a cancellation. Setting to `true` reverses the transaction's effects. Example: `false` | | `vendor_id` | **String** -- Read-only after creation. Unique identifier from custodial data feed (auto-generated if not from a feed). Example: `"aca6bbdb-097f-46c0-b83a-709dfdae202b"` | | `created_at` | **String** -- Read-only. ISO 8601 timestamp. Example: `"2023-07-28T02:24:30Z"` | | `modified_at` | **String** -- Read-only. ISO 8601 timestamp. Example: `"2023-07-30T10:43:21Z"` | **Optional attributes:** | Attribute | Type | Description | | :---------------------------- | :-------- | :------------------------------------------------------------------------------ | | `posted_date` | String | Date the custodian reported the transaction. `YYYY-MM-DD`. | | `settlement_date` | String | Trade settlement date. `YYYY-MM-DD`. | | `ex_date` | String | Ex-dividend date. `YYYY-MM-DD`. | | `description` | String | Custodian-provided description. | | `price_factor` | Number | Multiplier affecting total security value. | | `fee` | Number | Total fees (sum of all fee breakdowns). | | `fee_breakdown` | Array | Itemized fees. Each entry has `fee_type` and `fee_amount`. See fee types below. | | `accrued` | Number | Accrued interest. | | `comment` | String | Free-text note. Max 4,000 chars for snapshots, 20,000 for all other types. | | `tags` | \[String] | Transaction categories. Append-only (cannot remove tags after creation). | | `affects_cost_basis` | Boolean | Whether the transaction affects cost basis (fees/expenses only). | | `affects_unfunded_commitment` | Boolean | Whether the transaction affects unfunded commitment (fees/expenses only). | | `affects_adjusted_value` | Boolean | Whether the transaction affects adjusted value (fees/expenses only). | **Distribution breakdown fields** (applicable when `type` is `"distribution"`): | Attribute | Description | | :------------------- | :------------------------------------------------------------------------- | | `generic` | Unspecified distribution amount | | `cap_gain` | Capital gain (unknown term) | | `long_term` | Long-term capital gains | | `short_term` | Short-term capital gains | | `interest` | Interest income | | `ordinary` | Ordinary income | | `dividend` | Dividend income | | `return_of_capital` | Return of capital | | `recallable` | Amount potentially liable to be returned (does not reduce paid-in capital) | | `recallable_paid_in` | Recallable amount that reduces paid-in capital | **Option fields:** `option_time_value`, `underlying_fee` (applicable to option transactions). ## Fee types | Fee type | API key | | :------------------------ | :----------------------- | | External Broker Fee | `external_brokerage_fee` | | Internal Broker Fee | `internal_brokerage_fee` | | Other Government Tax | `other_government_tax` | | Counterparty Fee | `counterparty_fee` | | Entry and Exit Fee | `entry_exit_fee` | | Foreign Fee | `foreign_fee` | | Matching/Confirmation Fee | `matching_fee` | | Market Fee | `market_fee` | | Market Tax | `market_tax` | | Other Fee | `other_fee` | | Stamp Duty | `stamp_tax` | | Stock Exchange Tax | `stock_exchange_tax` | | Stock Exchange Fee | `stock_exchange_fee` | | Turnover Fee | `turnover_fee` | | VAT | `value_added_tax` | | Withholding Tax | `withholding_tax` | ## Get a transaction **GET** `/v1/transactions/:id` ```bash Request curl -X GET "https://{firm}.addepar.com/api/v1/transactions/1968" \ -H "Authorization: Basic {credentials}" \ -H "Addepar-Firm: 1" \ -H "Accept: application/vnd.api+json" ``` ```json 200 Response { "data": { "id": "1968", "type": "transactions", "attributes": { "amount": 10000, "cancellation": false, "created_at": "2023-07-28T02:24:30Z", "currency": "USD", "modified_at": "2023-07-30T10:43:21Z", "type": "buy", "trade_date": "2019-01-02", "units": 100, "vendor_id": "aca6bbdb-097f-46c0-b83a-709dfdae202b" }, "relationships": { "owner": { "data": { "type": "entities", "id": "196" } }, "owned": { "data": { "type": "entities", "id": "200" } } }, "links": { "self": "/v1/transactions/1968" } }, "included": [] } ``` **Relationship endpoints:** | Endpoint | Returns | | :----------------------------------------------------- | :----------------------------- | | `GET /v1/transactions/:id/owner` | Full owner entity details | | `GET /v1/transactions/:id/owned` | Full owned entity details | | `GET /v1/transactions/:id/cash_position` | Cash position details | | `GET /v1/transactions/:id/relationships/owner` | Owner type and ID only | | `GET /v1/transactions/:id/relationships/owned` | Owned type and ID only | | `GET /v1/transactions/:id/relationships/cash_position` | Cash position type and ID only | ## Create transactions Creates one or more transactions. Pass a single object in `data` for one transaction, or an array for up to 500. **POST** `/v1/transactions` **Required fields:** `type`, `currency`, `trade_date`, plus `units` (share-based) or `amount` (value-based/valuations). **Buy example (share-based asset with fees):** ```bash Request curl -X POST "https://{firm}.addepar.com/api/v1/transactions" \ -H "Authorization: Basic {credentials}" \ -H "Addepar-Firm: 1" \ -H "Content-Type: application/vnd.api+json" \ -H "Accept: application/vnd.api+json" \ -d '{ "data": { "type": "transactions", "attributes": { "amount": 100010.0, "currency": "USD", "fee": 10.0, "fee_breakdown": [ { "fee_type": "EXTERNAL_BROKERAGE_FEE", "fee_amount": 3.0 }, { "fee_type": "GENERAL_FEE", "fee_amount": 7.0 } ], "trade_date": "2008-03-02", "type": "buy", "units": 1000.0 }, "relationships": { "owner": { "data": { "type": "entities", "id": "2138776" } }, "owned": { "data": { "type": "entities", "id": "2363267" } }, "cash_position": { "data": { "type": "positions", "id": "178" } } } } }' ``` **Distribution example (value-based asset):** ```bash Request curl -X POST "https://{firm}.addepar.com/api/v1/transactions" \ -H "Authorization: Basic {credentials}" \ -H "Addepar-Firm: 1" \ -H "Content-Type: application/vnd.api+json" \ -H "Accept: application/vnd.api+json" \ -d '{ "data": { "type": "transactions", "attributes": { "currency": "USD", "generic": 25000, "short_term": 2000, "trade_date": "2018-04-23", "type": "distribution" }, "relationships": { "owner": { "data": { "type": "entities", "id": "2260650" } }, "owned": { "data": { "type": "entities", "id": "2260679" } } } } }' ``` **Response codes:** * `201 Created` -- Transaction created successfully * `400 Bad Request` -- Invalid payload, unsupported type, or validation failure * `403 Forbidden` -- Insufficient permissions ## Edit transactions Updates one or more existing transactions. Pass a single object for one, or an array for up to 500. **PATCH** `/v1/transactions/:id` (single) or **PATCH** `/v1/transactions` (bulk) **Cannot be changed after creation:** `vendor_id`, `owner`, `owned`, `cash_position` relationships. For snapshots, `trade_date` also cannot be changed (it is part of the transaction identity). To remove an attribute value, set it to `null`. If a transaction has `fee_breakdown`, you must include the full breakdown in every update (partial updates to the breakdown array are not supported). ```bash Request curl -X PATCH "https://{firm}.addepar.com/api/v1/transactions/2083" \ -H "Authorization: Basic {credentials}" \ -H "Addepar-Firm: 1" \ -H "Content-Type: application/vnd.api+json" \ -H "Accept: application/vnd.api+json" \ -d '{ "data": { "id": "2083", "type": "transactions", "attributes": { "amount": 999.0, "comment": "Edited Comment", "trade_date": "2021-01-22", "units": 24.0 } } }' ``` **Response codes:** * `200 OK` -- Transaction updated successfully * `400 Bad Request` -- Invalid payload or validation failure * `403 Forbidden` -- Insufficient write permissions * `404 Not Found` -- Transaction does not exist or not accessible ## Delete transactions Permanently removes one or more transactions. Pass an ID in the URL for a single delete, or an array of `{ "id", "type": "transactions" }` objects for up to 500. **DELETE** `/v1/transactions/:id` (single) or **DELETE** `/v1/transactions` (bulk) Deletion is irreversible. If you need an audit trail, use cancellation (`PATCH` with `cancellation: true`) instead. ```bash Request curl -X DELETE "https://{firm}.addepar.com/api/v1/transactions/1968" \ -H "Authorization: Basic {credentials}" \ -H "Addepar-Firm: 1" \ -H "Accept: application/vnd.api+json" ``` ``` 204 No Content ``` **Response codes:** * `204 No Content` -- Transaction deleted * `403 Forbidden` -- Insufficient permissions * `404 Not Found` -- Transaction does not exist or not accessible * `409 Conflict` -- `type` field not specified as `"transactions"` ## Scale considerations The Transactions endpoint is not paginated and has a 500-item batch limit per request. For large-scale transaction operations: * **Bulk reads:** Use [Transactions Query](/docs/transactions-query) to filter and retrieve transactions across date ranges, entities, or types with pagination. * **Bulk writes (>500):** Use [Transaction Jobs](/docs/transaction-jobs) to submit CSV-based batch imports that process asynchronously without rate limit consumption during polling. * **Ongoing sync:** For custodian feeds that post hundreds of transactions daily, submit them in batches of 500 using the bulk POST endpoint. Pair with `vendor_id` to detect duplicates. *** > 📘 Related > > * [Transaction Types](/docs/transaction-types) -- Full list of transaction classifications with required fields > * [Transaction Jobs](/docs/transaction-jobs) -- Async batch import for large transaction volumes > * [Transactions Query](/docs/transactions-query) -- Filtered bulk retrieval with pagination > * [Positions](/docs/positions) -- The ownership links that transactions record activity against > * [Snapshots](/docs/snapshots) -- Point-in-time valuations (separate endpoint) > * [Rate Limiting](/docs/rate-limiting-1) -- Budget planning for transaction-heavy integrations