> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Merchant

> Update a merchant's information

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

<Note>
  You cannot update `reference_merchant_id` after a merchant is created.
</Note>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token authentication.
</ParamField>

<ParamField header="X-API-Version" type="string" required>
  Must be `2026-03-01`.
</ParamField>

## Path Parameters

<ParamField path="merchant_id" type="string" required>
  The merchant ID (`merch_xxx`) or your `reference_merchant_id`.
</ParamField>

## Request Body

<ParamField body="name" type="string">
  The merchant's business name.
</ParamField>

<ParamField body="email" type="string">
  The merchant's email address.
</ParamField>

<ParamField body="default_address" type="object">
  The merchant's default business address. If provided, all address fields are required.
</ParamField>

<ParamField body="tax_ids" type="array">
  Array of tax identification numbers. This will replace all existing tax IDs.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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": "new-email@example.com"
    }'
  ```

  ```bash cURL (update address) theme={null}
  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"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "id": "merch_1765503753979c37c5f24",
    "object": "tax.merchant",
    "reference_merchant_id": "my-seller-123",
    "name": "Updated Seller Name",
    "email": "new-email@example.com",
    "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
  }
  ```

  ```json 404 - Not Found theme={null}
  {
    "error": {
      "error_code": "merchant_not_found",
      "error_message": "Merchant not found or belongs to different testmode"
    }
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /tax/merchants/{merchant_id}
openapi: 3.0.1
info:
  title: Numeral API
  description: >-
    API for sales tax calculations - Version 2026-01-01. This version introduces
    Merchant management and Platform Calculations for marketplace and payment
    processor scenarios.
  license:
    name: MIT
  version: '2026-01-01'
servers:
  - url: https://api.numeralhq.com/
security:
  - bearerAuth: []
paths:
  /tax/merchants/{merchant_id}:
    post:
      summary: Update Merchant
      description: >-
        Update a merchant's information. Accepts same fields as create (except
        reference_merchant_id).
      operationId: updateMerchant_v20260101
      parameters:
        - name: X-API-Version
          in: header
          required: true
          schema:
            type: string
            enum:
              - '2026-01-01'
        - name: merchant_id
          in: path
          required: true
          schema:
            type: string
          description: The merchant ID (merch_xxx) or your reference_merchant_id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantUpdateRequest'
            examples:
              update_name:
                summary: Update merchant name
                value:
                  name: Updated Seller Name
                  email: new-email@example.com
              update_address:
                summary: Update address and tax IDs
                value:
                  default_address:
                    address_line_1: 456 New Street
                    address_city: Los Angeles
                    address_province: CA
                    address_postal_code: '90001'
                    address_country: US
                  tax_ids:
                    - type: us_ein
                      value: 12-3456789
        required: true
      responses:
        '200':
          description: Merchant updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantResponse'
        '404':
          description: Merchant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantNotFoundError'
components:
  schemas:
    MerchantUpdateRequest:
      type: object
      description: Request body for updating a merchant. All fields are optional.
      properties:
        name:
          type: string
          description: The merchant's business name
        email:
          type: string
          description: The merchant's email address
        default_address:
          $ref: '#/components/schemas/MerchantAddress'
        tax_ids:
          type: array
          items:
            $ref: '#/components/schemas/TaxId'
        metadata:
          $ref: '#/components/schemas/Metadata'
    MerchantResponse:
      type: object
      properties:
        id:
          type: string
          description: The internal merchant ID
          example: merch_1765503753979c37c5f24
        object:
          type: string
          example: tax.merchant
        reference_merchant_id:
          type: string
          description: Your external ID for this merchant
          example: my-seller-123
        name:
          type: string
          example: Acme Seller Co
        email:
          type: string
          example: seller@example.com
        default_address:
          $ref: '#/components/schemas/MerchantAddress'
        tax_ids:
          type: array
          items:
            $ref: '#/components/schemas/TaxId'
        status:
          type: string
          enum:
            - active
            - deleted
          example: active
        testmode:
          type: boolean
          description: Whether this merchant was created in test mode
        created_at:
          type: number
          description: Unix timestamp of creation
        updated_at:
          type: number
          description: Unix timestamp of last update
        metadata:
          $ref: '#/components/schemas/Metadata'
    MerchantNotFoundError:
      type: object
      properties:
        code:
          type: integer
          example: 404
        type:
          type: string
          example: MERCHANT_NOT_FOUND
        message:
          type: string
          example: Merchant not found or belongs to different testmode
    MerchantAddress:
      type: object
      description: >-
        Merchant's default business address. Uses address_ prefix for field
        names.
      properties:
        address_line_1:
          type: string
          example: 123 Main St
        address_line_2:
          type: string
          example: Suite 100
        address_city:
          type: string
          example: San Francisco
        address_province:
          type: string
          description: State/province code (2-letter ISO 3166-2)
          example: CA
        address_postal_code:
          type: string
          example: '94105'
        address_country:
          type: string
          description: Country code (2-letter ISO 3166-1)
          example: US
      required:
        - address_line_1
        - address_city
        - address_province
        - address_postal_code
        - address_country
    TaxId:
      type: object
      properties:
        type:
          type: string
          description: >-
            Stripe-style tax ID type. See [Tax IDs](/essentials/tax-ids) for the
            full list of supported types.
          example: us_ein
        value:
          type: string
          description: The tax ID value
          example: 12-3456789
      required:
        - type
        - value
    Metadata:
      type: object
      description: >-
        You can store arbitrary keys and values in the metadata. Any valid JSON
        object whose values are less than 255 characters long is accepted.
      properties:
        example_key:
          type: string
          description: >-
            Storing things like an order number may be useful for reporting and
            reconciliation.
          example: example_value
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````