Remove a tax ID from a customer

Removes a tax ID from a customer. taxIdId is the tax ID's id on the customer: its canonical number, e.g. ATU12345678. Past sales keep the check they were quoted with; future sales no longer use the ID. The type is inferred again (spec §13.1): without a tax ID, a customer is a business only when declared one with a business name. Emits customer.updated.

At a glance

REST: DELETE /api/v1/customers/{id}/tax_ids/{taxIdId}
MCP tool: customers_tax_ids_delete
Operation ID: customers.tax_ids.delete
Scope: Brand
Permission: customers:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key optional
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_…`).
`taxIdId`	string	The tax ID's `id` on the customer: its canonical number, e.g. `ATU12345678`.

Body

This operation takes no body.

Response

200 OK 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

Remove the Austrian VAT ID

The customer keeps its business name, so it stays a business.

HTTP

DELETE /api/v1/customers/cus_01m4ty3c2b5qx7mhd9k8w6s0aa/tax_ids/ATU00000000
Authorization: Bearer or_test_…

Response (200):

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": [],
  "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:30:00.000Z",
  "deletedAt": null
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`id` or `taxIdId` is malformed.	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	This brand has no such customer in this mode, or the customer has no tax ID with this `taxIdId`.	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.
`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_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#

Remove the Austrian VAT ID#

Errors#