Transactions and categories

Transactions are your bookkeeping records of income and expenses. Wingspan fills them from your linked bank accounts. You can also add your own, change their category, mark them as business or personal, and attach a receipt. The profit and loss report and the insights are built from them.

Prerequisites

• A credential with bookkeeping.transaction:read to read, and bookkeeping.transaction:write to change.
• For synced transactions, a linked bank account. See Link and verify a bank account.

List transactions

Call GET /v3/finance/transactions.

curl "https://api.wingspan.app/v3/finance/transactions?filter[type][eq]=Expense&filter[startDate][eq]=2026-10-01" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

Each transaction has:

• name, amount, currency, type, status, and date.
• isBusiness, businessAmount, and deductibleAmount. These say how much of the amount counts for business.
• wsCategory, subcategory, scheduleCLineNumber, and scheduleCDescription.
• merchantName, merchantCategory, paymentChannel, note, and receiptFileId.
• Links to what it came from: externalBankAccountId, invoiceId, and cardId.
• latestUpdateSource: Plaid, System, or Person.

Read one with GET /v3/finance/transactions/{transactionId}.

Add a transaction

Call POST /v3/finance/transactions for money that isn't in a linked bank, such as cash. name, amount, currency, type, and date are required.

curl -X POST "https://api.wingspan.app/v3/finance/transactions" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Design software, one year",
    "amount": 240.00,
    "currency": "USD",
    "type": "Expense",
    "date": "2026-10-14",
    "isBusiness": true,
    "wsCategory": "Software",
    "note": "Paid by cash reimbursement"
  }'

The response is 201 with the transaction. Take wsCategory and subcategory from the category list below. A subcategory belongs to the wsCategory you send.

Change a transaction

Call PATCH /v3/finance/transactions/{transactionId}. Send only what changes. You can change name, amount, type, date, isBusiness, businessAmount, wsCategory, subcategory, note, receiptFileId, and metadata.

• Send subcategory: null to clear it.
• Changing wsCategory without sending a subcategory also clears the old subcategory.
• If you change amount without businessAmount, a transaction that was fully business stays fully business. A partly business transaction keeps its business amount, and the request fails if the new amount is smaller than that. To lower the amount below a partial business amount, send both fields.
• Two edits to the same transaction at once return 409. Retry.

Delete a transaction

Call DELETE /v3/finance/transactions/{transactionId}. It deletes a transaction you created yourself and returns 204. A transaction that came from a bank can't be deleted this way, and the call returns 409.

Sync from your banks

Call POST /v3/finance/transactions/sync to pull new transactions from every linked bank account. The response has status (Started, AlreadyInProgress, Completed, or Interrupted) and accountsSynced. The sync can still be running when the call returns. List transactions again after it finishes. A 409 means a sync can't start right now.

Read the category list

Call GET /v3/finance/transaction-categories. It returns the category tree.

• name and subcategories[]. Each subcategory has name and isCustom.
• scheduleCLineNumber and scheduleCDescription, the IRS Schedule C line the category maps to.
• isCustomSubcategoryAllowed, whether you can send a new subcategory name under that category.

The list includes up to 100 custom names per category, found in your 5,000 most recently updated categorized transactions. The Transfer category has built-in names only.

Errors

Webhook events

Transaction.Created and Transaction.Updated are published. See Webhooks and events.

Related pages

• Profit and loss and insights
• Manage a bank account
• Files and documents