---
title: "The tax example"
url: https://services.dev/docs/examples/tax
captured: [tax-check.txt, tax-suite.txt, tax-years.txt]
---
# The tax example

URL: https://services.dev/docs/examples/tax

> A brand shaped like apis.tax. Ten Services a business-return practice sells, its own Pool of preparers, signers and representatives on gigs.tax, accountants from gigs.accountants, one rules table, a lender line on the same consent, and a client's years run on a test clock.

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

The tax example is a brand shaped like apis.tax, built from one folder: its words and calendar, [a rules table](https://services.dev/docs/examples/tax/rules.md), one Pool and ten Services. AI does the work on every return. Each licensed act is a step a credentialed person attests: a preparer with a PTIN prepares, a CPA or an enrolled agent signs for the brand's firm, and a representative answers the IRS under a Form 2848 that names them.

It proves Time: a Tax Plan whose years run, facts kept from one year to the next, and clocks that file each state's extension by its own rule.

| Who | What you get |
|---|---|
| The business | One price a year for its 1099s, returns, estimates, questions and notices, or each at its own price. Each return promised five days before its date, and a penalty for a date the brand missed paid back, up to $5,000: [When a date is missed](https://services.dev/docs/examples/tax/missed.md) |
| The officer | Her own links for every act that's hers: the §7216 consent, each organizer item, each return's Form 8879, each estimate's decision and each Form 2848. No account |
| The signer | $45 and $15 a jurisdiction for each signature, $105 on a four-state return, payable two days after the act and paid that evening, with last year's return beside this one: [the delivery portal](https://services.dev/docs/examples/tax/delivery-portal.md) |
| The preparer | $90 and $15 a jurisdiction to repair a rejection no route names; a California leg asks for a CTEC registration or a CPA, EA or bar card: [the preparers' Pool](https://services.dev/docs/examples/tax/pool.md) |
| The representative | $90 to answer a notice under a Form 2848 that names them by CAF number: [Notice response](https://services.dev/docs/examples/tax/notice-response.md) |
| The accountant | $250 to attest a year-end close, from gigs.accountants: [Year-end close](https://services.dev/docs/examples/tax/year-end-close.md) |
| The lender | A return the brand filed, read on the §7216 consent that names it, or a transcript on a Form 4506-C, every field cited to its form, year and line, $12 a year: [Tax transcript](https://services.dev/docs/examples/tax/transcript.md) |

Like apis.tax, it sells two lines, joined by one consent: the §7216 consent the officer signs before a return is prepared says where its information may go, so a lender it names reads the filed return. Every rules row is illustrative, and no figure is tax advice.

## The gate

The acceptance test is one walk: the plan's first year on a test clock, `tick 1y`, then thirteen days into the next. Every line must hold:

```txt
→ GET /taxpayers/sbj_7Hq2
```

```txt title="magic values: owner.email = signs@example.test, metadata.sandbox.asks = {"organizer.books":"after 160d","organizer.assets":"waive","organizer #2":"after 2d","w9":"after 19d"}, metadata.sandbox.outside = {"reject":{"file.US-NY":["ein_mismatch"]}}, metadata.sandbox.events = { notice.received: { at: 2027-11-14T15:00:00Z, data: { notice, reply_by, tax_years } } }"
  period  2025     annual-return        job_4Tx2 · accepted
  period  2026     information-returns  job_4Tx1 · accepted
  period  2026     annual-return        job_4Tx3 · accepted
  period  2027-Q1  estimate             job_4Tx4 · accepted
  period  2027-Q2  estimate             job_4Tx5 · accepted
  period  2027-Q3  estimate             job_4Tx6 · accepted
  period  2027-Q4  estimate             job_4Tx8 · accepted
  period  2027     information-returns  job_4TxA · delivered
  period  2027     annual-return        job_4Tx9 · waiting
  keeps   paid          2026    US $73,710 · US-CA $6,205 · US-NY $7,605 · US-NJ $6,318, with the extension · job_4Tx3 at pay · 2027-07-20
  keeps   paid          2027-Q1 US $16,223 · US-CA $1,639 · US-NJ $1,391 · job_4Tx4 at record · 2027-04-12
  keeps   paid          2027-Q2 US $16,222 · US-CA $2,185 · US-NY $1,447 · US-NJ $1,390 · job_4Tx5 at record · 2027-06-12
  keeps   paid          2027-Q3 US $22,838 · US-NY $2,356 · US-NJ $1,958 · job_4Tx6 at record · 2027-09-12
  keeps   paid          2027-Q4 US $18,427 · US-CA $2,381 · US-NY $1,901 · US-NJ $1,579 · job_4Tx8 at record · 2027-12-12
# the gate, read off the run: the tax brand holds each line
  periods     2026, 2027 minted, each free · their 1099s too, 11 payees of 25
  read        carryforwards off 2025 (job_4Tx2), by value: 2 in, $14,907; 3 out, $26,131
  filed       1 federal and 3 linked state returns · the tentative tax deposited, then each extension its state's rule needs, proposed by a rung (by: clock, owed 2027-04-12 13:00)
  extended    US, US-NY to 2027-10-15 · US-NJ to 2027-11-15 · US-CA to 2027-11-15, automatic, no filing
  paid        2026: $95,739 with the extension, credited on the return · balance due $0.00
  repaired    US-NY ein_mismatch · refiled 2027-07-13, keeps 2027-07-11 · US-NJ filed 2027-07-11, on time
  estimates   4 kept by quarter, each state its own · Q3 catches up the $4,410 Q1 and Q2 were short · the 2027 organizer asks: Confirm the 4 federal payments for 2027, $73,710 in all
  notice      CP161 for 2026: rcp_7HqB found posted to 2027 · a transfer request under a Form 2848 naming mbr_8Ea1
  2027        file due 2028-04-18, rolled from 2028-04-15 (weekend, holiday) · US-NJ and US-TX 2028-05-15 · America/New_York
  renewed     cycle 2 · allowances reset
  folded      15 clocks, each rebuilt from its events alone: every one the same
```

[A year, and the next](https://services.dev/docs/examples/tax/years.md) walks it.

## Its suite

The brand's suite, generated from its contract, runs every row over HTTP and MCP, the Pool, clocks, taxpayers and plan included. A skipped case never counts as a pass:

```bash
npx services.dev verify --surface all
```

```txt title="magic values: metadata.sandbox.review = pass, metadata.sandbox.review = flag_once, party.email = signs@example.test, party.email = declines@example.test, party.email = silent@example.test, metadata.sandbox.talk = open, watch.url = https://fails-once.example.test/suite, watch.url = https://down.example.test/suite, watch.url = https://hooks.example.test/suite, member = mbr_eligible, member = mbr_lapsed_credential"
tax · 229 HTTP cases and 29 MCP cases from 84 rows: each row by its live credentials and magic values, with its auth, audience, replay and next cases · http://localhost:8787/verify/suite.json
258 passed · 0 failed · 89 skipped
  live mode only, run with --live: credential sk_live_ · 31 rows
  live mode only, run with --live: credential dlg_ · 26 rows
  live mode only, run with --live: credential tk_ · 15 rows
not in tax's contract: job.policy and job.signal, which no tax Service names
```

## The ten Services

| Service | Price | Charged on | The person, and their pay | Its page |
|---|---|---|---|---|
| Tax Plan | $2,400 a year | the start of each year | none: it orders five Services inside allowances, and an amendment at its own price | [Tax Plan](https://services.dev/docs/examples/tax/tax-plan.md) |
| Annual Return | $1,800, 20% off if late; state fees at cost | every filing accepted | a signer, $45 and $15 a jurisdiction; a preparer on a repair, $90 and $15 a jurisdiction | [Annual return](https://services.dev/docs/examples/tax/annual-return.md) |
| Estimated Payment | $79 | delivery | none: the company's officer decides | [Estimated payment](https://services.dev/docs/examples/tax/estimate.md) |
| Tax Question | $49 | delivery | a signer adopts, revises or refuses an answer that is advice, $25 | [Tax question](https://services.dev/docs/examples/tax/question.md) |
| Notice Response | $299, $99 answered yourself, or 25% of a penalty abated | the sent response's receipt | a representative under a Form 2848, $90 | [Notice response](https://services.dev/docs/examples/tax/notice-response.md) |
| Amended Return | $900 | every filing accepted | a preparer, and another member who signs | [Amended return](https://services.dev/docs/examples/tax/amended-return.md) |
| Carryforward Watch | $9 a year | the start of each year | none: the brand answers for the dates a return leaves | [Carryforward watch](https://services.dev/docs/examples/tax/carryforward-watch.md) |
| Year-End Close | $300, or $900 with an accountant's approval | delivery | an accountant from gigs.accountants, $250, when the order asks | [Year-end close](https://services.dev/docs/examples/tax/year-end-close.md) |
| Information Returns | $15 a payee | the filing's receipt | none: the brand files under its own codes | [Information returns](https://services.dev/docs/examples/tax/information-returns.md) |
| Tax Transcript | $12 a year | the order's receipt, or the disclosure | none: it reads under the brand's own credential, or the consent | [Tax transcript](https://services.dev/docs/examples/tax/transcript.md) |

## The line that makes it

One subscription across six Services, five inside its allowances and the amendment at its own price:

```ts title="tax · services/tax-plan.ts"
  on: {
    schedule: {
      information: { order: informationReturns, each: 'year', at: '5d after end', catch_up: 'open' },
      annual: { order: annualReturn, each: 'tax_year', at: '1mo after end', catch_up: 'open' },
      estimate: { order: estimate, each: 'quarter', at: '10d before pay', when: sub => sub.input.entity === 'C corp' },
    },
    event: { 'question.asked': question, 'notice.received': noticeResponse, 'fact.restated': amendedReturn },
  },
```

## Its plans

```txt title="services.dev check --plan"
# Free · returns you prepare and sign yourself, as an enrolled agent or CPA, one tax year per job; transcripts alongside
#   who: you sign, staff repair rejections
#   sides: you sign, so a return's $1,800.00 is yours less AI: no preparer's $150.00 or signer's $105.00 to pay
# Launch · a small practice: you, two staff and five members, or a rented Pool; returns, estimates and the Tax Plan
#   who: up to five members sign, or a rented door's preparers
#   sides: the Tax Plan's cycle leaves $2,100.00 of $2,400.00 after the signer's $210.00 and the representative's $90.00
# Team · full depth: a door of its own, standby for the season, the custodian ladder
#   who: a season's market on its own door, on standby
#   sides: a door of your own pays no placement, and standby fills both windows at its retainer instead of ladder raises

$ npx services.dev check --fit free services/annual-return.ts
services/annual-return.ts · Annual Return · $1,800 per return, filed 5 days before its deadline, 20% off if late, or we pay the penalty and its interest, up to $5,000, after we ask the IRS to take it off, charged when the federal return is accepted
  fit     Free (services.dev), with 7 changes
          brand.ts:9                    − domain: 'apis.tax',  → the brand serves on apis-tax.builder.domains
          services/annual-return.ts:29-33  − subject: { … }  → each return is one tax year's job: last year's figures come in on the organizer
          services/annual-return.ts:34  − roles: { preparer: { pool: preparers, pay: job => 90 + 15 * job.input.jurisdictions.length }, signer: { pool: preparers, pay: job => 45 + 15 * job.input.jurisdictions.length } },  + roles: { preparer: { credential: 'ptin' }, signer: { credential: { all: ['ptin'], any: ['cpa', 'enrolled agent'] } } },  → you sign as the enrolled agent or CPA, and a staff preparer with a PTIN repairs rejections, from the owner console
          services/annual-return.ts:53  − , guarantee: { covers: ['penalties', 'interest on them'], up_to: 5_000, after: 'notice-response', excludes: 'held' }  → the 20% off a late return is the promise you sell
          services/annual-return.ts:55  − assessment: { due: assessmentCloses, owner: 'brand', lives_on: 'subject', rungs: ['notice 30d'] },  → you keep the assessment date yourself
          services/annual-return.ts:56  − refund: { due: refundCloses, owner: 'of_record', lives_on: 'subject', hard: { bars: [{ step: 'amended-return.file', when: claimsRefund }] } },  → and the refund date
          services/annual-return.ts:57  − expiring: { due: earliestExpiry, owner: 'brand', lives_on: 'subject', rungs: ['notice 180d'] },  → the file and pay clocks stay on the job
  plan    Free (services.dev) · on the floor: the signature reserved to a PTIN and a CPA or enrolled agent, and the e-file under the brand's EFIN
          the gate reads each Service: transcripts sell beside it on Free, under the brand's participant status
  sides   you sign, so a return's $1,800.00 is yours less AI: no preparer's $150.00 or signer's $105.00 to pay

$ npx services.dev check --fit launch
  fit     Launch (services.dev), with 8 changes
          pools/preparers.ts:11         − door: 'gigs.tax',  → the Pool serves at apis.tax/practitioners
          pools/preparers.ts:29         − firms: true,  → each member clears conflicts on their own ledger
          pools/preparers.ts:30         − affinity: '14d',  → next year's return is offered to the Pool, the signer of record among them
          pools/preparers.ts:32-35      − standby: [ … ]  → the season fills on the default ladder's raises
          services/annual-return.ts:31  − , custodian: ['signer', 'brand']  → the signer who signs stays of record
          services/annual-return.ts:32  − , steward: carryforwardWatch  → the client keeps each date a return leaves on the taxpayer
          services/annual-return.ts:53  − , guarantee: { covers: ['penalties', 'interest on them'], up_to: 5_000, after: 'notice-response', excludes: 'held' }  → a penalty for a late return is the client's, as the agency charges it
          services/tax-plan.ts:29       − , 'fact.restated': amendedReturn  → a restated fact offers the amendment from the return that read it
  plan    Launch (services.dev) · a small practice: you, two staff and five members, or a rented Pool; every clock, the Tax Plan and its allowances
  sides   the Tax Plan's cycle leaves $2,100.00 of $2,400.00 after the signer's $210.00 and the representative's $90.00

$ npx services.dev check --plan
apis.tax · 13 files · 10 Services, 1 Pool and 1 imported, rules 2026-10 and the brand
  plan    Team (services.dev) · the highest plan a file needs · each Service runs live on its own
  Free    rules.ts                      on the floor: every reserved act signed by a credentialed person, or by the taxpayer for themselves
          services/transcript.ts        no gated key · ives is named by a Rules row, so the brand's credential is on the floor
  Launch  brand.ts                      Brand.domain at :9
          services/amended-return.ts    subject at :20 · roles.preparer.pool at :21
          services/carryforward-watch.ts  subject at :11 · clocks.lives_on: 'subject' at :13 · price.every at :14
          services/estimate.ts          subject at :17, and the payment it keeps
          services/information-returns.ts  subject at :15
          services/notice-response.ts   subject at :19 · roles.representative.pool at :20 · price.outcome at :32, the fee on a penalty abated
          services/question.ts          subject at :14 · roles.signer.pool at :15
          services/year-end-close.ts    subject at :16 · pool: '<door>/<pool>' at :17, gigs.accountants/accountants, a Pool another operator runs, with its placement line
  Team    pools/preparers.ts            Pool.door at :11 · gigs.tax, a door your account operates · Pool.firms at :29 · Pool.affinity at :30 · Pool.standby at :32
            also Launch                 Pool({...}) at :9 · Pool.payouts.schedule at :36
          services/annual-return.ts     subject.of_record.custodian at :31 · subject.steward at :32 · clocks.<c>.guarantee at :53
            also Launch                 subject.keeps at :32 · clocks.lives_on: 'subject' at :55, :56 and :57, the assessment, refund and expiring clocks
          services/tax-plan.ts          on.event at :29, past the Tax Plan's allowance: fact.restated mints an amended return
            also Launch                 subject at :22 · on.schedule at :24 · price.every at :31
          every key runs in test on any plan · deploy --live asks for each key's plan once its three sampled jobs release
  sides   a door of your own pays no placement, and standby fills both windows at its retainer instead of ladder raises
```

## The files

`check` reads the folder back; [Build it](https://services.dev/docs/examples/tax/build.md) adds each file.

```bash
npx services.dev check
```

```txt title="magic values: none"
brand.ts · 9 lines · tax · apis.tax · words job → return, subject → taxpayer, task → review, member → preparer · holds efin, iris, tin_matching, ives
rules.ts · 37 lines · rules 2026-10 · 6 Services · 23 rows · the taxpayer may answer a notice themselves · no fee rides on a return as filed
pools/preparers.ts · 27 lines · practitioners · 3 roles: preparer, signer, representative · joins in 3 steps on gigs.tax · feed · hold 24h
services/amended-return.ts · 22 lines · $900 per job, within 30 days, charged when file or aar is accepted.
services/annual-return.ts · 45 lines · $1,800 per job, filed 5 days before its deadline, 20% off if late, or we pay the penalty and its interest, up to $5,000, after we ask the IRS to take it off, charged when file is accepted.
services/carryforward-watch.ts · 8 lines · $9 per year, charged at the start of each year.
services/estimate.ts · 17 lines · $79 per job, within 48 hours, charged on delivery.
services/information-returns.ts · 17 lines · $15 per payee, charged when file is accepted.
services/notice-response.ts · 19 lines · $299 per job, or $99 if you answer it yourself, or 25% of a penalty abated, $99 at least, within 48 hours, charged on send's receipt.
services/question.ts · 10 lines · $49 per job, within 48 hours, charged on delivery.
services/tax-plan.ts · 18 lines · $2,400 per year, charged at the start of each year, 1 annual-return, 25 information-returns payees, 4 estimate, 12 question and 2 notice-response included each year.
services/transcript.ts · 18 lines · roadmap · $12 per job, within 48 hours, charged on order's receipt, or at disclose for a return the brand filed.
services/year-end-close.ts · 15 lines · $300 per job, or $900 with an accountant's approval, within 48 hours, charged on delivery.
✓ ready to sell · 10 Services · AI delivers 2 alone · each keeps at least 50% of every job
```

## The pages

| Page | What it shows |
|---|---|
| [Build it](https://services.dev/docs/examples/tax/build.md) | Each file, with `check` after it |
| [One job, every side](https://services.dev/docs/examples/tax/walk.md) | One year's return, as the buyer, the officer, the signer and the owner see it |
| [The agent's order](https://services.dev/docs/examples/tax/agent.md) | A bookkeeping agent buys the plan, answers the organizer it holds, and hands the officer her links |
| [Every branch](https://services.dev/docs/examples/tax/branches.md) | Each human and outside branch, and the value that produces it |
| [The customer portal](https://services.dev/docs/examples/tax/customer-portal.md) | The business's screens across the year |
| [The delivery portal](https://services.dev/docs/examples/tax/delivery-portal.md) | One enrolled agent's season, from joining to leaving |
| [The owner console](https://services.dev/docs/examples/tax/console.md) | Ten returns after the year, by Service, with the dates ahead |
| [The money](https://services.dev/docs/examples/tax/money.md) | Every way the brand earns, and what each person is paid |
| [What the brand gets](https://services.dev/docs/examples/tax/surfaces.md) | API, CLI, MCP, SDK, Site, Docs and App, in return words |
| [The rules table](https://services.dev/docs/examples/tax/rules.md) | Who may prepare, sign, file, disclose, represent and advise, and the fee no return may carry |
| [The preparers' Pool](https://services.dev/docs/examples/tax/pool.md) | Three credentialed roles, two doors, what protects a member, and the seat of record |
| [The season](https://services.dev/docs/examples/tax/season.md) | Standby in two windows, the fill ladder under load, and the extension as a valve |
| [A year, and the next](https://services.dev/docs/examples/tax/years.md) | The `tick 1y` walk |
| [Two clients, over the years](https://services.dev/docs/examples/tax/clients.md) | A client who changes, amends and leaves, a partnership's K-1s, and a second client on its own year |
| [The dates to file and pay](https://services.dev/docs/examples/tax/deadline.md) | The date to file and the date to pay, four states' extension rules, and the deposit the return credits |
| [Tax Plan](https://services.dev/docs/examples/tax/tax-plan.md) | One subscription routed to six Services, with allowances |
| [Annual return](https://services.dev/docs/examples/tax/annual-return.md) | The §7216 consent, kept facts, last year beside this one, and a signature for the brand's firm |
| [Federal first, then the states](https://services.dev/docs/examples/tax/efile.md) | One filing per jurisdiction, a coded rejection, a repair that keeps its time |
| [Estimated payment](https://services.dev/docs/examples/tax/estimate.md) | Each state's installment, the safe harbor, and a quarter that catches up |
| [Tax question](https://services.dev/docs/examples/tax/question.md) | An answer the signer adopts, revises or refuses |
| [Notice response](https://services.dev/docs/examples/tax/notice-response.md) | A CP161, a misapplied payment found by its receipt, and a Form 2848 that names the representative |
| [Amended return](https://services.dev/docs/examples/tax/amended-return.md) | `period_taken`, the amendment as its own return, and a partnership's AAR |
| [Carryforward watch](https://services.dev/docs/examples/tax/carryforward-watch.md) | The dates a return leaves, kept by the brand |
| [Year-end close](https://services.dev/docs/examples/tax/year-end-close.md) | The books closed by AI, and an accountant's approval sold on top |
| [Information returns](https://services.dev/docs/examples/tax/information-returns.md) | The year's 1099s, W-9s asked, TINs matched, filed by 31 January |
| [Tax transcript](https://services.dev/docs/examples/tax/transcript.md) | The lender line: a filed return on the §7216 consent, or a transcript on a 4506-C |
| [When a date is missed](https://services.dev/docs/examples/tax/missed.md) | Whose date it was, the penalty notice, and the credit back |
| [Porting apis.tax](https://services.dev/docs/examples/tax/port.md) | Every flow of the live door, matched, adapted or decided |
| [Take your first real return](https://services.dev/docs/examples/tax/launch.md) | Every outside system a real return depends on, and the contract it meets |

---

- Up: [Examples](https://services.dev/docs/examples.md)
- Previous: [Take your first real matter](https://services.dev/docs/examples/legal/launch.md)
- Next: [Build it](https://services.dev/docs/examples/tax/build.md)