Transactions

Transactions are the core of Crane Ledger's double-entry accounting system. Each transaction represents a financial event that affects multiple accounts through balanced debit and credit entries.

The Transaction Object

GET/organizations/:organization_id/transactions/:id

Auth required

A transaction represents a financial event with balanced journal entries.

{
  "id": "txn_xxxxxxxxxxxxxxxx",
  "object": "transaction",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "type": "income",
  "reference_number": "INV-001",
  "description": "Cash sale to customer",
  "transaction_date": "2024-01-15",
  "posting_date": "2024-01-15T10:30:00Z",
  "status": "posted",
  "total_debits": "100.00",
  "total_credits": "100.00",
  "currency_id": "CUR_USD",
  "amount": "100.00",
  "account_id": "act_xxxxxxxxxxxxxxxx",
  "contact_id": "con_xxxxxxxxxxxxxxxx",
  "category_id": "cat_xxxxxxxxxxxxxxxx",
  "document_id": null,
  "document_type": null,
  "payment_method": "cash",
  "reconciled": false,
  "created_by": "usr_xxxxxxxxxxxxxxxx",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "source": "api",
    "batch_id": "batch_001"
  }
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier with `txn_` prefix
`organization_id`	string	The organization this transaction belongs to
`type`	string	Transaction type: `income`, `expense`, `transfer`
`reference_number`	string	User-provided reference number
`description`	string	Transaction description
`transaction_date`	date	Business date of the transaction
`posting_date`	datetime	When the transaction was posted
`status`	enum	`pending`, `posted`, `failed`, `reversed`
`total_debits`	string	Total debits in base currency
`total_credits`	string	Total credits in base currency
`currency_id`	string	Transaction currency
`amount`	string	Transaction amount
`account_id`	string	Primary account ID
`contact_id`	string	Related contact ID
`category_id`	string	Transaction category
`reconciled`	boolean	Whether transaction is reconciled
`metadata`	object	Additional transaction data

Create Transaction

POST/organizations/:organization_id/transactions

Auth required

2 credits

Creates a new transaction with journal entries. The entries must balance (total debits = total credits).

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The ID of the organization

Request Body

Parameter	Type	Required	Description
`description`	string	Yes	Transaction description
`transaction_date`	date	Yes	Business date (YYYY-MM-DD)
`currency_id`	string	Yes	Currency ID
`entries`	array	Yes	Array of journal entries
`type`	string	No	Transaction type (income, expense, transfer)
`reference_number`	string	No	Custom reference number
`contact_id`	string	No	Related contact ID
`category_id`	string	No	Category ID
`payment_method`	string	No	Payment method

Entry Structure

Each entry in the entries array:

Parameter	Type	Required	Description
`account_id`	string	Yes	Account ID to affect
`entry_type`	enum	Yes	`debit` or `credit`
`amount`	number	Yes	Entry amount (positive)
`description`	string	No	Line item description
`reference`	string	No	External reference

Response

{
  "request_id": "req_xxxxxxxxxxxxxxxx",
  "success": true,
  "data": {
    "status": "queued",
    "estimated_completion": "2024-01-15T10:30:05Z"
  },
  "error": null,
  "duration_ms": 0,
  "credit_cost": 2
}

List Transactions

GET/organizations/:organization_id/transactions

Auth required

Returns a list of transactions for the organization with optional filtering.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID

Query Parameters

Parameter	Type	Description
`status`	enum	Filter by status (`pending`, `posted`, `failed`, `reversed`)
`type`	string	Filter by type (`income`, `expense`, `transfer`)
`account_id`	string	Filter by account
`contact_id`	string	Filter by contact
`from_date`	date	Start date for transaction_date
`to_date`	date	End date for transaction_date
`limit`	integer	Number of results (default: 20, max: 100)
`offset`	integer	Pagination offset

Response

