Tax estimates
Calculate estimated federal, state, and self-employment tax for a year from the tax profile stored on your Account.
A tax estimate shows what you owe for a year, split into federal, state, and self-employment tax, with a quarterly schedule. Wingspan calculates it from the tax profile stored on your Account. The call doesn't save anything.
Prerequisites
- A credential with
bookkeeping.service:write. - A tax profile with a filing status and a state of residence. An estimated annual income and estimated annual expenses make the result useful. Set them with
PATCH /v3/finance/tax-withholdings/settings. See Tax withholding.
Calculate an estimate
Call POST /v3/finance/tax-estimates. The only request field is year, a four-digit year. If you leave it out, Wingspan uses the current UTC year. year picks the tax year. It doesn't change the profile the estimate is based on.
curl -X POST "https://api.wingspan.app/v3/finance/tax-estimates" \
-H "Authorization: Bearer $WINGSPAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "year": 2026 }'// 200 OK (trimmed)
{
"year": 2026,
"filingStatus": "Single",
"state": "CA",
"totalIncome": 90000.00,
"totalExpenses": 12000.00,
"netProfit": 78000.00,
"estimatedTax": {
"federal": 11200.00,
"state": 4300.00,
"selfEmployment": 11000.00,
"total": 26500.00
},
"effectiveTaxRate": 0.34,
"quarterlyPayments": [
{ "quarter": "Q1", "dueDate": "2026-04-15", "amount": 6625.00, "paid": 6625.00, "remaining": 0.00 }
]
}The amounts above only show the field layout. quarterlyPayments has one entry per quarter, with amount, paid, and remaining. A profile with no income owes no tax. That returns 200 with an effective rate of zero.
Compare quarterlyPayments with your tax withholding balance, then schedule payments. See Tax withholding.
Errors
| Status | Meaning |
|---|---|
403 | Missing bookkeeping.service:write |
422 | year isn't a four-digit year, or the Account has no tax profile yet. The second case has detailCode: taxEstimates.TaxProfileIncomplete and errors naming filingStatus and state, whichever is missing. Set them, then retry. |
Related pages
Updated about 1 hour ago