updateTransaction — partially updates a transaction using field masks.
Use with an AI agent
Export this page as Markdown or bundle it with a task for your agent.
Try a task
Preview the prompt that will be copied
Reference
Authentication: bearer token required (see how to get a token)
updateTransaction — partially updates a transaction using field masks.
Authentication: Required (Bearer token). User must be account owner or collaborator,
with OWNER or COOWNER role if a role is assigned.
Parameters:
- transactionId (string, required): ID of the transaction to update
- expectedExactVersion (string, required for exact transactions): Version returned by a precision-aware read. A stale version is rejected.
- transaction (object, required): Fields to update (all optional)
- accountId (string): Destination account ID for moving a manual transaction. The accountId field must also be included in transactionFieldMasks. Transactions with source BANK_INTEGRATION cannot be moved between accounts. Destination-account authorization is enforced.
- name (string): New display name
- amount (float): New amount in smallest denomination
- type (string): INCOME, EXPENSE or TRANSFER. Include type in transactionFieldMasks to set it explicitly. Directional transfer categories use amount-sign classification; loan payments and transfers with a destination remain TRANSFER. Linked refunds remain EXPENSE.
- category (string): Top-level category (auto-resolves categoryId if not provided)
- categoryId (string): v2 category ID
- incomeCategory (string): Income sub-category
- expenseCategory (string): Expense sub-category
- subcategory (string): Sub-category label
- vendorId (string): Vendor ID
- vendorName (string): Vendor display name
- description (string): Notes
- transactedAt (string): ISO 8601 datetime
- isPending (bool): Pending flag
- inReview (bool): In-review flag
- fileIds ([string]): Attached file IDs (replaces existing)
- tagIds ([string]): Attached tag IDs (replaces existing)
- cronExpression (string): Recurrence cron expression
- endDate (string): ISO 8601 recurrence end date
- isExcludedFromAnalytics (bool): Exclude from analytics
- lineItems ([{id, name, amount}]): Line items (replaces existing)
- oneOffSplitParticipants ([{id?, name, amount}]): Freeform Split With Others rows reconciled by persisted row id. Omit id to add a new row.
- deletedOneOffSplitParticipants ([string]): Persisted split row ids to delete
- transactionFieldMasks (array, required unless lines are sent): Array of {path} objects specifying which fields to update
- lines ([{id?, accountRef: {kind, id}, side, amount, memo?}], optional): Replaces a JOURNAL entry's lines; debits must equal credits. Requires ledgerVersion.
- ledgerVersion (int, required with lines): The entry's current ledgerVersion. A stale version fails with "journal entry changed; reload and retry".
JOURNAL entries accept field masks only for name, description, transactedAt, fileIds, tagIds and isExcludedFromAnalytics; their account, amount and category derive from their lines. isExcludedFromAnalytics on a JOURNAL entry is stored as journalExcludedFromAnalytics, because analytics read the entry through its category lines. Each lines edit records a revision reversing the previous lines.
Without an explicit type, category and amount edits use the same category/sign classification as bank ingestion: nonnegative TRANSFER_IN is INCOME, negative TRANSFER_OUT is EXPENSE, and LOAN_PAYMENTS is TRANSFER. Existing manual transfers remain TRANSFER when their category and sign are unchanged; transfers with a destination remain TRANSFER. Same-direction and zero-amount edits in an unchanged ordinary category preserve the existing type, including refunds and reversals.
For a transfer with a destination account (toAccountId), changing amount scales the destination amount by the same ratio.
Returns:
- transactionId (string): ID of the updated transaction