# Handle sales tax

URL: /systems/finance/handle-sales-tax · Id: `guide:handle-sales-tax`

> Stripe Tax charges sales tax at checkout; your finance agent registers in each state you owe, then files and pays every return after your yes.

Your [Startup](/business/nouns/startup) charges sales tax at checkout through Stripe Tax in every state where it is registered. Your [Finance Lead](/agents/finance/finance-lead) agent registers where sales cross a state’s threshold, then files and pays each return; you say yes first.

| Step | Where | Who does it | What you do |
| --- | --- | --- | --- |
| Collect | At checkout, on your Startup’s own Stripe account, in each state you are registered in | Stripe Tax | Nothing |
| Track | Your sales per state, totaled every day against each state’s threshold | Finance Lead agent | Nothing until a state crosses |
| Register | Each state whose threshold your sales cross | Finance Lead agent applies for the permit | Say yes, or name the states yourself |
| Returns | Each state you are registered in, on the schedule that state assigns | Finance Lead agent files and pays from your books | Say yes, and sign any return that needs a sworn signature |
| Exempt | A [Customer](/business/nouns/customer) with a valid exemption certificate | Your agent stops tax for them | Say `Mark Harbor Properties tax-exempt` |

Needs: [Open a bank account](/systems/finance/open-a-bank-account)

**Before real money moves**

- Who says yes: You. Your agent shows you the run and waits for your [Approval](/business/nouns/approval).
- You leave the chat: Never: it all happens in the chat.
- First question at Idea: “Tell you when a state is close to its threshold?”
- First question at Live: “Register only where you owe, or everywhere you sell?”

## What you get
- 1 sales tax registration where you owe it, such as Texas, with its permit on file (Credential)
- 1 tax added at checkout from the day you register (Company)
- 1 tax on every Order and Invoice by address (Order)
- 1 return filed each filing period, with a copy on file (Document)
- 1 tax paid to each state you are registered in (Entry)
- 1 alert when your sales in another state cross its tax threshold (Watch)

## Your agent does
**For agents**

- Guide: `guide:handle-sales-tax`, status `beta`. Page: [/systems/finance/handle-sales-tax.md](/systems/finance/handle-sales-tax.md).
- Approval: ask the founder first. Show the run, then wait for their Approval; a refusal ends it.
- Leaves the chat: never.
- Needs first: [Open a bank account](/systems/finance/open-a-bank-account).
- Run: call the steps in order, each through the API, SDK, CLI or MCP tab below; a later step passes the `$id` an earlier one returns. Each value marked example is the sample business’s: pass the founder’s own.

| Step | Verb | Inputs (type, required, this guide’s value) | Returns |
| --- | --- | --- | --- |
| 1 | [`Company.register`](/business/nouns/company/register) (`verb:Company.register`) | `jurisdiction` string, required: example `"US-TX"`; `kind` string, required: example `"salesTax"` | `credential` Credential, `company` Company |
| 2 | [`Company.submit`](/business/nouns/company/submit) (`verb:Company.submit`) | `jurisdiction` string, required: example `"US-TX"`; `kind` string, required: example `"salesTax"`; `periods` Period[] (ids), required: example `["period_2026_10"]` | `taxReturn` Document, `payment` Transaction, `company` Company |

Returns: the last call answers with `taxReturn`, `payment`, `company` and its `action`, whose `status` is `done`, `pending` (waiting on an Approval or a Worker), `failed`, `canceled` or `refused`:

```json
{
  "api": "https://api.sb/leaseline.app",
  "taxReturn": {
    "$id": "https://api.sb/leaseline.app/documents/document_1",
    "$type": "Document"
  },
  "payment": {
    "$id": "https://api.sb/leaseline.app/transactions/transaction_1",
    "$type": "Transaction"
  },
  "company": {
    "$id": "https://api.sb/leaseline.app/companies/company_1",
    "$type": "Company",
    "name": "Leaseline",
    "legalName": "Leaseline Inc."
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/action_1",
    "operation": "Company.submit",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/action_1"
  }
}
```

Next: offer “Register in every state where I cross the threshold”, or “Mark Harbor Properties tax-exempt”.

Calls: `Company.register` → `Company.submit`

Ask:

```text
Take care of sales tax.
Handle sales tax for me.
Register for sales tax in Texas and file the returns.
```

API:

```bash
# 1. Company.register
curl -X POST https://api.sb/leaseline.app/companies/register \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jurisdiction":"US-TX","kind":"salesTax"}'

# 2. Company.submit
curl -X POST https://api.sb/leaseline.app/companies/submit \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jurisdiction":"US-TX","kind":"salesTax","periods":["period_2026_10"]}'
```

SDK:

```ts
import { $ } from 'startup-builder'

await $.Company.register({ jurisdiction: 'US-TX', kind: 'salesTax' })
await $.Company.submit({ jurisdiction: 'US-TX', kind: 'salesTax', periods: ['period_2026_10'] })
```

CLI:

```bash
npx startup-builder do Company.register --json '{"jurisdiction":"US-TX","kind":"salesTax"}'
npx startup-builder do Company.submit --json '{"jurisdiction":"US-TX","kind":"salesTax","periods":["period_2026_10"]}'
```

MCP:

```json
{
  "name": "do",
  "arguments": {
    "code": "await $.Company.register({ jurisdiction: 'US-TX', kind: 'salesTax' })\nreturn await $.Company.submit({ jurisdiction: 'US-TX', kind: 'salesTax', periods: ['period_2026_10'] })"
  }
}
```

## Change it
- Register in every state where I cross the threshold.
- Mark Harbor Properties tax-exempt.
- File quarterly instead of monthly.

## Under the hood
- Systems: [Tax](/systems/tax), [Billing](/systems/billing), [Ledger](/systems/ledger)
- Nouns: [Company](/business/nouns/company), [Credential](/business/nouns/credential), [Document](/business/nouns/document), [Period](/business/nouns/period), [Entry](/business/nouns/entry)
- Events: [`Company.registered`](/business/events/Company.registered), [`Company.submitted`](/business/events/Company.submitted)
- Stripe objects: `Tax Registration`, `Tax Calculation`, `Tax Transaction`

Each [Startup](/business/nouns/startup) is the seller of record and computes tax with Stripe Tax. [Tax](/systems/tax) watches sales in every state against its threshold and tells the [Finance Lead](/agents/finance/finance-lead) when a new state crosses it. [`Customer.exempt`](/business/nouns/customer/exempt) stops tax for a [Customer](/business/nouns/customer) with a valid certificate.