Tax on your online store

Tuppence works out the tax on every store order: the rate, the rounding and the total the shopper sees first are the ones they pay. You are always the seller, so every tax line is yours. You tell Tuppence where you are registered; it never decides that for you.

UK VAT. The store charges VAT only once your business details say you are VAT registered (settings.trader.vat_registered). Unanswered, it charges none and shows no VAT, which is right for a business under the threshold. Rates come from your country’s tax pack.

US sales tax. The store charges a state’s sales tax, worked out at the delivery address, only in the states where you record a registration. Everywhere else it charges none, and the order records why (not_collecting).

Scroll sideways to see all of it →

1. Record where you are registered

A US state’s sales tax, by its two-letter code, with your permit number if you want it on your documents. Selling from the US to the UK, record your UK VAT number the same way (country: "GB", type: "standard").

curl

curl -sS https://api.tuppence.ai/v1/tax_registrations \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "NY", "number": "NY-123456"}'

Node

import { Tuppence } from "@tuppence/node";

const tuppence = new Tuppence(process.env.TUPPENCE_SECRET_KEY);
const registration = await tuppence.request("POST", "/v1/tax_registrations", {
  body: { state: "NY", number: "NY-123456" },
});

Python

import os
from tuppence import Tuppence

tuppence = Tuppence(os.environ["TUPPENCE_SECRET_KEY"])
registration = tuppence.request("POST", "/v1/tax_registrations", body={"state": "NY", "number": "NY-123456"})

Caution

A registration can’t be removed once recorded. Record only the states where you hold a permit.

2. Watch your thresholds

GET /v1/tax_nexus lists every US state with a sales tax, nearest its threshold first: what you sold into it over the state’s own period (marketplace sales apart), the threshold with its source, and whether you are registered. It is counted every night at 02:30 in your time zone.

status	Means
below	Under 80 % of the state’s threshold
near	From 80 %. store.tax_threshold_near is sent once that period
over	At or past the threshold. store.tax_threshold_reached is sent once that period

Whether to register is your decision, with your accountant. A registered state sends no notices.

3. Read a location’s settings

The location you ship from is where your prices’ tax settings live: whether prices include tax, rounding, registration numbers and automatic US sales tax. Read and change them with GET and POST /v1/locations/{id}/tax. A change never reprices a paid order.

Events

Event	When
tax_registration.created	You record a registration
store.tax_threshold_near	A state passes 80 % of its threshold
store.tax_threshold_reached	A state reaches its threshold

Over MCP and the assistant

Tool	Scope	Does
get_tax_settings	tax:read	The ship-from location’s tax settings
list_tax_registrations	tax:read	The registrations you hold
get_nexus_status	tax:read	States near, over or registered (or one, or all)
add_tax_registration	tax:write	Records a registration. A person approves it, every time

No tool works out a tax amount or says whether you must register.

Next

• Your store’s policies
• Selling abroad