createTransaction — creates a new transaction for the authenticated user.
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)
createTransaction — creates a new transaction for the authenticated user.
Authentication: Required (Bearer token). The user must be the owner or collaborator of the target account.
Parameters:
- accountId (string, required unless type is JOURNAL): Account the transaction belongs to
- name (string, required): Transaction display name
- amount (float, required): Legacy hundredths of a major currency unit (negative = expense, positive = income)
- currency (string, optional): 3-letter ISO currency code for transaction denomination
- category (string, required unless type is JOURNAL): Top-level category (FOOD, INCOME, RENT, TRANSPORTATION, …)
- transactedAt (string, required): ISO 8601 / RFC3339 datetime of the transaction
- fileIds ([string], required): List of attached file IDs (pass [] for none)
- type (string, optional): INCOME | EXPENSE | TRANSFER | JOURNAL — inferred from amount/category if omitted
- categoryId (string, optional): v2 category ID — resolved from category if omitted
- incomeCategory (string, optional): Income sub-category
- expenseCategory (string, optional): Expense sub-category
- subcategory (string, optional): Sub-category label
- vendorId (string, optional): Vendor ID
- vendorName (string, optional): Vendor display name
- description (string, optional): Additional notes
- tagIds ([string], optional): Tag IDs to attach
- cronExpression (string, optional): Recurrence cron expression
- endDate (string, optional): ISO 8601 recurrence end date
- isExcludedFromAnalytics (bool, optional): Exclude from spending analytics
- lineItems ([{id, name, amount}], optional): Itemised line items
- oneOffSplitParticipants ([{name, amount}], optional): Freeform Split With Others rows stored directly on the transaction. The server generates persisted row ids; names are display labels only and do not identify or notify another user.
- importSource (optional): EMAIL, PUSH_NOTIFICATION or NOTIFICATION. Labels an imported transaction and places it in review; cannot be combined with Apple Card metadata. Requires a stable clientRequestId to deduplicate imports.
- appleCardTransaction ({transactionId}, optional): Apple Card / FinanceKit metadata; triggers idempotent create and BANK_INTEGRATION source
- toAccountId (string, optional): Transfer destination account. accountId is the source and amount must be negative. Both accounts' balances change.
- toAmount (float, optional): Destination amount in legacy hundredths of its own currency, when it differs from the source's.
- lines ([{accountRef: {kind, id}, side, amount, memo?}], optional): JOURNAL entry lines; requires type JOURNAL. kind is ACCOUNT, CATEGORY or SYSTEM (OPENING_BALANCE_EQUITY, UNCATEGORIZED_INCOME, UNCATEGORIZED_EXPENSE, FX_GAIN_LOSS); side is DEBIT or CREDIT; amount is a positive integer in minor units. Debits must equal credits. accountId and amount are derived from the lines and category is optional.
- clientRequestId (string, optional): Caller-chosen idempotency key, 1-128 characters of letters, digits, '-' or '_' (a UUID works). Repeating a call with the same key on the same account returns the first call's transactionId and creates nothing.
Returns:
- transactionId (string): Newly created (or idempotently matched) transaction ID
- budgetAlertPending (boolean, optional): The transaction was saved, and its alert bookkeeping will be retried in the background