Docs

Create a transaction

POST /api/v1/programmatic/transactions

POST/api/v1/programmatic/transactions
Transactionsv1transactions:create

Creates one withdrawal, deposit, or transfer. The request is replay-safe per PAT and idempotency key.

Parameters

NameInType Description
Idempotency-KeyheaderstringRequired Unique 16–128 character retry key. Reuse it only when retrying the identical request. tx_20260722_01J2Y8M4R1

Request body

application/json

One posted withdrawal, deposit, or transfer. Account requirements depend on `type`.

{
  "type": "withdrawal",
  "date": "2026-07-12T12:00:00.000Z",
  "amount": "12.50",
  "description": "Lunch",
  "source_account_id": "<asset-account-id>"
}

Code examples

curl --request POST \
  --url 'https://api.tetri.app/api/v1/programmatic/transactions' \
  --header 'Authorization: Bearer $TETRI_API_TOKEN' \
  --header 'Idempotency-Key: tx_20260722_01J2Y8M4R1' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "withdrawal", "date": "2026-07-12T12:00:00.000Z", "amount": "12.50", "description": "Lunch", "source_account_id": "<asset-account-id>" }'

Responses

201Transaction created. The response includes cache side effects and mutation metadata.
{
  "data": {
    "type": "transactions",
    "id": "<uuid>",
    "attributes": {
      "revision": "2026-07-12T12:00:00Z",
      "group_title": "<string>",
      "execution_status": "scheduled",
      "executed_at": "2026-07-12T12:00:00Z",
      "archived_at": "2026-07-12T12:00:00Z",
      "is_archived": false,
      "created_by": {},
      "transactions": [
        {
          "transaction_journal_id": "<uuid>",
          "type": "withdrawal",
          "date": "2026-07-12T12:00:00Z",
          "occurred_at": "2026-07-12T12:00:00Z",
          "business_date": "2026-07-12",
          "timezone": "Europe/Tbilisi",
          "description": "Grocery shopping",
          "amount": "42.50",
          "foreign_amount": "45.00",
          "foreign_currency_code": "EUR",
          "foreign_currency_symbol": "€",
          "currency_code": "USD",
          "currency_symbol": "$",
          "currency_decimal_places": 2,
          "source_id": "<uuid>",
          "source_name": "<string>",
          "source_type": "asset",
          "destination_id": "<uuid>",
          "destination_name": "<string>",
          "destination_type": "expense",
          "category_id": "<uuid>",
          "category_name": "<string>",
          "budget_id": "<uuid>",
          "budget_name": "<string>",
          "tags": [
            "<string>"
          ],
          "notes": "<string>",
          "last_reconciled_at": "2026-07-12",
          "reconciled": false,
          "status": "posted",
          "estimated_rate": "1.05",
          "pending_rate_quote": {},
          "final_rate": "1.058",
          "settled_at": "2026-07-12T12:00:00Z",
          "splits": [
            {
              "id": "<uuid>",
              "amount": "42.50",
              "category_id": "<uuid>",
              "note": "<string>",
              "tag_ids": [
                "<uuid>"
              ]
            }
          ],
          "has_splits": false,
          "remainder": "0.00"
        }
      ]
    }
  },
  "meta": {
    "accounts_created": [
      {
        "wallet_id": "<uuid>",
        "account_id": "<uuid>",
        "currency_id": "<uuid>"
      }
    ]
  },
  "side_effects": [
    {
      "domain": "wallets",
      "id": "<string>",
      "action": "upsert",
      "data": {}
    }
  ]
}
400Request parameters or payload failed validation. Inspect `code` and `message`.
{
  "statusCode": 400,
  "code": "PROGRAMMATIC_PAGINATION_MODE_CONFLICT",
  "message": "<string>",
  "error": "Bad Request",
  "request_id": "8cf64dcc-0f73-4f8d-a845-3d80c1040475"
}
401The personal access token is missing, invalid, expired, or revoked.
{
  "statusCode": 400,
  "code": "PROGRAMMATIC_PAGINATION_MODE_CONFLICT",
  "message": "<string>",
  "error": "Bad Request",
  "request_id": "8cf64dcc-0f73-4f8d-a845-3d80c1040475"
}
403The token lacks the required scope or no longer has workspace access.
{
  "statusCode": 400,
  "code": "PROGRAMMATIC_PAGINATION_MODE_CONFLICT",
  "message": "<string>",
  "error": "Bad Request",
  "request_id": "8cf64dcc-0f73-4f8d-a845-3d80c1040475"
}
409The idempotency key was reused with a different request or the resource state conflicts.
{
  "statusCode": 400,
  "code": "PROGRAMMATIC_PAGINATION_MODE_CONFLICT",
  "message": "<string>",
  "error": "Bad Request",
  "request_id": "8cf64dcc-0f73-4f8d-a845-3d80c1040475"
}
429The credential exceeded its request rate limit.
{
  "statusCode": 400,
  "code": "PROGRAMMATIC_PAGINATION_MODE_CONFLICT",
  "message": "<string>",
  "error": "Bad Request",
  "request_id": "8cf64dcc-0f73-4f8d-a845-3d80c1040475"
}