Amend a federal return (Form 1040-X)
Computes Form 1040-X (Rev. December 2025) for one amended 2020-2025 return: columns A, B and C for lines 1-15, then lines 16-23.
Compute Form 1040-X (Rev. December 2025) for one amended federal return, 2020-2025.
Column C is the federal compute of `amended`; column A is `original.figures`; B = C − A. One billable unit.
Headers
| Header | Required | Description |
|---|---|---|
| Authorization | Yes | Bearer <API key> |
| Content-Type | Yes | application/json |
| Idempotency-Key | No (recommended) | Optional. A unique key per logical request (one key per operation). Retrying with the SAME key + SAME request body replays the byte-identical first response (with header `Idempotent-Replayed: true`)…Optional. A unique key per logical request (one key per operation). Retrying with the SAME key + SAME request body replays the byte-identical first response (with header `Idempotent-Replayed: true`) and bills exactly ONCE. The SAME key with a DIFFERENT body → 409 `idempotency_key_reused`. A concurrent in-flight duplicate → 409 `idempotency_key_in_progress` (retry). Keys are scoped per account and replay for 24h. Errors (4xx/5xx) are NOT cached — a retry after an error is a fresh request. |
Request body
| Field | Description |
|---|---|
| amendedFederalProfilerequired | The corrected return, exactly as accepted by POST /tax-compute/federal. Column C is its federal compute. |
| original.figuresobjectrequired | Column A: the return as filed, or as previously adjusted by you or the IRS, in whole dollars. filingStatus and Form 1040-X lines 1, 2, 4a, 4b, 6, 7, 10, 12, 14 and 15 (line1 … line15). Lines 3, 5, 8…Column A: the return as filed, or as previously adjusted by you or the IRS, in whole dollars. filingStatus and Form 1040-X lines 1, 2, 4a, 4b, 6, 7, 10, 12, 14 and 15 (line1 … line15). Lines 3, 5, 8 and 11 follow by the form's arithmetic. |
| original.profileFederalProfile | Optional cross-check. It is recomputed and must reproduce every line of original.figures, or the request declines original_profile_mismatch. It is never column A. |
| estimatedTaxPayments{ original, corrected }required | Line 13, columns A and C, including any prior-year overpayment applied. |
| paidWithOrAfterOriginalintegerrequired | Line 16: paid with an extension, with the original return, and after it was filed. No interest, penalties or fees. |
| originalOverpaymentintegerrequired | Line 18: Form 1040 line 34 as filed (including any amount applied to next year's estimated tax), plus any additional overpayment from an IRS adjustment. |
| appliedToEstimatedTaxinteger | Line 23: the part of line 21 to apply to next year's estimated tax. |
| correctedPaymentsAffirmedboolean | Must be true to compute (otherwise corrected_payments_not_attested), attesting:Must be true to compute (otherwise corrected_payments_not_attested), attesting: on the corrected return, Form 1040-X line 12 is only the federalWithholding sent plus the Additional Medicare Tax withheld that the engine figures, with no other federal income tax withheld and no excess social security or tier 1 RRTA tax withheld; line 14 has no earned income credit; line 15 has no refundable credit other than the additional child tax credit and the net premium tax credit the engine computes; estimatedTaxPayments.corrected is the line 13 amount: the estimated tax paid for the year, including any prior-year overpayment applied to it; paidWithOrAfterOriginal is the line 16 amount and excludes interest, penalties and fees; originalOverpayment is the line 18 amount: the overpayment shown on the original return, including any part applied to next year's estimated tax, plus any additional overpayment from an IRS adjustment. |
Every field of amended is in the federal reference.
Example
curl https://tax-mcp.com/api/mcp/tax-compute/amended-return \
-H "Authorization: Bearer $TAX_MCP_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"amended": {
"year": 2024,
"filingStatus": "single",
"canBeClaimedAsDependent": false,
"noForeignOrTerritoryExclusionAffirmed": true,
"wages": 85000,
"medicareWages": 85000,
"federalWithholding": 9600
},
"original": {
"figures": {
"filingStatus": "single",
"line1": 80000,
"line2": 14600,
"line4a": 0,
"line4b": 0,
"line6": 9447,
"line7": 0,
"line10": 0,
"line12": 9000,
"line14": 0,
"line15": 0
}
},
"estimatedTaxPayments": { "original": 0, "corrected": 0 },
"paidWithOrAfterOriginal": 447,
"originalOverpayment": 0,
"correctedPaymentsAffirmed": true
}'{
"computed": true,
"form": "1040-X",
"revision": "Rev. December 2025",
"year": 2024,
"filingStatus": { "original": "single", "amended": "single" },
"lines": [
{
"line": "1",
"label": "Adjusted gross income",
"original": 80000,
"change": 5000,
"correct": 85000
},
{
"line": "2",
"label": "Itemized deductions or standard deduction",
"original": 14600,
"change": 0,
"correct": 14600
},
{
"line": "3",
"label": "Subtract line 2 from line 1",
"original": 65400,
"change": 5000,
"correct": 70400
},
{
"line": "4a",
"label": "Qualified business income deduction",
"original": 0,
"change": 0,
"correct": 0
},
{
"line": "4b",
"label": "Deductions for tips, overtime, car loan interest, and seniors from Schedule 1-A",
"original": 0,
"change": 0,
"correct": 0
},
{
"line": "5",
"label": "Taxable income",
"original": 65400,
"change": 5000,
"correct": 70400
},
{ "line": "6", "label": "Tax", "original": 9447, "change": 1100, "correct": 10547 },
{
"line": "7",
"label": "Nonrefundable credits",
"original": 0,
"change": 0,
"correct": 0
},
{
"line": "8",
"label": "Subtract line 7 from line 6",
"original": 9447,
"change": 1100,
"correct": 10547
},
{ "line": "10", "label": "Other taxes", "original": 0, "change": 0, "correct": 0 },
{
"line": "11",
"label": "Total tax",
"original": 9447,
"change": 1100,
"correct": 10547
},
{
"line": "12",
"label": "Federal income tax withheld and excess social security and tier 1 RRTA tax withheld",
"original": 9000,
"change": 600,
"correct": 9600
},
{
"line": "13",
"label": "Estimated tax payments, including amount applied from prior year's return",
"original": 0,
"change": 0,
"correct": 0
},
{
"line": "14",
"label": "Earned income credit (EIC)",
"original": 0,
"change": 0,
"correct": 0
},
{
"line": "15",
"label": "Refundable credits",
"original": 0,
"change": 0,
"correct": 0
}
],
"line16": 447,
"line17": 10047,
"line18": 0,
"line19": 10047,
"amendedReturn": {
"computed": true,
"year": 2024,
"filingStatus": "single",
"taxableIncome": 70400,
"incomeTax": 10547,
"totalTax": 10547,
"lines": [
{ "lineId": "1040:15", "label": "Taxable income", "amount": 70400 },
{
"lineId": "1040:16",
"label": "Income tax",
"amount": 10547,
"derivation": "<5 derivation steps — see full response>"
},
{ "lineId": "1040:24", "label": "Total tax", "amount": 10547 }
],
"flags": [],
"owedOrRefund": 947
},
"flags": [],
"amountYouOwe": 500,
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": {
"engine": "deterministic",
"jurisdiction": "amended-return",
"tax_year": 2024
},
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "<computation-support notice — see full response>"
}
}Full response, including line derivations
{
"computed": true,
"form": "1040-X",
"revision": "Rev. December 2025",
"year": 2024,
"filingStatus": { "original": "single", "amended": "single" },
"lines": [
{
"line": "1",
"label": "Adjusted gross income",
"original": 80000,
"change": 5000,
"correct": 85000
},
{
"line": "2",
"label": "Itemized deductions or standard deduction",
"original": 14600,
"change": 0,
"correct": 14600
},
{
"line": "3",
"label": "Subtract line 2 from line 1",
"original": 65400,
"change": 5000,
"correct": 70400
},
{
"line": "4a",
"label": "Qualified business income deduction",
"original": 0,
"change": 0,
"correct": 0
},
{
"line": "4b",
"label": "Deductions for tips, overtime, car loan interest, and seniors from Schedule 1-A",
"original": 0,
"change": 0,
"correct": 0
},
{
"line": "5",
"label": "Taxable income",
"original": 65400,
"change": 5000,
"correct": 70400
},
{ "line": "6", "label": "Tax", "original": 9447, "change": 1100, "correct": 10547 },
{
"line": "7",
"label": "Nonrefundable credits",
"original": 0,
"change": 0,
"correct": 0
},
{
"line": "8",
"label": "Subtract line 7 from line 6",
"original": 9447,
"change": 1100,
"correct": 10547
},
{ "line": "10", "label": "Other taxes", "original": 0, "change": 0, "correct": 0 },
{
"line": "11",
"label": "Total tax",
"original": 9447,
"change": 1100,
"correct": 10547
},
{
"line": "12",
"label": "Federal income tax withheld and excess social security and tier 1 RRTA tax withheld",
"original": 9000,
"change": 600,
"correct": 9600
},
{
"line": "13",
"label": "Estimated tax payments, including amount applied from prior year's return",
"original": 0,
"change": 0,
"correct": 0
},
{
"line": "14",
"label": "Earned income credit (EIC)",
"original": 0,
"change": 0,
"correct": 0
},
{
"line": "15",
"label": "Refundable credits",
"original": 0,
"change": 0,
"correct": 0
}
],
"line16": 447,
"line17": 10047,
"line18": 0,
"line19": 10047,
"amendedReturn": {
"computed": true,
"year": 2024,
"filingStatus": "single",
"taxableIncome": 70400,
"incomeTax": 10547,
"totalTax": 10547,
"lines": [
{
"lineId": "1040:15",
"label": "Taxable income",
"amount": 70400,
"derivation": []
},
{
"lineId": "1040:16",
"label": "Income tax",
"amount": 10547,
"derivation": [
{
"lineId": "1040:16",
"label": "Tax Table method (IRS-mandated below $100,000 taxable income)",
"inputs": [
{ "name": "taxableIncome", "value": 70400 }
],
"rule": {
"description": "Form 1040 instructions require the published Tax Table — a lookup on the midpoint of a narrow taxable-income band — for taxable income under $100,000; the exact bracket formula (Tax Computation Worksheet) applies only at $100,000 or more.",
"authority": "Form 1040 instructions — Tax Table"
},
"computation": "taxable income $70,400 → Tax Table band midpoint $70,425",
"result": 0
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 10% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 11600 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2024/single",
"value": "10% (up to $11,600)",
"revProc": "Rev. Proc. 2023-34"
}
},
"computation": "0.1 × $11,600 = $1,160",
"result": 1160
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 12% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 35550 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2024/single",
"value": "12% (up to $47,150)",
"revProc": "Rev. Proc. 2023-34"
}
},
"computation": "0.12 × $35,550 = $4,266",
"result": 4266
},
{
"lineId": "1040:16",
"label": "Ordinary income tax — 22% bracket",
"inputs": [
{ "name": "taxableIncomeInBracket", "value": 23275 }
],
"rule": {
"description": "marginal rate × taxable income falling within this bracket",
"authority": "IRC §1(j)",
"constantRef": {
"table": "BRACKETS_BY_YEAR",
"key": "2024/single",
"value": "22% (up to $100,525)",
"revProc": "Rev. Proc. 2023-34"
}
},
"computation": "0.22 × $23,275 = $5,120.5",
"result": 5120.5
},
{
"lineId": "1040:16",
"label": "Whole-dollar rounding — ordinary income tax",
"inputs": [
{ "name": "unroundedOrdinaryTax", "value": 10547 }
],
"rule": {
"description": "round the ordinary income tax to whole dollars",
"authority": "Form 1040 instructions — whole-dollar rounding"
},
"computation": "$10,547 − $10,546.5 = $0.5",
"result": 0.5
}
]
},
{
"lineId": "1040:24",
"label": "Total tax",
"amount": 10547,
"derivation": []
}
],
"flags": [],
"owedOrRefund": 947
},
"flags": [],
"amountYouOwe": 500,
"billed": true,
"retry_safe": true,
"next_action": "none",
"provenance": {
"engine": "deterministic",
"jurisdiction": "amended-return",
"tax_year": 2024
},
"legal_notice": {
"ref": "https://tax-mcp.com/terms#compute-notice",
"version": "v1",
"text": "Computation support only. Not tax, legal, accounting, or financial advice. Customer is responsible for review, filing positions, and use only within the documented supported envelope."
}
}Responses
| Status | Meaning |
|---|---|
| 200 | { computed, form, revision, year, filingStatus, lines[{line, original, change, correct}], line16-19, amountYouOwe | overpaid, refunded, appliedToEstimatedTax, amendedReturn, flags } or a decline with…{ computed, form, revision, year, filingStatus, lines[{line, original, change, correct}], line16-19, amountYouOwe | overpaid, refunded, appliedToEstimatedTax, amendedReturn, flags } or a decline with code corrected_payments_not_attested | filing_status_change_not_supported | amended_return_declined | original_return_declined | original_profile_mismatch | original_payments_inconsistent | engine_line_mismatch | applied_to_estimated_tax_exceeds_overpayment |
| 400 | Invalid body / JSON / failed validation |
| 401 | Missing / unknown / revoked key (no enumeration) |
| 403 | Account suspended — contact billing (distinct from 401: the key is valid) |
| 409 | Idempotency-Key reused with a different body (`idempotency_key_reused`), or a concurrent in-flight duplicate (`idempotency_key_in_progress`). Retry; NOT billed. |
| 429 | Monthly quota exhausted (account-wide;Monthly quota exhausted (account-wide; `quota_exceeded`, next_action `upgrade_plan_or_wait_next_period`, retry_safe false) or per-minute rate exceeded (`rate_limit_exceeded`, next_action `retry_after_backoff`, retry_safe true). Not billed. |
| 500 | Sanitized server error computing the return |
| 503 | Metering outage — fail-closed (the call is NOT silently served free) |
A computed response carries lines (each with original, change and correct), lines 16-19, then amountYouOwe (line 20) or overpaid, refunded and appliedToEstimatedTax (lines 21-23), and amendedReturn, the federal result to attach as the corrected Form 1040. A federal decline of either profile comes back as amended_return_declined or original_return_declined with the federal code in returnDecline. The other declines: a change into or out of married filing jointly, no correctedPaymentsAffirmed, original figures whose tax and payments do not reconcile with lines 16 and 18, appliedToEstimatedTax above line 21, and engine_line_mismatch (line 5 differs from the engine's taxable income). Flags ending in VERIFY mark original amounts the corrected return drops, such as an earned income credit. You write the line 6 method and Parts I and II.
Roadmap status for this page
Generated from the roadmap (updated 2026-10-30). Shipped & certified means live and independently checked against primary tax sources; certifying means live, with those checks still in progress.
| Capability | Status |
|---|---|
| Amended return (Form 1040-X), 2020-2025Form 1040-X columns A, B and C and lines 16-23 for 2020-2025, from the original as filed and the amended profile. |