Add a tax ID to your account

Adds a tax ID (for example an EU VAT number) to the signed-in customer's account after checking it with its register (VIES for EU VAT IDs, HMRC for UK VAT numbers, the Swiss UID register; others by format). The answer is stored with it: a number the register doesn't know is kept as invalid and doesn't make purchases business-to-business. A malformed number is refused (tax_id_invalid). At most 5 per customer.

Emits customer.updated. Customer portal only (portal:write).

At a glance

REST: POST /api/v1/portal/me/tax_ids
MCP tool: portal_tax_ids_add
Operation ID: portal.tax_ids.add
Scope: Brand
Permission: portal:write
Risk tier: write
Dry run: Not supported
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: A customer signed in to the customer portal (API keys can't call it)
Since: M9

Request

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
`object`	`"portal_account"`
`customerId`	`cus_…` ID
`livemode`	boolean
`email`	string
`name`	string or null
`businessName`	string or null
`type`	one of `individual`, `business`, `unknown`
`locale`	string or null
`billingAddress`	object or null
`taxIds`	array of object
`taxIds[].id`	string	The tax ID's identity on your account: its canonical number.
`taxIds[].type`	string
`taxIds[].value`	string
`taxIds[].country`	string
`taxIds[].status`	one of `valid`, `invalid`, `unavailable`, `format_only`, `unverified`	The register's answer: `valid`, `invalid`, `unavailable`, `format_only` or `unverified`.
`taxIds[].checkedAt`	date-time
`portalLastLoginAt`	date-time or null

Examples

Add an Austrian VAT ID

HTTP

POST /api/v1/portal/me/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

{
  "object": "portal_account",
  "customerId": "cus_01m4tx5nj8emwbyf7y9vcf48b1",
  "livemode": false,
  "email": "ana@example.com",
  "name": "Ana Novak",
  "businessName": "Alpen Apps GmbH",
  "type": "business",
  "locale": null,
  "billingAddress": {
    "line1": "Ring 1",
    "line2": null,
    "city": "Wien",
    "postalCode": "1010",
    "region": null,
    "country": "AT"
  },
  "taxIds": [
    {
      "id": "ATU00000000",
      "type": "eu_vat",
      "value": "ATU00000000",
      "country": "AT",
      "status": "valid",
      "checkedAt": "2026-10-20T09:00:00.000Z"
    }
  ],
  "portalLastLoginAt": "2026-10-20T09:00:00.000Z"
}

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	The number isn't valid for its type and country (format or checksum); `details.reason` says which. Nothing is stored.	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.
`customer_deleted`	400	Your account was deleted by the brand.	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	You already have this tax 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	You already have 5 tax IDs.	Remove a tax ID the customer no longer uses before adding another (at most 5 per customer).
`version_conflict`	409	Your details changed at the same moment; retry.	Fetch the object again and retry the change.
`livemode_not_allowed`	403	The portal session is in the other mode than the request.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.
`permission_denied`	403	The caller isn't a customer signed in to this brand's portal (operators and API keys use the customer operations).	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, scope_required, resource_not_found, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Add an Austrian VAT ID#

Errors#