Add a tax ID to a customer · Ownrecord docs

Adds a tax ID to a customer after checking it with its register (VIES for EU VAT IDs, HMRC for UK VAT numbers, the Swiss UID register; Norwegian and US numbers by format; other types are kept unverified). The answer is stored with the ID: status, source, reason, consultation number and time (spec §9.4). A malformed number is refused (tax_id_invalid); one the register doesn't know is stored as invalid and doesn't make the customer a business. Dry runs simulate the check.

At most 5 tax IDs per customer; the same number twice is refused (customer_tax_id_exists). The type is inferred again (spec §13.1). Emits customer.updated.

At a glance

REST: POST /api/v1/customers/{id}/tax_ids
MCP tool: customers_tax_ids_add
Operation ID: customers.tax_ids.add
Scope: Brand
Permission: customers:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the customers:write scope
Since: M4

Request

Path parameters

Field	Type	Description
`id`	`cus_…` ID	The customer's ID (`cus_…`).

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`type`	string	Yes	The tax ID's type: `eu_vat`, `gb_vat`, `ch_uid`/`ch_vat`, `no_org`/`no_vat` or `us_ein`. Other types are kept but can't be checked (`unverified`).
`value`	string	Yes	The number as the customer gave it, with or without the country prefix and separators.
`country`	string	Yes	The country that issued the tax ID (ISO 3166-1 alpha-2; `EL` = Greece).

Response

201 Created with a JSON object:

Field	Type	Description
`id`	`cus_…` ID
`object`	`"customer"`
`livemode`	boolean
`entityId`	`ent_…` ID
`brandId`	`brd_…` ID
`email`	string
`name`	string or null
`businessName`	string or null
`locale`	string or null
`type`	one of `individual`, `business`, `unknown`	Inferred (spec §13.1): `business` with a tax ID that isn't rejected, or with a business name when declared a business. Tax is decided per sale: only a `valid` tax ID makes a sale business-to-business.
`declaredType`	one of `individual`, `business`, `unknown`	What you declared.
`billingAddress`	object or null
`taxIds`	array of object
`taxIds[].id`	string	Identifies the tax ID on the customer: its canonical number, e.g. `ATU12345678`.
`taxIds[].type`	string	`eu_vat`, `gb_vat`, `ch_uid`/`ch_vat`, `no_org`/`no_vat`, `us_ein`, or another type (unverified).
`taxIds[].value`	string	The number as given.
`taxIds[].country`	string
`taxIds[].number`	string or null	The canonical number (null for types Ownrecord can't check).
`taxIds[].verification`	object	The latest check (spec §9.4).
`taxIds[].verification.status`	one of `valid`, `invalid`, `unavailable`, `format_only`, `unverified`	`valid`, `invalid`, `unavailable` (the register couldn't answer), `format_only` (no register: format and checksum) or `unverified` (a type Ownrecord can't check).
`taxIds[].verification.source`	string	Who decided: VIES, HMRC, CH_UID, FORMAT (format and checksum only) or NONE.
`taxIds[].verification.reason`	string or null	Why, e.g. `not_registered` or `service_unavailable`.
`taxIds[].verification.checkedAt`	date-time
`taxIds[].verification.consultationNumber`	string or null	The register's proof of the check (VIES request identifier, HMRC consultation number).
`taxIds[].verification.simulated`	boolean	A fixture answer (development and test environments), not a register's.
`taxIds[].history`	array of object	Earlier checks, newest first (at most 10).
`taxIds[].history[].status`	one of `valid`, `invalid`, `unavailable`, `format_only`, `unverified`	`valid`, `invalid`, `unavailable` (the register couldn't answer), `format_only` (no register: format and checksum) or `unverified` (a type Ownrecord can't check).
`taxIds[].history[].source`	string	Who decided: VIES, HMRC, CH_UID, FORMAT (format and checksum only) or NONE.
`taxIds[].history[].reason`	string or null	Why, e.g. `not_registered` or `service_unavailable`.
`taxIds[].history[].checkedAt`	date-time
`taxIds[].history[].consultationNumber`	string or null	The register's proof of the check (VIES request identifier, HMRC consultation number).
`taxIds[].history[].simulated`	boolean	A fixture answer (development and test environments), not a register's.
`taxIds[].addedAt`	date-time
`taxCountryLocked`	object or null	Where the customer's purchases are taxed (spec §9.3): set at the first successful payment, moved only when a top-up's evidence resolves to another country.
`taxExempt`	object or null	Tax exemption (spec §9.5). Not applied yet: exemption certificates come in a later release.
`processorRefs`	array of object	The customer at each payment processor used (set by checkout).
`processorRefs[].processorConnectionId`	`pcon_…` ID
`processorRefs[].customerRef`	string
`risk`	object
`risk.level`	one of `normal`, `elevated`, `blocked`
`risk.reasons`	array of string
`risk.firstPaymentAt`	date-time or null
`risk.totalPaid`	money
`portalLastLoginAt`	date-time or null
`testClockId`	`clk_…` ID or null	Test mode: the test clock the customer was created on (spec §16.13).
`metadata`	object
`createdAt`	date-time
`updatedAt`	date-time
`deletedAt`	date-time or null	When the customer was deleted (soft delete); null while active.

Examples

Add an Austrian VAT ID

HTTP

POST /api/v1/customers/cus_01m4ty3c2b5qx7mhd9k8w6s0aa/tax_ids
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "type": "eu_vat",
  "value": "ATU 0000 0000",
  "country": "AT"
}

