--- title: "Annual return" url: https://services.dev/docs/examples/tax/annual-return captured: [tax-annual-return.txt] --- # Annual return URL: https://services.dev/docs/examples/tax/annual-return > A company's return, from the §7216 consent to four accepted filings. A request list the officer answers item by item, a signer who reads last year's return beside this one and signs as the paid preparer for the brand's firm, the officer's Form 8879, and facts the taxpayer keeps for next year. *tax's words: return is a job, taxpayer is a subject, review is a task, preparer is a member (examples/tax/brand.ts).* The brand's largest file, at 45 lines. The AI drafts the return, an adversarial panel checks it, a credentialed signer signs it, and the officer signs its e-file authorization before anything is filed: [the file](https://services.dev/docs/examples/tax/build.md#servicesannual-returnts). The taxpayer is its subject, keyed by EIN, and the tax year is its period, so one taxpayer has one return a year. The keys that make it a return: | Key | Here | What it does | |---|---|---| | `consent` | §7216, `uses: ['prepare']`, `may: [...]`, a year | The officer's consent to use the return's information, and each disclosure she allows: a preparer outside the US, a lender she names. What she leaves out is refused: [the rules table](https://services.dev/docs/examples/tax/rules.md) | | `subject.period` | `'tax_year'` | One return per taxpayer per year. A second answers `409 period_taken`: [Amended return](https://services.dev/docs/examples/tax/amended-return.md) | | `subject.keeps` | `carryforwards`, `tax`, `paid`, `first_installment` | Written by value when a return ends accepted, keyed by its year: the credits, each jurisdiction's tax, what was deposited, and New York's next first installment | | `subject.of_record` | the signer, named at `sign`, `until: 'assessment'` | The signer stays of record for the return until its assessment date. If their credential lapses, another signer covers it, then the brand | | `organizer.items` | `requestList` | The request list your code writes from the job and last year's return | | `roles..pay` | `45 + 15 × jurisdictions`, `90 + 15 × jurisdictions` | Pay that grows with the legs: $105 to sign Acme's four, $150 to repair them | | `sign.stamp` | `{ block: 'paid preparer', firm: 'brand' }` | The signer's name, PTIN and credential go in the paid-preparer block for the brand's firm name and EIN, and the return is filed under the brand's EFIN, so the signer never lends theirs | | `sign.compare` | `'prior'` | The signer's packet holds last year's return beside this one | | `authorize.what` | `authorization`: Form 8879-CORP, or 8879-PE for a partnership | The e-file authorization the officer signs, id-verified, which meets the remote-signing identity check | | `authorize.void` | `{ tolerance: { balance_due: 1 } }` | A $1 change to the balance due voids her Form 8879, and a new one is asked | | `price.within`, `price.late` | `'5d before file'`, `'20%'` | The return is filed five days before its own date to file, and 20% comes off the charge when it's later: [The dates to file and pay](https://services.dev/docs/examples/tax/deadline.md) | | `clocks.file.guarantee` | `{ covers: ['penalties', 'interest on them'], up_to: 5_000, after: 'notice-response', excludes: 'held' }` | A penalty for a date the brand or its member missed, and its interest, is paid from the brand's line once the notice response has asked for it to be taken off; time held on the client is left out: [When a date is missed](https://services.dev/docs/examples/tax/missed.md) | | `ends.accepted.emit` | `'k1.issued'`, one per owner | A partnership's or an S corp's owners each get their K-1 as a fact on their own taxpayer | | `price.lines` | `{ state_fees: { at: 'cost', from: 'file' } }` | A state's fee, off the filing's receipt, passes to the buyer at cost | ## Ordered The order holds $1,800 and waits on Ada, the officer who signs, before anything else: ```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" ← job_4Tx2 · waiting · on party · $1,800.00 held · consent · ask_7Hq2 (consent) ``` ## The §7216 consent, then the organizer She signs the consent through her own link: to prepare, and no disclosure, so the review goes only to members who work in the US. The organizer is a request list your code writes for the year: books, statements, payroll, assets, and an account number for each state: ```txt → POST /asks/ask_7Hq2?t=… {"uses":["prepare"],"may":[]} # Ada Lovelace: consent, §7216 ``` ```txt title="magic values: none" ← 200 done ← job_4Tx2 · waiting · on party · $1,800.00 held · organizer · ask_7Hq3 (organizer) # the organizer: the request list for the year books Read-only access to the books, closed for the year bank Year-end bank and card statements payroll Payroll reports: W-2s, the W-3 and each quarterly 941 assets Assets bought or sold this year ca_account Your CA tax account number ny_account Your NY tax account number nj_account Your NJ tax account number ``` She answers it item by item, and the return goes to a signer: ```txt → POST /asks/ask_7Hq3?t=… {"items":{…7 answered}} # Ada Lovelace: organizer, to upload ``` ```txt title="magic values: none" ← 200 done ← job_4Tx2 · waiting · on claim · $1,800.00 held · sign · tsk_7Hq2 ``` ## Signed, then authorized Katherine Johnson claims the review in her own session, affirms each item on the checklist, the officer's authorization among them, and signs as the paid preparer for apis.tax. This taxpayer has no earlier year on file, so nothing sits beside it; [the plan's year](https://services.dev/docs/examples/tax/years.md) shows 2025 beside 2026: ```txt → POST /practitioners/returns/job_4Tx2/approve {"checklist":["every line traces to a source","due diligence answered","the officer's e-file authorization shows this return's figures"]} ``` ```txt title="200 · magic values: none" ← job_4Tx2 · waiting · on party · $1,800.00 held · authorize · ask_7Hq4 (authorize) ``` Ada signs Form 8879-CORP, id-verified, as an officer: ```txt → POST /asks/ask_7Hq4?t=… {} # Ada Lovelace: authorize, Form 8879-CORP ``` ```txt title="magic values: none" ← 200 done ``` ## Filed The federal return leads, and each state follows. The charge releases when every filing is accepted: ```txt → GET /returns/job_4Tx2 # the buyer ``` ```txt title="magic values: none" ← job_4Tx2 · delivered · workpapers-2026.txt · return.txt · $1,800.00 charged · sbj_7Hq2 rcp_7Hq2 US accepted · filed 2027-02-01 · US 1120 2026 accepted rcp_7Hq3 US-CA accepted · filed 2027-02-01 · after rcp_7Hq2 · US-CA 100 2026 accepted rcp_7Hq4 US-NY accepted · filed 2027-02-01 · after rcp_7Hq2 · US-NY CT-3 2026 accepted rcp_7Hq5 US-NJ accepted · filed 2027-02-01 · after rcp_7Hq2 · US-NJ CBT-100 2026 accepted returns US 1120 2026.txt · US-CA 100 2026.txt · US-NY CT-3 2026.txt · US-NJ CBT-100 2026.txt ``` ```txt → GET /owner/returns/job_4Tx2 # the owner console ``` ```txt title="magic values: none" record consent · owner · §7216 · use: prepare · disclose: none | organizer.books · answered | organizer.bank · answered | organizer.payroll · answered | organizer.assets · answered | organizer.ca_account · answered | organizer.ny_account · answered | organizer.nj_account · answered | organizer · owner · upload | compute · code | draft · ai | check · ai · adversarial · 3 lenses · pass | sign · person · ptin and enrolled agent · * · mbr_8Ea1 · paid-preparer block for apis.tax | authorize · owner · Form 8879-CORP · id-verified | file · IRS and states · efin simulated · 4 accepted ledger +$1,800.00 · AI $1.68 · signer $105.00 · you $1,693.32 ``` In the plan's year, the organizer starts from the 2025 return and compute reads its carryforwards off the taxpayer. [Subjects](https://services.dev/docs/service/subject.md) and [Intake and request lists](https://services.dev/docs/service/intake.md) cover the keys. --- - Up: [The tax example](https://services.dev/docs/examples/tax.md) - Previous: [Tax Plan](https://services.dev/docs/examples/tax/tax-plan.md) - Next: [Federal first, then the states](https://services.dev/docs/examples/tax/efile.md)