# Registrations

> Ownrecord tracks, for each entity and tax regime, whether you're registered, in a grace period, below a threshold or blocked, and checkout follows that state.

To charge tax in a jurisdiction, your entity usually has to be registered there. Some regimes require registration from the first sale; others only once your sales cross a **threshold**. Ownrecord keeps a **registration** for each of your entity's regimes, counts your sales against each threshold, and lets checkout sell only where it's allowed.

Registrations belong to the legal entity, so the sales of all its brands count toward the same thresholds.

## States

| State              | Meaning                                                                        | Consumer sales (B2C)                                     |
| ------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `registered`       | You have a registration number and an effective date.                          | Sell and charge tax.                                     |
| `grace`            | A threshold was crossed and the deadline to register is running.               | Sell and charge tax, held separately until you register. |
| `monitored`        | The regime has a threshold, you're below it and not registered.                | Sell, with the below-threshold rule.                     |
| `pre_registration` | Monitored, and close to the threshold (80% by default).                        | As monitored, with time to prepare.                      |
| `blocked_b2c`      | You must register before selling to consumers, or a grace deadline was missed. | Don't sell. Customers can join a waitlist.               |
| `not_applicable`   | The regime doesn't apply to this entity.                                       | Not applicable.                                          |
| `deregistered`     | You were registered and that registration has ended.                           | Blocked or monitored, depending on the regime.           |

Business customers (B2B) are usually handled with reverse charge. Where a regime allows reverse charge without registration, business customers can buy even while consumer sales are blocked.

## How states change

- As your sales grow, a monitored registration moves to `pre_registration` when it nears the threshold, so you can prepare in time.
- When a sale crosses the threshold, the registration moves to `grace` if its prerequisites are done, and the deadline to register starts. If the prerequisites aren't done, it moves to `blocked_b2c` and you get a critical alert.
- Some regimes have no threshold but allow registering shortly after the first sale. For these, a person on your team **arms** the jurisdiction to confirm the prerequisites are done and someone will register in time. The first sale then starts the grace period.
- When you enter your registration number and effective date, the registration becomes `registered`.
- If the deadline gets close and you haven't registered or recorded that you've applied, Ownrecord blocks new consumer sales there automatically, a safety margin before the deadline (72 hours by default), and alerts you.

When the tax rules change, registrations follow. After each knowledge release, every entity gets a registration for any regime that is new to it, in its default state and in both modes, including entities created before the rules were loaded. Registrations whose regime changed are re-evaluated: for example, if a regime drops its grace period, a registration in grace is blocked and you get an alert. Registrations you've marked registered keep their state.

US states work differently: you may not collect sales tax before you hold a permit. When you cross a state's threshold, Ownrecord by default keeps selling **without** collecting tax until you register. A brand can choose to stop selling there instead.

## Deadlines and alerts

Every grace period has a deadline, worked out from the regime's rules in the jurisdiction's time zone: for example 23:59:59 local time on the 10th of the month after the sale that crossed the threshold. New consumer sales stop automatically a safety margin before it (72 hours by default) unless you've marked the application submitted.

Alerts escalate between the crossing and that automatic stop: when grace starts, at half the time, at 80%, and then daily in the last three days. The last alerts are critical and are emailed to the entity's tax managers and the organization's owners. An hourly job checks every registration in grace, in both modes, raises the alerts once each and applies the automatic stop. Marking the application submitted ends the alerts and the automatic stop while you wait for the registration number.

## Counting sales

Threshold counters belong to the legal entity, so the sales of all its brands count together. They're kept in the threshold's currency per calendar year, or per month for rolling 12-month windows, and they move at the tax point: when a payment is taken for a purchase or top-up, or when an invoice is finalised. A refund takes its amount back out of the window of the original sale. Test-mode sales never move live counters.

When a sale crosses a threshold, the registration changes in the same transaction as the sale, so the sale that crosses is always recorded with the state it triggered.

## Registrations in the console and the API

Open a legal entity and choose **Jurisdictions**. Tax managers, finance, owners, admins and the other entity-wide roles see it; members scoped to one brand don't. The page starts with an overview: how many regimes are registered, in a grace period, blocked for consumers (and how many of those are armed), close to a threshold or monitored, each a filter for the list, and the next deadlines with their countdowns. The list shows every regime with its state and why, how close the entity is to the threshold, the deadline and the prerequisites, with what needs attention first. Regimes that don't apply to the entity are folded away.

Each regime opens its own page: the state and its reason, the deadline countdown and when sales stop automatically, the existing customers (see below), the counters per window, the **prerequisites checklist** (with lead times, an owner, notes and documents), the **playbook** with step-by-step instructions and official links, the regime's rules, the proof on file and the history.

Tax managers, owners and admins act on a registration there or through the API:

