# Customers

> A customer is a buyer of one brand. Ownrecord keeps its tax IDs with their verification, the location evidence of each purchase, and the country its purchases are taxed in.

A **customer** is someone who buys from one of your brands: a consumer or a business. Customers belong to one brand and one mode, so the same email address in two brands, or in test and live mode, is two customers. Within a brand and mode, an email address belongs to one active customer, because checkout recognises returning buyers and the customer portal signs them in by email.

Checkout creates customers itself. You can also create them ahead of a sale, from your own sign-up, through the API or in the console.

## Type

Every customer has a **type**: `individual`, `business` or `unknown`. Ownrecord infers it:

- a tax ID makes the customer a `business`, unless the tax register rejected it;
- otherwise a customer you declare as a business with a business name is a `business`;
- a customer you declare as an individual is an `individual`;
- anything else is `unknown`.

The type describes the customer; it doesn't decide the tax. Each sale is classified on its own: only a **valid** tax ID makes a sale business-to-business, so a business whose VAT ID can't be confirmed is taxed as a consumer.

## Tax IDs

A customer can have up to five tax IDs. Each one is checked when it's added, before anything is stored:

| Type                    | Checked with                     |
| ----------------------- | -------------------------------- |
| `eu_vat`                | VIES, the EU's VAT register      |
| `gb_vat`                | HMRC's "Check a UK VAT number"   |
| `ch_uid`, `ch_vat`      | The Swiss UID register           |
| `no_org`, `no_vat`      | Format and check digit only      |
| `us_ein`                | Format only                      |
| Other types (`au_abn`…) | Not checked; kept for your files |

A number with a typing error is refused straight away (`tax_id_invalid`), so you can correct it. A well-formed number gets the register's answer, which is stored with the ID: the **status**, who answered, when, and the register's **consultation number** where it gives one, which is your proof of the check.

| Status        | Meaning                                                                     | Effect on a sale       |
| ------------- | --------------------------------------------------------------------------- | ---------------------- |
| `valid`       | The register confirmed the number.                                          | Business-to-business   |
| `invalid`     | The register doesn't know the number.                                       | Taxed as to a consumer |
| `unavailable` | The register didn't answer (it's down or slow). Ownrecord asks again later. | Taxed as to a consumer |
| `format_only` | There's no register to ask; the format and check digit are right.           | Depends on the country |
| `unverified`  | Ownrecord can't check this type of number.                                  | Taxed as to a consumer |

Answers are reused for 24 hours for the same number. Before a renewal or a top-up, a check older than 30 days is repeated, and the earlier check moves into the tax ID's history. In development and test environments the register answers come from a fixture table (`ATU00000000` is valid, `DE000000000` invalid) and are marked as such.

## Location evidence

Where a digital sale is taxed depends on where the customer is. At checkout, renewal and top-up, Ownrecord gathers **evidence** of the customer's location:

- the country of the customer's IP address, with the address cut to its network (the first three parts of an IPv4 address, the first three groups of an IPv6 address): Ownrecord never stores a full IP address;
- the billing address the customer enters;
- the country of the customer's card, from the payment processor, captured before the payment is confirmed;
- optionally the bank country, phone country or the customer's own declaration.

Each kind of evidence counts once. The evidence and the location it points to are stored as an **evidence set**. The location is confirmed with the rules of the tax regime that applies: in the EU, two pieces of evidence must agree. When they disagree, the regime's conflict policy decides (by majority, by billing address, or held for review), and a brand may choose a stricter policy, never a looser one. When the card country arrives and changes the picture, checkout records a new evidence set and quotes the tax again; if the total changes, the customer confirms the new total before paying.

You can read a customer's evidence sets in the console and with [`customers.evidence_sets.list`](https://ownrecord.io/docs/reference/customers-evidence-sets-list.md).

## The locked tax country

The first successful payment **locks** the customer's tax country: the country that payment was taxed in. Prepaid credits are taxed when they're bought, in that country, and not again when they're used. The lock moves only when the evidence of a later top-up places the customer in another country; each top-up is taxed where its own evidence says.

## Deleting a customer

Deleting a customer is a soft delete. The customer stays readable, because its invoices, payments and evidence must be kept, but it can't be changed any more, and its email address can be used for a new customer. Deleting needs an owner or admin.

## Customers in the console and the API

Open a brand and choose **Customers** to search by email, open a customer's profile, tax IDs with their checks, location evidence and locked tax country, and to create customers or add tax IDs.

| Action                     | Operation                                                                                             | Needs                          |
| -------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------ |
| Create a customer          | [`customers.create`](https://ownrecord.io/docs/reference/customers-create.md)                         | `customers:write`              |
| List and search            | [`customers.list`](https://ownrecord.io/docs/reference/customers-list.md)                             | `customers:read`               |
| Read a customer            | [`customers.get`](https://ownrecord.io/docs/reference/customers-get.md)                               | `customers:read`               |
| Change the profile         | [`customers.update`](https://ownrecord.io/docs/reference/customers-update.md)                         | `customers:write`              |
| Add a tax ID               | [`customers.tax_ids.add`](https://ownrecord.io/docs/reference/customers-tax-ids-add.md)               | `customers:write`              |
| Remove a tax ID            | [`customers.tax_ids.delete`](https://ownrecord.io/docs/reference/customers-tax-ids-delete.md)         | `customers:write`              |
| Read the location evidence | [`customers.evidence_sets.list`](https://ownrecord.io/docs/reference/customers-evidence-sets-list.md) | `customers:read`               |
| Delete a customer          | [`customers.delete`](https://ownrecord.io/docs/reference/customers-delete.md)                         | `customers:admin`, with reason |

Every change sends a `customer.created` or `customer.updated` event to your webhook endpoints.