Money transactions
Journal of income and expenses by account: posting amount, posting record and primary document.
Money transactions
Objects
MoneyTransaction
idintegerrequiredID of the record, unique among records of its kind in the store.
versionintegerrequiredVersion of the record: it grows with every change. Send it as the ETag in If-Match to change the record.
account_idintegerrequiredID of the money account of the movement.
directionstringrequiredincome — money into the account; expense — money out of the account.
- Values:
incomeexpense
amountintegerrequiredPosting amount in the minor units of the store currency, always positive: direction gives the sign. For a foreign-currency account it is converted at the snapshot rate.
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
account_amountstringrequiredAmount in the account currency, as a decimal string.
account_currencystringrequiredAccount currency: an ISO 4217 code or an asset (USDT).
exchange_ratestring or nullrequiredSnapshot rate: 1 unit of the account currency = exchange_rate units of the store currency, as a decimal string. null for an account in the store currency.
occurred_atstring (date-time)requiredMoment of the movement.
occurred_onstring (date)requiredAccounting date, YYYY-MM-DD in the store time zone.
category_idinteger or nullrequiredCategory ID; null for a transfer between accounts or a movement without a category.
supplier_idinteger or nullrequiredID of the supplier counterparty; null if there is none.
transfer_idinteger or nullrequiredShared ID of the legs of a transfer between accounts: the expense from one account and the income to the other carry the same one. null if not a transfer.
reverses_transaction_idinteger or nullrequiredID of the movement this one reverses; null for a regular movement.
originstringrequiredSource class: manual — entered by a person; sales; refunds; disputes; pos — register and safe; suppliers; payroll; statement — bank statement; opening_balance; exchange_differences; group_stores — operations of group stores on a shared account.
- Values:
manualstatementsalesrefundsdisputespossupplierspayrollopening_balanceexchange_differencesgroup_stores
sourceobject or nullrequiredThe record that posted the movement; null if entered manually.
Fields · 2
typestringrequiredPosting kind. payment and payment_* — a payment income and its parts (tip, surcharge, change, provider fee, withheld tax); refund — a refund payout; pos_* — register documents; supplier_bill_payment — a supplier bill payment; exchange_difference — an exchange difference.
- Values:
paymentpayment_tippayment_tip_refundpayment_surchargepayment_surcharge_refundpayment_overpaymentpayment_changepayment_change_counterpayment_provider_feepayment_provider_fee_refundpayment_withheld_taxpayment_withheld_tax_refundrefunddisputepos_shiftpos_shift_drawerpos_cash_transferpos_cash_transfer_counterpos_cash_shared_safepos_cash_shared_safe_counterpos_cash_movementpos_drawer_movementpos_cash_advance_expensepos_cash_advance_expense_voidpos_cash_bank_creditpos_cash_bank_credit_counterpos_cash_bank_credit_differencepayroll_periodpurchase_ordersupplier_bill_paymentsupplier_return_refundstatement_lineopening_balanceexchange_differencegroup_member_operation
idinteger or nullrequiredID of the source record: for payment and payment_* — the payment ID, for refund — an ID from the refund transactions[], for exchange_difference — the expense movement ID; for the others — an internal ID.
documentobject or nullrequiredPrimary document of the movement; null if entered manually or the document lives in the books of another group store.
Fields · 2
typestringrequiredDocument kind: order; pos_shift — register shift; supplier_bill; purchase_order; supplier_return; dispute; payroll — payroll period; pos_safe — register safe; statement_import — statement import; money_accounts — account opening balance.
- Values:
orderdisputepos_shiftpos_safepurchase_ordersupplier_billsupplier_returnpayrollstatement_importmoney_accounts
idinteger or nullrequiredDocument ID; null for registers without a record of their own: pos_safe, statement_import, money_accounts.
descriptionstring or nullrequiredMovement comment as a person or a document wrote it; null if there is none.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
Endpoints
List money transactions changed since a given moment: account income and expenses with their source and primary document
get/money-transactions
Scope: finance:read
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — also return deleted records: archived ones with deleted_at set, and records erased from the database as tombstones {id, deleted_at} in the continuation by the sync cursor. Turn it on for a sync.
account_idintegerOnly movements of this money account.
- Minimum:
- 1
transfer_idintegerOnly the legs of this transfer between accounts.
- Minimum:
- 1
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/money-transactions" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"version": 0,
"account_id": 0,
"direction": "income",
"amount": 0,
"currency": "string",
"account_amount": "string",
"account_currency": "string",
"exchange_rate": "string",
"occurred_at": "2026-01-15T12:00:00Z",
"occurred_on": "2026-01-15",
"category_id": 0,
"supplier_id": 0,
"transfer_id": 0,
"reverses_transaction_id": 0,
"origin": "manual",
"source": {
"type": "payment",
"id": 0
},
"document": {
"type": "order",
"id": 0
},
"description": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Record manual income or expense on a money account
post/money-transactions
Scope: finance:write
Parameters
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
account_idintegerrequiredID of the money account of the movement.
- Minimum:
- 1
directionstringrequiredincome — money into the account; expense — money out of the account.
- Values:
incomeexpense
account_amountstringrequiredAmount in the account currency, as a decimal string.
- Max length:
- 37
amountinteger or nullPosting amount in the minor units of the store currency, always positive: direction gives the sign. For a foreign-currency account it is converted at the snapshot rate.
- Minimum:
- 0
- Maximum:
- 100000000000000
occurred_onstring (date)Accounting date, YYYY-MM-DD in the store time zone.
occurred_atstring (date-time)Moment of the movement.
category_idinteger or nullCategory ID; null for a transfer between accounts or a movement without a category.
supplier_idinteger or nullID of the supplier counterparty; null if there is none.
descriptionstring or nullMovement comment as a person or a document wrote it; null if there is none.
- Max length:
- 1000
Responses
201Created
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns MoneyTransaction
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/money-transactions" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"account_id": 1,
"direction": "income",
"account_amount": "string",
"amount": 0,
"occurred_on": "2026-01-15",
"occurred_at": "2026-01-15T12:00:00Z",
"category_id": 0,
"supplier_id": 0,
"description": "string"
}{
"id": 0,
"version": 0,
"account_id": 0,
"direction": "income",
"amount": 0,
"currency": "string",
"account_amount": "string",
"account_currency": "string",
"exchange_rate": "string",
"occurred_at": "2026-01-15T12:00:00Z",
"occurred_on": "2026-01-15",
"category_id": 0,
"supplier_id": 0,
"transfer_id": 0,
"reverses_transaction_id": 0,
"origin": "manual",
"source": {
"type": "payment",
"id": 0
},
"document": {
"type": "order",
"id": 0
},
"description": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Get a money transaction
get/money-transactions/{transaction}
Scope: finance:read
Parameters
Path
transactionintegerrequiredID of the money transaction.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns MoneyTransaction
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/money-transactions/{transaction}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"version": 0,
"account_id": 0,
"direction": "income",
"amount": 0,
"currency": "string",
"account_amount": "string",
"account_currency": "string",
"exchange_rate": "string",
"occurred_at": "2026-01-15T12:00:00Z",
"occurred_on": "2026-01-15",
"category_id": 0,
"supplier_id": 0,
"transfer_id": 0,
"reverses_transaction_id": 0,
"origin": "manual",
"source": {
"type": "payment",
"id": 0
},
"document": {
"type": "order",
"id": 0
},
"description": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Update a money transaction: only the category, counterparty and description of a transaction with a source document
patch/money-transactions/{transaction}
Scope: finance:write
Parameters
Path
transactionintegerrequiredID of the money transaction.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Request body application/json
account_idintegerID of the money account of the movement.
- Minimum:
- 1
directionstringincome — money into the account; expense — money out of the account.
- Values:
incomeexpense
account_amountstringAmount in the account currency, as a decimal string.
- Max length:
- 37
amountinteger or nullPosting amount in the minor units of the store currency, always positive: direction gives the sign. For a foreign-currency account it is converted at the snapshot rate.
- Minimum:
- 0
- Maximum:
- 100000000000000
occurred_onstring (date)Accounting date, YYYY-MM-DD in the store time zone.
occurred_atstring (date-time)Moment of the movement.
category_idinteger or nullCategory ID; null for a transfer between accounts or a movement without a category.
supplier_idinteger or nullID of the supplier counterparty; null if there is none.
descriptionstring or nullMovement comment as a person or a document wrote it; null if there is none.
- Max length:
- 1000
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns MoneyTransaction
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
money_transaction_lockedThe transaction cannot be changed by hand - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X PATCH "https://api.saleya.app/v1/money-transactions/{transaction}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"account_id": 1,
"direction": "income",
"account_amount": "string",
"amount": 0,
"occurred_on": "2026-01-15",
"occurred_at": "2026-01-15T12:00:00Z",
"category_id": 0,
"supplier_id": 0,
"description": "string"
}{
"id": 0,
"version": 0,
"account_id": 0,
"direction": "income",
"amount": 0,
"currency": "string",
"account_amount": "string",
"account_currency": "string",
"exchange_rate": "string",
"occurred_at": "2026-01-15T12:00:00Z",
"occurred_on": "2026-01-15",
"category_id": 0,
"supplier_id": 0,
"transfer_id": 0,
"reverses_transaction_id": 0,
"origin": "manual",
"source": {
"type": "payment",
"id": 0
},
"document": {
"type": "order",
"id": 0
},
"description": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Delete a manual money transaction and restore the account balance
delete/money-transactions/{transaction}
Scope: finance:write
Parameters
Path
transactionintegerrequiredID of the money transaction.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Responses
204Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
No body
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
in_use_conflictRecord in use - 409
money_transaction_lockedThe transaction cannot be changed by hand - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X DELETE "https://api.saleya.app/v1/money-transactions/{transaction}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'