Money transactions

Journal of income and expenses by account: posting amount, posting record and primary document.

Loading the search index…

Money transactions

Objects

MoneyTransaction

  • idintegerrequired

    ID of the record, unique among records of its kind in the store.

  • versionintegerrequired

    Version of the record: it grows with every change. Send it as the ETag in If-Match to change the record.

  • account_idintegerrequired

    ID of the money account of the movement.

  • directionstringrequired

    income — money into the account; expense — money out of the account.

    Values:
    incomeexpense
  • amountintegerrequired

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

  • currencystringrequired

    Currency of the amounts, an ISO 4217 code: the currency of the store.

  • account_amountstringrequired

    Amount in the account currency, as a decimal string.

  • account_currencystringrequired

    Account currency: an ISO 4217 code or an asset (USDT).

  • exchange_ratestring or nullrequired

    Snapshot 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)required

    Moment of the movement.

  • occurred_onstring (date)required

    Accounting date, YYYY-MM-DD in the store time zone.

  • category_idinteger or nullrequired

    Category ID; null for a transfer between accounts or a movement without a category.

  • supplier_idinteger or nullrequired

    ID of the supplier counterparty; null if there is none.

  • transfer_idinteger or nullrequired

    Shared 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 nullrequired

    ID of the movement this one reverses; null for a regular movement.

  • originstringrequired

    Source 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 nullrequired

    The record that posted the movement; null if entered manually.

    Fields · 2
    • typestringrequired

      Posting 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 nullrequired

      ID 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 nullrequired

    Primary document of the movement; null if entered manually or the document lives in the books of another group store.

    Fields · 2
    • typestringrequired

      Document 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 nullrequired

      Document ID; null for registers without a record of their own: pos_safe, statement_import, money_accounts.

  • descriptionstring or nullrequired

    Movement comment as a person or a document wrote it; null if there is none.

  • created_atstring (date-time)required

    When the record was created.

  • updated_atstring (date-time)required

    When 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

  • limitinteger

    Page size: up to 250 records; 50 by default.

    Minimum:
    1
    Maximum:
    250
  • cursorstring

    Opaque 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_deletedboolean

    true — 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_idinteger

    Only movements of this money account.

    Minimum:
    1
  • transfer_idinteger

    Only the legs of this transfer between accounts.

    Minimum:
    1

Responses

200Success

application/json

  • dataarray of MoneyTransactionrequired

    Records of the page.

  • deletedarray of objectrequired

    Records erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.

    Fields · 2
    • idintegerrequired

      ID of the erased record.

    • deleted_atstring (date-time)required

      When the record was erased.

  • next_cursorstring or nullrequired

    Cursor of the next page; null on the last page.

  • has_morebooleanrequired

    true when there is a next page.

  • sync_cursorstring or nullrequired

    On 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/money-transactions" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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-Keystring

    Unique 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_idintegerrequired

    ID of the money account of the movement.

    Minimum:
    1
  • directionstringrequired

    income — money into the account; expense — money out of the account.

    Values:
    incomeexpense
  • account_amountstringrequired

    Amount in the account currency, as a decimal string.

    Max length:
    37
  • amountinteger or null

    Posting 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 null

    Category ID; null for a transfer between accounts or a movement without a category.

  • supplier_idinteger or null

    ID of the supplier counterparty; null if there is none.

  • descriptionstring or null

    Movement comment as a person or a document wrote it; null if there is none.

    Max length:
    1000

Responses

201Created

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"
  • Locationstring (uri)required

    Address 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl -X POST "https://api.saleya.app/v1/money-transactions" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — 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"
}
Example response · 201
{
  "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

  • transactionintegerrequired

    ID of the money transaction.

Responses

200Success

Headers

  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/money-transactions/{transaction}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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

  • transactionintegerrequired

    ID of the money transaction.

Header

  • Idempotency-Keystring

    Unique 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-Matchstringrequired

    ETag 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_idinteger

    ID of the money account of the movement.

    Minimum:
    1
  • directionstring

    income — money into the account; expense — money out of the account.

    Values:
    incomeexpense
  • account_amountstring

    Amount in the account currency, as a decimal string.

    Max length:
    37
  • amountinteger or null

    Posting 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 null

    Category ID; null for a transfer between accounts or a movement without a category.

  • supplier_idinteger or null

    ID of the supplier counterparty; null if there is none.

  • descriptionstring or null

    Movement comment as a person or a document wrote it; null if there is none.

    Max length:
    1000

Responses

200Success

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
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
Request body — 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"
}
Example response · 200
{
  "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

  • transactionintegerrequired

    ID of the money transaction.

Header

  • Idempotency-Keystring

    Unique 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-Matchstringrequired

    ETag 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-Replayedstring

    true 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl -X DELETE "https://api.saleya.app/v1/money-transactions/{transaction}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"'