Response (201):

JSON

{
  "id": "cus_01m4ty3c2b5qx7mhd9k8w6s0aa",
  "object": "customer",
  "livemode": false,
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "email": "billing@alpenapps.example",
  "name": "Lena Huber",
  "businessName": "Alpen Apps GmbH",
  "locale": "de-AT",
  "type": "business",
  "declaredType": "business",
  "billingAddress": {
    "line1": "Mariahilfer Straße 1",
    "line2": null,
    "city": "Wien",
    "postalCode": "1060",
    "region": null,
    "country": "AT"
  },
  "taxIds": [
    {
      "id": "ATU00000000",
      "type": "eu_vat",
      "value": "ATU 0000 0000",
      "country": "AT",
      "number": "ATU00000000",
      "verification": {
        "status": "valid",
        "source": "VIES",
        "reason": null,
        "checkedAt": "2026-10-14T09:00:00.000Z",
        "consultationNumber": "WAPIAAAAZ1x2y3",
        "simulated": false
      },
      "history": [],
      "addedAt": "2026-10-14T09:00:00.000Z"
    }
  ],
  "taxCountryLocked": null,
  "taxExempt": null,
  "processorRefs": [],
  "risk": {
    "level": "normal",
    "reasons": [],
    "firstPaymentAt": null,
    "totalPaid": {
      "amount": "0",
      "currency": "EUR"
    }
  },
  "portalLastLoginAt": null,
  "testClockId": null,
  "metadata": {
    "userId": "u_4821"
  },
  "createdAt": "2026-10-14T09:00:00.000Z",
  "updatedAt": "2026-10-14T09:00:00.000Z",
  "deletedAt": null
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	A field is missing or malformed.	Fix the fields listed in `details.issues` and send the request again.
`tax_id_invalid`	400	A tax ID's number isn't valid for its type and country (format, checksum, another country's prefix, a Northern Ireland XI number); `details.reason` says which. Nothing is stored. Types Ownrecord can't check (e.g. `au_abn`) are stored as `unverified` instead.	Check the number and its country for typing errors (`details.reason` says what is wrong), then send it again. A Northern Ireland business enters its GB VAT number.
`resource_not_found`	404	This brand has no such customer in this mode (customers belong to one brand and one mode).	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`customer_deleted`	400	The customer was deleted.	Create a new customer for this buyer. Deleted customers stay readable for the records they belong to, but can't be changed.
`customer_tax_id_exists`	409	The customer already has this tax ID (`details.tax_id_id`).	Nothing to do: the tax ID is already on the customer (`details.tax_id_id`). To check it again, remove it and add it back.
`customer_tax_id_limit`	400	The customer already has 5 tax IDs.	Remove a tax ID the customer no longer uses before adding another (at most 5 per customer).
`version_conflict`	409	The customer changed at the same moment; retry.	Fetch the object again and retry the change.
`scope_required`	400	The request names no brand (an org or entity key without `Ownrecord-Brand`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`livemode_not_allowed`	403	You have no live-mode access, so you can't act on live customers.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.
`permission_denied`	403	You can't change this brand's customers (`customers:write`: owners, admins and support).	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Add an Austrian VAT ID#

Errors#