Retire one surplus bank copy of a duplicated charge (bank-vs-bank pairs only)
const url = 'https://api.tovarifinancial.com/duplicate-suggestions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/retire';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"expectedRetireTransactionId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","expectedSurvivorTransactionId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","acknowledgeBalanceShiftCents":1}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.tovarifinancial.com/duplicate-suggestions/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/retire \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "expectedRetireTransactionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "expectedSurvivorTransactionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "acknowledgeBalanceShiftCents": 1 }'Soft-deletes the surplus bank copy of a bank-vs-bank pair, carries a cleared status across to a pending survivor, recomputes the account balance and marks the suggestion confirmed. The server re-derives the survivor and the retiree under a row lock and re-runs every eligibility gate; the two expected* ids are concurrency tokens, never choices.
X-Idempotency-Key is REQUIRED on this route: a missing or blank key answers 400 VALIDATION_ERROR (fieldErrors.idempotencyKey) before any database work. It is HONORED through the shared idempotency store: the same key with the same body replays the recorded 200 byte for byte, and the same key with a different path id or body is refused 409 IDEMPOTENCY_CONFLICT.
A 409 carries one of several codes (see DuplicateRetireConflict). MATCH_NOT_ELIGIBLE: the pair is not bank-vs-bank, was dismissed, or no longer passes a structural or evidence gate. STALE_WRITE: the echoed ids no longer match the server-derived pair; refresh. DUPLICATE_RETIRE_UNCONFIRMED: the retirement would move the balance and acknowledgeBalanceShiftCents was absent or did not equal the current figure — fieldErrors.acknowledgeBalanceShiftCents and fieldErrors.balanceHazardKind carry the CURRENT shift and hazard kind, so the client can re-render the acknowledgement and resend. A database uniqueness conflict other than the idempotency claim answers 409 USER_ALREADY_EXISTS, and a database-level access refusal answers 403 DATABASE_ERROR, a code the shared 403 entry (TenantGateError) does not name. No refusal writes anything, and the key stays free for a corrected retry.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Duplicate suggestion id
Header Parameters
Section titled “Header Parameters”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”object
Concurrency token echoed from the queue item’s consumedTransactionId. A mismatch with the server-derived retiree is 409 STALE_WRITE.
Concurrency token echoed from the queue item’s survivorTransactionId. A mismatch is 409 STALE_WRITE.
Required when the freshly computed balance hazard is not clear, and must equal its shiftCents. Absent or null means nothing is acknowledged. A non-integer is 400.
Examplegenerated
{ "expectedRetireTransactionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "expectedSurvivorTransactionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "acknowledgeBalanceShiftCents": 1}Responses
Section titled “Responses”The confirmed pair, the retirement outcome and the affected balances
object
object
object
SIGNED whole days, bank MINUS manual.
Signed — equal on both legs by construction.
Detection-time verdict. Always false for ‘bank-vs-bank’.
object
Calendar date, ‘YYYY-MM-DD’
SIGNED ledger cents, exactly as stored.
Raw bank text. UNTRUSTED — render as text, never as markup.
object
Calendar date, ‘YYYY-MM-DD’
SIGNED ledger cents, exactly as stored.
Raw bank text. UNTRUSTED — render as text, never as markup.
SERVER-DECIDED — echo it back; never guess a survivor.
For ‘bank-vs-bank’, bankLeg is the SURVIVOR and manualLeg is the surplus bank copy proposed for retirement.
BANK KIND ONLY. Frozen detection-time evidence, not recomputed on read.
BANK KIND ONLY. copyCount - 1, frozen on the same terms.
BANK KIND ONLY. Whether retiring this copy would move the account balance. Recomputed on every read.
object
SIGNED, PER-RETIREE — this copy’s own amount.
BANK KIND ONLY. The survivor’s status after a retire. Recomputed on every read.
SIGNED, ECHOED — the retiree’s own amount, the figure the acknowledgement was taken against. Not the delta the balance moved by; read affectedAccounts for the balances.
object
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
object
Month, ‘YYYY-MM’
Integer minor units (cents)
Integer minor units (cents)
Example
{ "data": { "suggestion": { "origin": "sync", "status": "open", "pairKind": "manual-vs-bank", "balanceHazard": { "kind": "clear" }, "survivorStatusAfter": "uncleared" }, "survivorStatusAfter": "uncleared", "affectedBudget": [ { "month": "2026-07" } ] }}Validation failed — see errorCode / fieldErrors
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Missing, invalid, or expired bearer token
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}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.
object
Which precondition refused the request. Evaluated in this order (CCR-1); SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true.
object
Active policy versions the user has not yet accepted.
object
True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.
Example
{ "errorCode": "EMAIL_NOT_VERIFIED"}Suggestion not found or not owned by the caller org
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}IDEMPOTENCY_CONFLICT, MATCH_NOT_ELIGIBLE, STALE_WRITE, DUPLICATE_RETIRE_UNCONFIRMED (with the current acknowledgeBalanceShiftCents and balanceHazardKind in fieldErrors), or USER_ALREADY_EXISTS. Nothing was written in any case.
object
IDEMPOTENCY_CONFLICT (the key was reused with a different request), MATCH_NOT_ELIGIBLE (a structural gate refused), STALE_WRITE (the echoed ids no longer match the server-derived pair), DUPLICATE_RETIRE_UNCONFIRMED (the balance shift was not acknowledged at its current figure), or USER_ALREADY_EXISTS (a database uniqueness conflict other than the idempotency claim).
Present only on DUPLICATE_RETIRE_UNCONFIRMED.
object
DUPLICATE_RETIRE_UNCONFIRMED only — one element, the CURRENT signed shift in cents as a decimal string.
DUPLICATE_RETIRE_UNCONFIRMED only — one element, the current hazard kind.
Example
{ "errorCode": "IDEMPOTENCY_CONFLICT", "fieldErrors": { "balanceHazardKind": [ "clear" ] }}Internal error (no internal detail leaked)
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}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.
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}