Delete a transaction

DELETE

/transactions/{id}

const url = 'https://api.tovarifinancial.com/transactions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0?cascade=1';
const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request DELETE \
  --url 'https://api.tovarifinancial.com/transactions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0?cascade=1' \
  --header 'Authorization: Bearer <token>'

Soft-deletes the transaction. When the target is one leg of a transfer BOTH legs are removed, but only when ?cascade=1 confirms it: omit the parameter and the call answers 409 carrying the counterpart leg, so the confirmation can name it without a second round-trip. There is deliberately no “delete both by default”.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string format: uuid

Transaction id

Query Parameters

cascade

string

Allowed values: 1

Optional. Set to ‘1’ — the ONLY accepted value — to confirm deleting a transfer’s matching leg as well. Omitted (or any other value) means no cascade, and deleting a transfer leg then answers 409 with details.counterpart.

Header Parameters

X-Idempotency-Key

string

Optional idempotency key for safe write retries. Every operation that declares this header reads it. Two cases, told apart per operation: (1) where the operation also documents a 409, 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.

Responses

200

Deleted + side effects

application/json

object

data

required

object

transaction

object

string

deleted

boolean

affectedAccounts

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

workingBalanceCents

Integer minor units (cents)

integer format: int64

monthChangeCents

Integer minor units (cents)

integer format: int64

affectedBudget

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

message

string

requestId

required

string

timestamp

required

string format: date-time

Example

{
  "data": {
    "transaction": {
      "deleted": true
    },
    "affectedBudget": [
      {
        "month": "2026-07"
      }
    ]
  }
}

401

Missing, invalid, or expired bearer token

application/json

object

errorCode

required

Machine-readable error code (AUTH_ERROR_CODES).

string

Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS ORG_NAME_TAKEN 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

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.

application/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

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

Resource not found or not owned by the caller org

application/json

object

errorCode

required

Machine-readable error code (AUTH_ERROR_CODES).

string

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

Either IDEMPOTENCY_CONFLICT (an X-Idempotency-Key was replayed with a different request) or VALIDATION_ERROR because the transaction is one leg of a transfer and ?cascade=1 was omitted — details.counterpart names the matching leg that would also be deleted. Nothing was written in either case.

application/json

object

errorCode

required

string

Allowed values: IDEMPOTENCY_CONFLICT VALIDATION_ERROR

message

required

string

details

object

requiresCascade

required

Always true on this arm — re-issue the DELETE with ?cascade=1 to remove both legs.

boolean

counterpart

required

object

transactionId

required

string format: uuid

accountId

required

string format: uuid

accountName

required

string

amountCents

required

SIGNED ledger cents, exactly as stored.

integer format: int64

transactionDate

required

Calendar date, ‘YYYY-MM-DD’

string

isPlaceholder

required

The counterpart leg is an unreviewed placeholder rather than a user-entered row.

boolean

requestId

required

string

timestamp

required

string format: date-time

Example

{
  "errorCode": "IDEMPOTENCY_CONFLICT"
}

500

Internal error (no internal detail leaked)

application/json

object

errorCode

required

Machine-readable error code (AUTH_ERROR_CODES).

string

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

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.

application/json

object

errorCode

required

Machine-readable error code (AUTH_ERROR_CODES).

string

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"
}