Create Merchant

Available on Pro and Enterprise Plans

Creates a new merchant under the authenticated account. Requires X-API-KEY header. Set merchantType to choose the compliance model. “self-managed” creates a merchant that is active immediately with no TaxCloud invite; “taxcloud” (the default) starts the TaxCloud invite process and is an Enterprise plan feature.

Authentication

X-API-KEYstring

API Key authentication via header

Request

This endpoint expects an object.

merchantNamestringRequired1-255 characters

Legal or trading name of the merchant business. Required; must be 1–255 characters.

contactFirststringOptional

First name of the merchant's primary contact.

contactLaststringOptional

Last name of the merchant's primary contact.

contactEmailstringOptional

Email address of the merchant's primary contact; used for TaxCloud invitations and notifications.

sendTaxcloudInvitebooleanOptional

Sends invite to set up and connect a TaxCloud account to a merchant who does not already use TaxCloud. To connect a TaxCloud account for a merchant who already uses TaxCloud, use the "Set Merchant Credentials" function. Ignored when merchantType is 'self-managed'.

merchantTypeenumOptionalDefaults to taxcloud

The merchant's compliance model, chosen once at creation. 'taxcloud' (the default) starts the TaxCloud invite process, so TaxCloud can handle registration, filing, and remittance for the merchant; creating one requires an Enterprise plan. 'self-managed' skips the invite entirely and the merchant is active as soon as the call returns, with the merchant remaining responsible for their own compliance.

Allowed values:

referenceIdstringOptional<=255 characters

The ID you use in your own system to identify this merchant.

Response

Created

merchantIdstring

UUID assigned to the newly created merchant; use it in subsequent merchant operations.

messagestring

Human-readable description of the result.

statusstring

Result status of the operation (e.g. 'success').

Errors

400

Create Merchant Body Bad Request Error

401

Create Merchant Body Unauthorized Error

409

Create Merchant Body Conflict Error

422

Create Merchant Body Unprocessable Entity Error

500

Create Merchant Body Internal Server Error