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.

How transactions work

A transaction records a single financial event at a point in time. It connects to the ownership graph through three relationships:

The transaction type determines what kind of event occurred (buy, sell, contribution, distribution, etc.) and which fields are required. See 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 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

📘

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

Optional attributes:

Distribution breakdown fields (applicable when type is "distribution"):

Option fields: option_time_value, underlying_fee (applicable to option transactions).

Fee types

Get a transaction

GET /v1/transactions/:id

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"

{
  "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:

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):

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):

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).

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.

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 to filter and retrieve transactions across date ranges, entities, or types with pagination.
• Bulk writes (>500): Use 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 -- Full list of transaction classifications with required fields
• Transaction Jobs -- Async batch import for large transaction volumes
• Transactions Query -- Filtered bulk retrieval with pagination
• Positions -- The ownership links that transactions record activity against
• Snapshots -- Point-in-time valuations (separate endpoint)
• Rate Limiting -- Budget planning for transaction-heavy integrations