Apply the payee's saved default category to its existing transactions
const url = 'https://api.tovarifinancial.com/payees/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/apply-category';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{}'};
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/payees/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/apply-category \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{}'Retroactively sweeps the payee’s EXISTING transactions into the category already saved on the payee row (KAN-568). The target is read from that row under a lock and is never taken from the request, so a body naming a category (defaultCategoryId, budgetCategoryId, categoryId) is rejected with 400 instead of being ignored — send {} or no body at all. Rows that are hand-edited, transfer legs, currently income-categorized, or outflows aimed at an income category are skipped and counted, never rewritten. A payee with more than 10000 linked transactions is refused with 400 before anything is written. Balances cannot change (a category carries no amount), so no affected-account or affected-budget payload is returned; the client invalidates its transaction/budget/report caches instead. Since KAN-1245 X-Idempotency-Key is STORED, not merely logged: replaying a key returns the ORIGINAL counts, and reusing one with a different payload returns 409.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Payee id
Header Parameters
Section titled “Header Parameters”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.
Request Body
Section titled “Request Body”object
Examplegenerated
{}Responses
Section titled “Responses”Per-bucket sweep counts
object
object
The payee’s saved default category, resolved server-side — never supplied by the caller.
Rows whose category actually CHANGED to the target.
Rows already in the target whose provenance was pinned to ‘user’ (category unchanged).
Skipped: the row was hand-edited (category_is_overridden).
Skipped: the row is a leg of an internal transfer.
Skipped: the row’s CURRENT category is kind=‘income’.
Skipped: target is kind=‘income’ but the row is money OUT.
Already in the target with category_source=‘user’ — untouched.
Every non-deleted transaction linked to the payee.
Same value as scannedCount, named for the payee cache’s transactionCount field so the client can patch it without a refetch.
Examplegenerated
{ "data": { "payeeId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "budgetCategoryId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "updatedCount": 1, "frozenCount": 1, "skippedOverriddenCount": 1, "skippedTransferCount": 1, "skippedIncomeCount": 1, "skippedSignMismatchCount": 1, "unchangedCount": 1, "scannedCount": 1, "transactionCount": 1 }, "message": "example", "requestId": "example", "timestamp": "2026-04-15T12:00:00Z"}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"}Resource 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"}Conflict. errorCode is IDEMPOTENCY_CONFLICT when an X-Idempotency-Key was replayed with a different request payload; where the operation instead detects a resource-state conflict it carries that endpoint’s own errorCode (a duplicate name, an import that is no longer committable, an account already linked to a bank connection).
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}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"}