---
title: "Amended return"
url: https://services.dev/docs/examples/tax/amended-return
captured: [tax-amend.txt, tax-build.txt, tax-cases.txt]
---
# Amended return

URL: https://services.dev/docs/examples/tax/amended-return

> A second order for a tax year already filed answers period_taken, and its next is the amended return, ordered again from the accepted one. The amendment is its own return on the same taxpayer, prepared by one member and signed by another, and a partnership files an administrative adjustment request instead.

*tax's words: return is a job, taxpayer is a subject, review is a task, preparer is a member (examples/tax/brand.ts).*

The annual return's period is its tax year, so a taxpayer holds one return a year. When that return is accepted, its end offers a follow-on: `ends: { accepted: { follow: [amendedReturn] } }`. An amendment is never a second annual return. It's its own Service, ordered from the first.

```bash
cat services/amended-return.ts
```

```txt title="captured/tax-build.txt · magic values: none"
import { Service } from 'services.dev'
import { authorization, carryforwardList, efile, schedules } from '../lib/tax.ts'
import { preparers } from '../pools/preparers.ts'
import rules from '../rules.ts'

// A year already filed, filed again. A second order for a tax year the annual return holds answers 409 period_taken, and
// its next is this Service, ordered from the accepted return with the same input: the schedules figured again, prepared,
// signed for the brand's firm, authorized and e-filed, the federal return first. A partnership under the centralized
// audit regime doesn't amend: it files an administrative adjustment request, and each owner gets an adjusted statement.
export default Service({
  name: 'Amended Return',
  description: 'Amended returns.',
  input: {
    business: 'party', owner: 'party: the officer who signs', ein: 'text: such as 12-3456789', tax_year: 'text: such as 2026',
    entity: ['C corp', 'S corp', 'partnership'], jurisdictions: 'jurisdiction[]: such as US, US-CA', books: 'url: a read-only link to the ledger, such as https://books.example/acme',
    owners: 'party[]?: each owner of a partnership or an S corp', change: 'text?: what changed since the return was filed',
  },
  output: { return: 'file: the return packet, every jurisdiction', returns: 'file[]', workpapers: 'file', statements: 'file[]?: each owner\'s adjusted statement', tax: 'money{}', balance_due: 'money{}', carryforwards: carryforwardList, receipts: 'text[]' },
  rules,
  subject: { kind: 'taxpayer', key: 'ein', period: { of: 'tax_year', many: true }, keeps: { carryforwards: 'carryforwards', tax: 'tax' } },
  roles: { preparer: { pool: preparers, pay: job => 90 + 15 * job.input.jurisdictions.length }, signer: { pool: preparers, pay: job => 45 + 15 * job.input.jurisdictions.length } },
  deliver: {
    compute: { by: schedules, cite: 'depreciation and carryforward schedules' },
    draft: { by: 'ai', cite: 'the workpapers and the records the organizer took' },
    check: { review: 'adversarial', lenses: ['what changed', 'numeric tie-out'] },
    prepare: { by: 'preparer', est: '1h', checklist: ['every changed line traces to a source'] },
    sign: { by: 'signer', stamp: { block: 'paid preparer', firm: 'brand' }, est: '20min' },
    authorize: { ask: 'owner', to: 'sign', what: authorization, how: 'id-verified', capacity: 'officer', void: { tolerance: { balance_due: 1 } } },
    file: { submit: efile, to: 'IRS and states', receipt: 'receipts', each: { of: 'jurisdictions', lead: j => j === 'US' }, rejected: { '*': 'prepare' }, when: job => job.input.entity !== 'partnership' },
    aar: { submit: efile, to: 'IRS', form: '8082', receipt: 'receipts', when: job => job.input.entity === 'partnership', emit: { 'k1.adjusted': job => job.input.owners ?? [] } },
  },
  price: { usd: 900, within: '30d', release: ['file.accepted', 'aar.accepted'] },
})
```

## The year is taken

The 2026 return is filed and accepted:

```txt
→ POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada Lovelace","email":"ada@example.com"},"ein":"12-3456789","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"acme-2026"}
```

```txt title="magic values: none"
# … filed, then accepted: job_4Tx2
→ POST /returns/job_4Tx2/accept
```

