---
title: "Update Merchant"
method: POST
path: "/tax/merchants/{merchant_id}"
---

# Update Merchant

`POST /tax/merchants/{merchant_id}`

## Request

- Base URL: `https://api.numeralhq.com`
- URL: `https://api.numeralhq.com/tax/merchants/{merchant_id}`
- Auth: HTTP bearer

Update a merchant's information. Accepts same fields as create (except reference_merchant_id).

## Path parameters

- `merchant_id` string, required

## Headers

- `X-API-Version` '2026-03-01', required

## Request body

- MerchantUpdateRequest: Request body for updating a merchant. All fields are optional.
  - `name` string: The merchant's business name
  - `email` string: The merchant's email address
  - `default_address` MerchantAddress: Merchant's default business address. Uses address_ prefix for field names.
    - `address_line_1` string, required
    - `address_line_2` string
    - `address_city` string, required
    - `address_province` string, required: State/province code (2-letter ISO 3166-2)
    - `address_postal_code` string, required
    - `address_country` string, required: Country code (2-letter ISO 3166-1)
  - `tax_ids` TaxId[]
    - `type` string, required: Country-specific Stripe-style tax ID type (e.g., `us_ein`, `eu_vat`, `gb_vat`, `au_abn`, `ca_gst_hst`). See [Tax IDs](/essentials/tax-ids) for the full list of supported types.
    - `value` string, required: The tax ID value (1-100 characters).
  - `metadata` Metadata: You can store arbitrary keys and values in the metadata. At most 50 keys; each key at most 255 characters; each value must be a string of at most 255 characters (non-string values are rejected).
    - `example_key` string: Storing things like an order number may be useful for reporting and reconciliation.

## Response `200`

Merchant updated successfully

- MerchantResponse
  - `id` string: The internal merchant ID
  - `object` string
  - `reference_merchant_id` string: Your external ID for this merchant
  - `name` string
  - `email` string
  - `default_address` MerchantAddress: Merchant's default business address. Uses address_ prefix for field names.
    - `address_line_1` string, required
    - `address_line_2` string
    - `address_city` string, required
    - `address_province` string, required: State/province code (2-letter ISO 3166-2)
    - `address_postal_code` string, required
    - `address_country` string, required: Country code (2-letter ISO 3166-1)
  - `tax_ids` TaxId[]
    - `type` string, required: Country-specific Stripe-style tax ID type (e.g., `us_ein`, `eu_vat`, `gb_vat`, `au_abn`, `ca_gst_hst`). See [Tax IDs](/essentials/tax-ids) for the full list of supported types.
    - `value` string, required: The tax ID value (1-100 characters).
  - `status` 'active' | 'deleted'
  - `testmode` boolean: Whether this merchant was created in test mode
  - `created_at` number: Unix timestamp of creation
  - `updated_at` number: Unix timestamp of last update
  - `metadata` Metadata: You can store arbitrary keys and values in the metadata. At most 50 keys; each key at most 255 characters; each value must be a string of at most 255 characters (non-string values are rejected).
    - `example_key` string: Storing things like an order number may be useful for reporting and reconciliation.

## Other responses

- `404`: Merchant not found

## Changes

- **2026-11-03** `f4650eaed11f`: 1 breaking, 2 info
  - removed the enum value `2026-01-01` from the `header` request parameter `X-API-Version`
  - api operation id `updateMerchant_v20260101` removed and replaced with `updateMerchant_v20260301`
  - added the new enum value `2026-03-01` to the `header` request parameter `X-API-Version`

[Operation history](https://skmtc.dev/numeral-com/apis/numeral-api/changes/tax/merchants/:merchant_id/post.md)

---

[API](https://skmtc.dev/numeral-com/apis/numeral-api.md) - [All operations](https://skmtc.dev/numeral-com/apis/numeral-api/llms.txt) - [OpenAPI document](https://skmtc.dev/numeral-com/apis/numeral-api/revisions/f4650eaed11f?raw)