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

# Delete Merchant

> Soft delete a merchant

Soft delete a merchant. The merchant will no longer appear in GET or LIST operations but the data is preserved internally.

<Warning>
  Deleted merchants cannot be used in new platform calculations. Attempting to use a deleted merchant's ID will return a `merchant_not_found` error.
</Warning>

## Headers

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

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

## Path Parameters

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

## Response

<ResponseField name="id" type="string">
  The merchant ID.
</ResponseField>

<ResponseField name="object" type="string">
  Always `tax.merchant`.
</ResponseField>

<ResponseField name="deleted" type="boolean">
  Always `true` for successful deletion.
</ResponseField>

<ResponseField name="deleted_at" type="number">
  Unix timestamp of deletion.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE https://api.numeralhq.com/tax/merchants/my-seller-123 \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "X-API-Version: 2026-01-01"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "id": "merch_1765503753979c37c5f24",
    "object": "tax.merchant",
    "deleted": true,
    "deleted_at": 1735690500
  }
  ```

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

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


## OpenAPI

````yaml DELETE /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}:
    delete:
      summary: Delete Merchant
      description: >-
        Soft delete a merchant. The merchant will no longer appear in GET/LIST
        operations.
      operationId: deleteMerchant_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
      responses:
        '200':
          description: Merchant deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantDeleteResponse'
        '404':
          description: Merchant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantNotFoundError'
components:
  schemas:
    MerchantDeleteResponse:
      type: object
      properties:
        id:
          type: string
          example: merch_1765503753979c37c5f24
        object:
          type: string
          example: tax.merchant
        deleted:
          type: boolean
          example: true
        deleted_at:
          type: number
          description: Unix timestamp of deletion
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````