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

# Update Merchant

`POST /tax/merchants/{merchant_id}`

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-01-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

---

[API](https://skmtc.net/numeral-com/apis/numeral-api.md) · [All operations](https://skmtc.net/numeral-com/apis/numeral-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/numeral-com/numeral-api/revisions/f0af51c3f9b9/schema)