Skip to main content
POST
/
api
/
transactions
Create Transaction
curl --request POST \
  --url https://api.example.com/api/transactions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": {},
  "amount": 123,
  "accountId": "<string>",
  "currency": "<string>",
  "description": "<string>",
  "date": "<string>",
  "categoryId": "<string>"
}
'
{
  "400": {},
  "401": {},
  "404": {},
  "id": "<string>",
  "type": "<string>",
  "amount": 123,
  "currency": "<string>",
  "description": "<string>",
  "date": "<string>",
  "userId": "<string>",
  "accountId": "<string>",
  "categoryId": "<string>",
  "account": {},
  "category": {},
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>"
}

​
Authentication

This endpoint requires authentication using a Bearer token.
​
Authorization
string
required
Bearer token for authentication

​
Request Body

​
type
enum
required
Type of transaction
​
amount
number
required
Transaction amount (must be greater than 0.01, max 2 decimal places)
​
accountId
string
required
UUID of the account where the transaction impacts
​
currency
string
default:"ARS"
Currency code (3 characters max). Must match the account’s currency.
​
description
string
Description of the transaction (max 500 characters)
​
date
string
ISO 8601 date string for when the transaction occurred
​
categoryId
string
UUID of the category to associate with this transaction

​
Validation Rules

  • Amount: Must be at least 0.01 with maximum 2 decimal places
  • Type: Must be one of: INCOME, EXPENSE, or TRANSFER
  • Currency: Must match the account’s currency if provided
  • Sufficient Funds: For EXPENSE or TRANSFER transactions, the account must have sufficient balance
  • Category Coherence: If a category is provided, its type must match the transaction type (or be “BOTH”)

​
Response

​
id
string
Unique identifier for the created transaction
​
type
string
Transaction type (INCOME, EXPENSE, or TRANSFER)
​
amount
number
Transaction amount
​
currency
string
Currency code
​
description
string
Transaction description
​
date
string
Transaction date in ISO 8601 format
​
userId
string
ID of the user who owns this transaction
​
accountId
string
ID of the associated account
​
categoryId
string
ID of the associated category (if any)
​
account
object
Full account object including updated balance
​
category
object
Full category object (if categoryId was provided)
​
createdAt
string
Timestamp when the transaction was created
​
updatedAt
string
Timestamp when the transaction was last updated
​
deletedAt
string
Soft delete timestamp (null for active transactions)

​
Error Responses

​
400
error
Bad Request - Validation failed or business rule violation
  • Insufficient funds
  • Currency mismatch
  • Invalid category type
  • Amount too small or invalid format
​
401
error
Unauthorized - Missing or invalid authentication token
​
404
error
Not Found - Account or category not found or doesn’t belong to user

​
Example Request

curl -X POST https://api.yourfinanceapp.com/api/transactions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "EXPENSE",
    "amount": 1500.75,
    "currency": "ARS",
    "description": "Compra de comestibles",
    "date": "2026-03-04T14:30:00.000Z",
    "categoryId": "92b77be3-a14a-462c-a291-7eff27cbcf47",
    "accountId": "uuid-de-la-cuenta"
  }'

​
Example Response

{
  "id": "a3c4e8f2-9d7b-4a1c-8e3f-2b5d9a7c1e4f",
  "type": "EXPENSE",
  "amount": 1500.75,
  "currency": "ARS",
  "description": "Compra de comestibles",
  "date": "2026-03-04T14:30:00.000Z",
  "userId": "user-uuid-123",
  "accountId": "uuid-de-la-cuenta",
  "categoryId": "92b77be3-a14a-462c-a291-7eff27cbcf47",
  "account": {
    "id": "uuid-de-la-cuenta",
    "name": "Cuenta Principal",
    "type": "WALLET",
    "balance": 8499.25,
    "currency": "ARS"
  },
  "category": {
    "id": "92b77be3-a14a-462c-a291-7eff27cbcf47",
    "name": "Alimentos",
    "type": "EXPENSE",
    "icon": "🛒"
  },
  "createdAt": "2026-03-04T14:30:15.123Z",
  "updatedAt": "2026-03-04T14:30:15.123Z",
  "deletedAt": null
}

Build docs developers (and LLMs) love

Get started for freeTalk to us