Update Merchant

Update a merchant’s information

POST /tax/merchants/{merchant_id}

cURL

curl -X POST https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Seller Name",
    "email": "[e-mail]"
  }'

curl -X POST https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "default_address": {
      "address_line_1": "456 New Street",
      "address_city": "Los Angeles",
      "address_province": "CA",
      "address_postal_code": "90001",
      "address_country": "US"
    }
  }'

200 - Success

{
  "id": "merch_1765503753979c37c5f24",
  "object": "tax.merchant",
  "reference_merchant_id": "my-seller-123",
  "name": "Updated Seller Name",
  "email": "[e-mail]",
  "default_address": {
    "address_line_1": "123 Main St",
    "address_city": "San Francisco",
    "address_province": "CA",
    "address_postal_code": "94105",
    "address_country": "US"
  },
  "tax_ids": [],
  "status": "active",
  "testmode": true,
  "created_at": 1735689600,
  "updated_at": 1735690000
}

{
  "error": {
    "error_code": "merchant_not_found",
    "error_message": "Merchant not found or belongs to different testmode"
  }
}

Update a merchant’s information. All fields are optional - only include the fields you want to update.

You cannot update reference_merchant_id after a merchant is created.

Headers

Authorization · string · required

Bearer token authentication.

X-API-Version · string · required

Must be 2026-03-01.

Path Parameters

merchant_id · string · required

The merchant ID (merch_xxx) or your reference_merchant_id.

Request Body

name · string

The merchant’s business name.

email · string

The merchant’s email address.

default_address · object

The merchant’s default business address. If provided, all address fields are required.

tax_ids · array

Array of tax identification numbers. This will replace all existing tax IDs.

metadata · object

Arbitrary key-value pairs.

cURL

curl -X POST https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Seller Name",
    "email": "[e-mail]"
  }'

curl -X POST https://api.numeralhq.com/tax/merchants/my-seller-123 \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "default_address": {
      "address_line_1": "456 New Street",
      "address_city": "Los Angeles",
      "address_province": "CA",
      "address_postal_code": "90001",
      "address_country": "US"
    }
  }'

200 - Success

{
  "id": "merch_1765503753979c37c5f24",
  "object": "tax.merchant",
  "reference_merchant_id": "my-seller-123",
  "name": "Updated Seller Name",
  "email": "[e-mail]",
  "default_address": {
    "address_line_1": "123 Main St",
    "address_city": "San Francisco",
    "address_province": "CA",
    "address_postal_code": "94105",
    "address_country": "US"
  },
  "tax_ids": [],
  "status": "active",
  "testmode": true,
  "created_at": 1735689600,
  "updated_at": 1735690000
}

{
  "error": {
    "error_code": "merchant_not_found",
    "error_message": "Merchant not found or belongs to different testmode"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-API-Version · enum<string> · required

Available options: 2026-01-01

Path Parameters

merchant_id · string · required

The merchant ID (merch_xxx) or your reference_merchant_id

Body

application/json

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 · object

Merchant's default business address. Uses address_ prefix for field names.

Show child attributes

tax_ids · object[]

Show child attributes

metadata · object

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).

Show child attributes

Response

200

application/json

Merchant updated successfully

id · string

The internal merchant ID

Example:

"merch_1765503753979c37c5f24"

object · string

Example:

"tax.merchant"

reference_merchant_id · string

Your external ID for this merchant

Example:

"my-seller-123"

name · string

Example:

"Acme Seller Co"

email · string

Example:

"[e-mail]"

default_address · object

Merchant's default business address. Uses address_ prefix for field names.

Show child attributes

tax_ids · object[]

Show child attributes

status · enum<string>

Available options: active, deleted

Example:

"active"

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 · object

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).

Show child attributes