Update your billing details

Changes the signed-in customer's name, business name or billing address, as invoices show them. Send only the fields to change; null removes an optional one, and billingAddress is replaced as a whole. The new address is used for the next purchases and invoices; past sales stay taxed where they were.

Emits customer.updated to the brand's webhooks. Customer portal only (portal:write).

At a glance

REST: PATCH /api/v1/portal/me/tax_details
MCP tool: portal_tax_details_update
Operation ID: portal.tax_details.update
Scope: Brand
Permission: portal:write
Risk tier: write
Dry run: Not supported
Idempotency: Idempotency-Key optional
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
`name`	string or null	No	Your name; null removes it.
`businessName`	string or null	No	Your business's legal name, for invoices; null removes it.
`billingAddress`	object or null	No	Replaces the billing address; null removes it.

Response

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

Set the billing address

HTTP

PATCH /api/v1/portal/me/tax_details
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "billingAddress": {
    "line1": "Ring 1",
    "city": "Wien",
    "postalCode": "1010",
    "country": "AT"
  }
}

Response (200):

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	Nothing to change, a field is malformed, or a business would be left without a business name or a tax ID.	Fix the fields listed in `details.issues` and send the request again.
`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.
`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_reused, idempotency_in_progress, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Set the billing address#

Errors#