Sign in

v1

latestOpenAPI 3.0.1MIT2026-07-26286592.7 KB

Create Merchant

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

post/tax/merchants

Headers

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

API version. Must be 2026-01-01 for merchant endpoints.

Request body

reference_merchant_idstring

Your external ID for this merchant. Must be unique per client+testmode.

namestring

The merchant's business name

emailstring

The merchant's email address

Example request

{
  "reference_merchant_id": "my-seller-123",
  "name": "Acme Seller Co",
  "email": "seller@example.com",
  "default_address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Suite 100",
    "address_city": "San Francisco",
    "address_province": "CA",
    "address_postal_code": "94105",
    "address_country": "US"
  },
  "tax_ids": [
    {
      "type": "us_ein",
      "value": "12-3456789"
    }
  ],
  "metadata": {
    "example_key": "example_value"
  }
}

Response

Merchant created successfully

idstring

The internal merchant ID

objectstring
reference_merchant_idstring

Your external ID for this merchant

namestring
emailstring
status'active' | 'deleted'
testmodeboolean

Whether this merchant was created in test mode

created_atnumber

Unix timestamp of creation

updated_atnumber

Unix timestamp of last update

Example response

{
  "id": "merch_1765503753979c37c5f24",
  "object": "tax.merchant",
  "reference_merchant_id": "my-seller-123",
  "name": "Acme Seller Co",
  "email": "seller@example.com",
  "default_address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Suite 100",
    "address_city": "San Francisco",
    "address_province": "CA",
    "address_postal_code": "94105",
    "address_country": "US"
  },
  "tax_ids": [
    {
      "type": "us_ein",
      "value": "12-3456789"
    }
  ],
  "status": "active",
  "metadata": {
    "example_key": "example_value"
  }
}