Skip to content
Tovari Docs

Split a transaction across categories (create or replace its lines)

PUT
/transactions/{id}/splits
curl --request PUT \
  --url https://api.tovarifinancial.com/transactions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/splits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "expectedAmountCents": 1, "lines": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "budgetCategoryId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "amountCents": 1, "memo": "example" } ] }'

Replaces the whole line set. 2-20 user lines, each the sign of the parent and non-zero, plus at most one server-recognised system filler (a line keeps that role only when its id, category and amount all match the stored filler). The lines must sum exactly to the locked parent amount. The parent takes the largest-magnitude user line as its category with categorySource user. Nothing is written on any refusal.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Transaction id

Header Parameters

Section titled “Header Parameters”
X-Idempotency-Key
string

Optional idempotency key for safe write retries. Every operation that declares this header reads it. Three cases, told apart per operation: (1) where the operation also documents a 409 whose codes include IDEMPOTENCY_CONFLICT, replaying this key with a different payload returns 409 IDEMPOTENCY_CONFLICT and replaying it with the same payload returns the original response; (2) where it documents no 409, a replay is reconciled optimistically against a unique key column and answers the original 200; (3) where it documents a 409 whose codes do NOT include IDEMPOTENCY_CONFLICT, a conflict on this key is impossible — a replay answers a 200, and that 409 is a resource-state conflict described by the operation’s own 409 schema.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
expectedAmountCents
required

The signed parent amount the editor balanced against.

integer format: int64
lines
required
Array<object>
object
id

An existing line id to keep stable; absent or null = a new line.

string format: uuid
nullable
budgetCategoryId
required
string format: uuid
amountCents
required

Integer minor units (cents)

integer format: int64
memo
string
nullable <= 200 characters
Examplegenerated
{
  "expectedAmountCents": 1,
  "lines": [
    {
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "budgetCategoryId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "amountCents": 1,
      "memo": "example"
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

The split parent + side effects

Media typeapplication/json
object
data
required
object
transaction
required
object
id
required
string format: uuid
accountId
required
string format: uuid
amountCents
required

Integer minor units (cents)

integer format: int64
budgetCategoryId
required
string format: uuid
nullable
categorySource
required
string
Allowed values: user
categoryIsOverridden
required
boolean
split
required
object
lineCount
required
integer
needsReview
required

A system filler line (a bank amount change) is present.

boolean
lines
required
Array<object>
object
id
required
string format: uuid
budgetCategoryId
required
string format: uuid
categoryName
required
string
categoryColorId
required
string
nullable
categoryKind
required
string
amountCents
required

Integer minor units (cents)

integer format: int64
memo
required
string
nullable
sortOrder
required
integer
isSystemFiller
required
boolean
affectedBudget
required
Array<object>
object
categoryId
string
month

Month, ‘YYYY-MM’

string
spentCents

Integer minor units (cents)

integer format: int64
threeMonthAvgCents

Integer minor units (cents)

integer format: int64
affectedAccounts
required
Array<object>
object
accountId
string
balanceCents

Integer minor units (cents)

integer format: int64
clearedBalanceCents

Integer minor units (cents)

integer format: int64
unclearedBalanceCents

Integer minor units (cents)

integer format: int64
pendingBalanceCents

Integer minor units (cents)

integer format: int64
workingBalanceCents

Integer minor units (cents)

integer format: int64
monthChangeCents

Integer minor units (cents)

integer format: int64
message
string
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "data": {
    "transaction": {
      "categorySource": "user",
      "categoryIsOverridden": true
    },
    "affectedBudget": [
      {
        "month": "2026-07"
      }
    ]
  }
}

400

Section titled “400”

VALIDATION_ERROR — fieldErrors keyed lines, lines.<i>.amountCents, lines.<i>.budgetCategoryId or lines.<i>.memo, and details { issue?: count|sum, lineErrors: [{ index, field, reason }] } with reason in category_missing|category_not_allowed|sign|zero|memo_too_long.

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "errorCode": "INVALID_EMAIL_FORMAT"
}

401

Section titled “401”

Missing, invalid, or expired bearer token

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "errorCode": "INVALID_EMAIL_FORMAT"
}

403

Section titled “403”

Authenticated, but the tenant gate refuses the request until the caller resolves a precondition. errorCode is one of EMAIL_NOT_VERIFIED, POLICY_ACCEPTANCE_REQUIRED, or SUBSCRIPTION_REQUIRED, evaluated in exactly that order (contract term CCR-1: email verification first, then policy acceptance, then subscription — so a subscriber who has merely not re-accepted the current policies always sees POLICY_ACCEPTANCE_REQUIRED). A POLICY_ACCEPTANCE_REQUIRED body additionally carries details.outstanding (the policy versions still to accept) and details.firstAcceptance. The SUBSCRIPTION_REQUIRED arm is INERT unless the server-side BILLING_ENABLED flag is exactly the string true; while it is off, only the first two codes are reachable. Not retryable as sent — resolve the named condition, then resend.

Media typeapplication/json
object
errorCode
required

Which precondition refused the request. Evaluated in this order (CCR-1); SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true.

string
Allowed values: EMAIL_NOT_VERIFIED POLICY_ACCEPTANCE_REQUIRED SUBSCRIPTION_REQUIRED
message
required
string
details
object
outstanding
required

Active policy versions the user has not yet accepted.

Array<object>
object
id
required
string format: uuid
policyType
required
string
version
required
integer
title
required
string
firstAcceptance
required

True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.

boolean
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "errorCode": "EMAIL_NOT_VERIFIED"
}

404

Section titled “404”

Resource not found or not owned by the caller org

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "errorCode": "INVALID_EMAIL_FORMAT"
}

409

Section titled “409”

SPLIT_NOT_ELIGIBLE (details.reason transfer|adjustment|zero_amount), SPLIT_AMOUNT_CHANGED (details.currentAmountCents), or IDEMPOTENCY_CONFLICT. Nothing was written.

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "errorCode": "INVALID_EMAIL_FORMAT"
}

500

Section titled “500”

Internal error (no internal detail leaked)

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "errorCode": "INVALID_EMAIL_FORMAT"
}

503

Section titled “503”

Service temporarily unavailable — errorCode is SERVICE_UNAVAILABLE. A TRANSIENT, RETRYABLE condition rather than a defect in the request: a query that exceeded its time budget, a lost or refused database connection, a saturated connection pool, or an outage at an upstream provider the request depends on (the authentication provider, or the bank data provider on a bank-connection operation). The identical request may succeed on retry — back off briefly and, on a write, resend the same X-Idempotency-Key where the operation accepts one.

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
  "errorCode": "INVALID_EMAIL_FORMAT"
}