| Action                     | Operation                                                                                                                     | Needs                                                                          |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Upload a document          | [`registrations.documents.upload`](https://ownrecord.io/docs/reference/registrations-documents-upload.md)                     | A PDF, PNG, JPEG or WebP file of up to 3 MB, base64-encoded                    |
| Update a prerequisite      | [`registrations.update_prerequisite`](https://ownrecord.io/docs/reference/registrations-update-prerequisite.md)               | Its code; a status, owner, notes or documents (uploaded or references)         |
| Arm                        | [`registrations.arm`](https://ownrecord.io/docs/reference/registrations-arm.md)                                               | `blocked_b2c`, every prerequisite done, a regime with a grace period           |
| Mark application submitted | [`registrations.mark_application_submitted`](https://ownrecord.io/docs/reference/registrations-mark-application-submitted.md) | `grace`, and proof of the submission                                           |
| Mark registered            | [`registrations.mark_registered`](https://ownrecord.io/docs/reference/registrations-mark-registered.md)                       | The number, the effective date and proof; a sign-in within the last 15 minutes |
| Deregister                 | [`registrations.deregister`](https://ownrecord.io/docs/reference/registrations-deregister.md)                                 | `registered`                                                                   |

[`registrations.list`](https://ownrecord.io/docs/reference/registrations-list.md) and [`registrations.get`](https://ownrecord.io/docs/reference/registrations-get.md) read them, with [`registrations.history`](https://ownrecord.io/docs/reference/registrations-history.md) and [`registrations.affected_customers`](https://ownrecord.io/docs/reference/registrations-affected-customers.md); `registrations.get` also says which actions the registration allows right now and why the others don't apply. You can name a registration by its ID (`regn_…`) or by its regime's ID, such as `EU_OSS_UNION` or `US_SALES_TAX:TX`.

Arming, marking submitted, marking registered and deregistering are compliance actions: if your organization's approval policy lists one, it waits for a second person's approval. Every action is kept in the registration's history with who did it and your note, and in the audit log. Changes are announced with the `registration.state_changed`, `registration.updated`, `registration.deadline_escalated` and `threshold.crossed` events.

**Documents and proof.** Upload documents to a registration: the submission receipt, the registration confirmation, a company register extract for a prerequisite. A document is a PDF, PNG, JPEG or WebP file of up to 3 MB; its type is read from the file itself, and it is stored privately. In the console, choose the file in a prerequisite's form or in the **Mark application submitted** and **Mark registered** dialogs. Over the API, [`registrations.documents.upload`](https://ownrecord.io/docs/reference/registrations-documents-upload.md) takes the file base64-encoded and returns its `file_…` ID, which you then give as the `reference` of a prerequisite's attachment or of the proof. A `file_…` reference must be a document of the same registration. Proof can also be a reference to a document you keep elsewhere: the tax authority's receipt or application number, or a link to it in your own storage (links open only when they are `https` or `http` addresses). Uploaded documents open from the registration's page, only for people who can see the registration, and only while the file still matches the SHA-256 recorded at upload; [`registrations.documents.get`](https://ownrecord.io/docs/reference/registrations-documents-get.md) returns a document's details.

**History.** [`registrations.history`](https://ownrecord.io/docs/reference/registrations-history.md) returns one timeline, newest first: every state change with who made it, why and their note; what the audit log recorded about the registration, such as prerequisite updates and uploaded documents, with what changed; and the deadline reminders. The registration's page shows it.

The effective date is read as the start of that day in the jurisdiction's time zone. For US states, no sales tax is collected before it.

## Existing customers when consumer sales are blocked

Blocking a regime stops **new** consumer sales. Customers the entity already sold to there, during a grace period or while registered, keep their subscription renewals, credit top-ups and refunds: the tax obligation already exists, so tax keeps being charged. Tax charged before the entity is registered is held in the ledger as **pending registration** (`tax_pending_registration`), per regime and jurisdiction: that is the open liability you owe once you register. When you mark the registration registered, Ownrecord moves that balance to `tax_payable` in the same step (a `tax_transfer` ledger transaction linked to the registration), so it is filed with the tax you charge as registered.

A blocked, grace or deregistered regime's page lists these customers, all brands combined: the tax pending registration for each (net of refunds), the tax charged while registered, the jurisdictions and the last sale, with the regime's open liability per jurisdiction. Names and emails show only to people who can read that brand's customers. [`registrations.affected_customers`](https://ownrecord.io/docs/reference/registrations-affected-customers.md) returns the same list, with amounts linked to no customer (a manual ledger adjustment, for example) as `unattributed`, so the customers and `unattributed` add up to the ledger balances.

## Demand: where it pays to register

Open a legal entity and choose **Demand** to see where its customers are waiting or were turned away, all brands combined, in the current mode. There is one row per country (or US state, or territory) with:

- the **waitlist**: how many customers wait for you to sell there, how many haven't confirmed their email yet, were already told you can sell, or left the waitlist;
- the **estimated monthly value** of what the waiting customers wanted to buy, per currency: recurring prices count per month (a yearly price a twelfth, a weekly one 52 twelfths), one-time prices and credit packs count once, as a first month's purchase;
- **blocked checkouts** in the window you choose (3 to 36 months): checkouts paused for the customer's location, once per checkout and reason;
- the **regimes** that apply there, each linked to its registration page: the registration's state, the prerequisites with their lead times and status, the **lead time** (the longest of what isn't done yet) and the **compliance effort**: a fiscal representative, a local agent, how often you file.

Sort by any of these, open a row's split by brand, or show one brand only, and export the table as CSV. The page names no customer: it holds counts and amounts. The same roles as **Jurisdictions** see it; members scoped to one brand don't. Over the API: [`waitlist.demand.list`](https://ownrecord.io/docs/reference/waitlist-demand-list.md); a key without `registrations:read` gets the regimes without their registration.

## Who registers

Ownrecord doesn't log into government portals. It turns each obligation into **tasks**: complete the prerequisites, prepare the registration, submit it, then confirm the number. Each task comes with a registration packet (your entity's details, prepared for that regime's form) and step-by-step instructions. A person on your team, or an authorized agent, does the registration and reports back with the evidence. See [Building an agent on Ownrecord](https://ownrecord.io/docs/guides/building-an-agent.md).

Registrations exist separately in [test and live mode](https://ownrecord.io/docs/concepts/test-and-live-mode.md), so you can practise the whole flow on test data.