Merchant

Create Merchant

<span class="plan-badge plan-badge--pro">Available on Pro and Enterprise Plans</span> 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