Ordering the same tax year again answers `409 period_taken`. It names the return that holds the year, and its `next` is the call that amends it, as a tool and as HTTP:

```txt
→ POST /returns {"service":"annual-return","business":{"name":"Acme Robotics","email":"books@acme.example"},"owner":{"name":"Ada Lovelace","email":"ada@example.com"},"ein":"12-3456789","tax_year":"2026","entity":"C corp","jurisdictions":["US","US-CA","US-NY","US-NJ"],"books":"https://books.example/acme","max_usd":1800,"key":"acme-2026-again"}
```

```json title="409 · magic values: none"
{
  "type": "BLOCKED",
  "category": "conflict",
  "code": "period_taken",
  "reason": "taxpayer 12-3456789 has Annual Return for 2026 already: job_4Tx2, accepted. A second one for 2026 is a follow-on from it: amended-return.",
  "param": "tax_year",
  "subject": "sbj_7Hq2",
  "period": "2026",
  "job": "job_4Tx2",
  "follow": [
    "amended-return"
  ],
  "next": {
    "do": "again",
    "arguments": {
      "id": "job_4Tx2",
      "service": "amended-return"
    },
    "tool": "reorder_return",
    "http": "POST http://localhost:8787/returns/job_4Tx2/again"
  },
  "doc_url": "https://apis.tax/docs/errors/period_taken",
  "simulated": true
}
```

## Ordered again, as an amendment

Sent as it came, with the amendment's price. The new return records the one it came from:

```txt
→ POST /returns/job_4Tx2/again {"id":"job_4Tx2","service":"amended-return","max_usd":900,"key":"acme-2026-amended"}
```

```txt title="magic values: none"
← job_4Tx3 · working · $900.00 held · from job_4Tx2
```

```txt
→ GET /returns/job_4Tx3
```

```txt title="magic values: none"
← job_4Tx3 · delivered · workpapers-2026.txt · return.txt · $900.00 charged · on sbj_7Hq2
```

Here Katherine Johnson prepares it, and the signer reviews preparers, so a second member, Grace Hopper, signs. Either could have done either act, never both on one return:

```txt
→ GET /owner/returns/job_4Tx3   # the owner console
```

```txt title="magic values: none"
  record  compute · code | draft · ai | check · ai · adversarial · 2 lenses · pass | prepare · person · ptin and enrolled agent · * · mbr_8Ea1 | sign · person · ptin and cpa · * · mbr_7Hq2 · not the preparer | authorize · owner · Form 8879-CORP · id-verified | file · IRS and states · efin simulated · 4 accepted
  ledger  +$900.00 · AI $1.26 · preparer $150.00 · signer $105.00 · you $643.74
```

## A partnership's AAR

A partnership under the centralized audit regime doesn't amend its return: it files an administrative adjustment request, Form 8082, and each partner gets an adjusted statement. `when` sends the amendment down that path, and `aar` emits `k1.adjusted` to each partner's own taxpayer:

```bash
npx services.dev jobs again job_4Ty5 --service amended-return change="a late 1099 raises ordinary income $24,000" --test-clock tc_7Hq6
```

```txt title="magic values: owner.email = signs@example.test, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}"
job_4Ty6 · amended-return · period 2026 · a partnership: aar, not file · $900.00 held
  steps    compute → draft → check → prepare · mbr_7Hq5 → sign · mbr_8Ea1 → authorize · Form 8879-PE → aar · IRS · Form 8082 accepted
  events   k1.adjusted · a Form 8986 to each partner · Rosa Diaz +$9,600 · Sam Okoro +$8,400 · Ines Varga +$6,000
```

A restated figure on a year the plan already filed mints the amendment on its own, at its own price: [Two clients, over the years](https://services.dev/docs/examples/tax/clients.md#a-client-who-changes). Past the year's refund date, a hard date refuses it.

[One job per period](https://services.dev/docs/service/periods.md) covers `period` and `period_taken`, and [How a job ends](https://services.dev/docs/service/ends.md) covers `follow`.

---

- Up: [The tax example](https://services.dev/docs/examples/tax.md)
- Previous: [Notice response](https://services.dev/docs/examples/tax/notice-response.md)
- Next: [Carryforward watch](https://services.dev/docs/examples/tax/carryforward-watch.md)