Tax withholding

Tax withholding sets money aside for taxes in a separate savings account that Wingspan holds for you. You choose a rate. You can also deposit, withdraw, and schedule quarterly estimated IRS payments from the balance.

Prerequisites

• A credential with bookkeeping.business-banking-account:read to read, and :write to change settings or move money.
• A tax withholding account. It is an internal account with type: TaxWithholding. If you don't have one, open one. See Internal accounts and balances. Balance, deposit, withdraw, payment, and history calls return 404 when you don't have one.
• If you call with a person's login session, deposits, withdrawals, and tax payments need a HighRiskWriteAction MFA step-up. See Banking and spend.

Set up withholding

Read the current settings with GET /v3/finance/tax-withholdings/settings. If nothing has been saved, you get disabled settings with a zero rate.

Change them with PATCH /v3/finance/tax-withholdings/settings. Send at least one field.

curl -X PATCH "https://api.wingspan.app/v3/finance/tax-withholdings/settings" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "isEnabled": true,
    "withholdingRate": 25,
    "filingStatus": "Single",
    "state": "CA",
    "estimatedAnnualIncome": 90000,
    "estimatedAnnualExpenses": 12000
  }'

The response is the settings. It also shows federalRate, stateRate, and selfEmploymentRate when Wingspan has them. An empty body returns 422.

filingStatus, state, and the two estimates are also the inputs to Tax estimates.

Check the balance

Call GET /v3/finance/tax-withholdings/balance. The response has balance, available, hold, pending, currency, and updatedAt.

Deposit and withdraw

• POST /v3/finance/tax-withholdings/deposit moves money in.
• POST /v3/finance/tax-withholdings/withdraw moves money out.

Both take amount (required) and destinationAccountId (optional), and both require an Idempotency-Key. They return 200 with a transfer.

The other side of the movement is your Wallet unless you name another account in destinationAccountId. A value that starts with ia_ is looked up as one of your Wallet accounts. Any other value is read as the ID of one of your external bank accounts. Anything that isn't yours returns 404.

curl -X POST "https://api.wingspan.app/v3/finance/tax-withholdings/deposit" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tax-deposit-2026-10-20" \
  -d '{ "amount": 1500.00 }'

Schedule an IRS payment

Call POST /v3/finance/tax-withholdings/tax-payments. It creates an estimated tax payment to the IRS, paid from the tax withholding balance. It isn't a deposit or a withdrawal.

curl -X POST "https://api.wingspan.app/v3/finance/tax-withholdings/tax-payments" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: irs-q4-2026" \
  -d '{ "amount": 3200.00, "quarter": "Q4", "year": 2026 }'

// 201 Created (trimmed)
{
  "id": "Tp4Wn9Qk3Lx6Bz8Mh2Rc5T",
  "type": "TaxPayment",
  "direction": "Debit",
  "status": "Scheduled",
  "amount": 3200.00,
  "currency": "USD",
  "quarter": "Q4",
  "year": 2026,
  "effectiveAt": "2027-01-15T00:00:00Z"
}

To cancel it, call POST /v3/finance/tax-withholdings/tax-payments/{taxPaymentId}/cancel with an Idempotency-Key. A payment can be cancelled while it is scheduled and before Wingspan's internal filing deadline. A payment that has posted or was already cancelled returns 409. The response is the payment with status: Cancelled.

Read the history

Call GET /v3/finance/tax-withholdings/transactions.

Each row has type (TaxWithholding, TaxPayment, or BookTransfer), subType (Deposit, Withdraw, or Correction), direction (Credit or Debit), status, amount, effectiveAt, and, where they apply, quarter, year, invoiceId, and invoiceNumber.

The feed groups rows by source: scheduled and processing IRS payments, cancelled IRS payments, set-asides from invoices, and posted ledger entries. Date filters and sort apply within each source. The result is not one list in date order across sources.

Errors

Related pages

• Tax estimates
• Move money with transfers
• Tax filing