---
title: "Create Merchant"
method: POST
path: "/tax/merchants"
---

# Create Merchant

`POST /tax/merchants`

Creates a new merchant for platform/marketplace calculations. Merchants represent sellers on your platform.

## Headers

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

## Request body

- MerchantRequest — Request body for creating a merchant
  - `reference_merchant_id` string — Your external ID for this merchant. Must be unique per client+testmode.
  - `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[] — Tax identification numbers for this merchant
    - `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 created 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

- `400` — Validation error

---

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