{
  "object": "list",
  "data": [
    {
      "id": "txn_xxxxxxxxxxxxxxxx",
      "description": "Cash sale to customer",
      "transaction_date": "2024-01-15",
      "status": "posted",
      "amount": "500.00",
      "type": "income",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "has_more": false,
  "total_count": 1
}

Get Transaction

GET/organizations/:organization_id/transactions/:id

Auth required

Retrieves the details of a specific transaction including all journal entries.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID
`id`	string	Yes	The transaction ID

Response

Returns the complete transaction object with all journal entries.

Update Transaction

PUT/organizations/:organization_id/transactions/:id

Auth required

1 credits

Updates an existing transaction. Only pending transactions can be modified.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID
`id`	string	Yes	The transaction ID

Request Body

Parameter	Type	Description
`description`	string	Transaction description
`transaction_date`	date	Business date
`reference_number`	string	Reference number
`contact_id`	string	Related contact
`category_id`	string	Category
`entries`	array	Updated journal entries

Pending Only

Only transactions with status pending can be updated. Posted transactions must be reversed and re-created.

Delete Transaction

DELETE/organizations/:organization_id/transactions/:id

Auth required

1 credits

Deletes a pending transaction. Posted transactions cannot be deleted.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID
`id`	string	Yes	The transaction ID

Post Transaction

POST/organizations/:organization_id/transactions/:id/post

Auth required

1 credits

Posts a pending transaction, making it final and affecting account balances.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID
`id`	string	Yes	The transaction ID

Response

{
  "request_id": "req_xxxxxxxxxxxxxxxx",
  "success": true,
  "data": {
    "status": "queued",
    "message": "Transaction posting queued"
  },
  "credit_cost": 1
}

Balance Validation

The system validates that total debits equal total credits before posting. Unbalanced transactions will fail to post.

Reverse Transaction

POST/organizations/:organization_id/transactions/:id/reverse

Auth required

2 credits

Reverses a posted transaction by creating an offsetting transaction with opposite entries.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID
`id`	string	Yes	The transaction ID

Request Body

Parameter	Type	Required	Description
`reason`	string	No	Reason for reversal
`reversal_date`	date	No	Date for reversal (defaults to today)

Response

{
  "request_id": "req_xxxxxxxxxxxxxxxx",
  "success": true,
  "data": {
    "status": "queued",
    "message": "Transaction reversal queued",
    "reversal_transaction_id": "txn_yyyyyyyyyyyyyyyy"
  },
  "credit_cost": 2
}

Transaction Lifecycle

Status Flow

pending → posted → reversed
   ↓        ↓
 failed   (final)

Status Descriptions

Status	Description	Actions Available
`pending`	Draft transaction awaiting posting	Edit, delete, post
`posted`	Final transaction affecting balances	Reverse only
`failed`	Transaction failed validation	Edit and retry, delete
`reversed`	Transaction has been reversed	View only

Double-Entry Validation

All transactions must satisfy the fundamental accounting equation:

Total Debits = Total Credits

Example: Complete Transaction

{
  "description": "Purchase office supplies with credit card",
  "transaction_date": "2024-01-15",
  "currency_id": "CUR_USD",
  "entries": [
    {
      "account_id": "act_office_supplies_5100",
      "entry_type": "debit",
      "amount": 250.00,
      "description": "Office supplies expense"
    },
    {
      "account_id": "act_credit_card_2100",
      "entry_type": "credit",
      "amount": 250.00,
      "description": "Credit card payable"
    }
  ]
}

Multi-Entry Transaction

Complex transactions can have multiple entries:

{
  "description": "Customer payment with discount",
  "entries": [
    {
      "account_id": "act_cash_1000",
      "entry_type": "debit",
      "amount": 950.00,
      "description": "Cash received"
    },
    {
      "account_id": "act_sales_discount_4200",
      "entry_type": "debit",
      "amount": 50.00,
      "description": "Sales discount given"
    },
    {
      "account_id": "act_accounts_receivable_1100",
      "entry_type": "credit",
      "amount": 1000.00,
      "description": "Clear customer balance"
    }
  ]
}

Validation: 950 + 50 = 1000 ✓

Common Transaction Patterns

Revenue Recognition

{
  "type": "income",
  "description": "Service revenue",
  "entries": [
    {"account_id": "act_ar", "entry_type": "debit", "amount": 1000.00},
    {"account_id": "act_revenue", "entry_type": "credit", "amount": 1000.00}
  ]
}

Expense Recording

{
  "type": "expense",
  "description": "Rent payment",
  "entries": [
    {"account_id": "act_rent_expense", "entry_type": "debit", "amount": 2000.00},
    {"account_id": "act_cash", "entry_type": "credit", "amount": 2000.00}
  ]
}

Asset Purchase

{
  "description": "Equipment purchase",
  "entries": [
    {"account_id": "act_equipment", "entry_type": "debit", "amount": 5000.00},
    {"account_id": "act_cash", "entry_type": "credit", "amount": 5000.00}
  ]
}

Need help?

Create a free account to access our support portal. Once signed in, use the Support tab in your dashboard to submit a support ticket — our team typically responds within 24 hours.

✨ For LLMs/AI assistants: Read our structured API reference