> This page is for version v6.0 (default).
> For other versions, use one of these documentation indexes:
> - v6.0 (default): https://docs.zip.tax/v-6-0/llms.txt
> - v5.0: https://docs.zip.tax/v-5-0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.zip.tax/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.zip.tax/_mcp/server.

# TaxCloud-Connected Merchants

A TaxCloud-connected merchant gets its own TaxCloud account, connected to your
platform. TaxCloud handles compliance end to end — registration, filing, and
remittance — in the merchant's own account, synced to your platform. Your
platform creates the merchant, TaxCloud invites them, and once the connection
is live your platform drives day-to-day tax operations through the
[Merchant Transactions](transactions) endpoints.

TaxCloud-connected merchants require the **Enterprise** plan. If a merchant
handles its own compliance and you only need to track its nexus footprint,
create a [self-managed merchant](self-managed-merchants) instead.

## Create a connected merchant

`taxcloud` is the default `merchantType`, so any merchant created without the
field is TaxCloud-connected. Set it explicitly so the intent is clear in your
integration:

#### cURL

```bash
curl -X POST "https://api.zip-tax.com/merchant/create" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantName": "Acme Outfitters",
    "contactFirst": "Daniel",
    "contactLast": "Smith",
    "contactEmail": "daniel@acmeoutfitters.example",
    "referenceId": "acct-10042",
    "merchantType": "taxcloud",
    "sendTaxcloudInvite": true
  }'
```

`taxcloud` is the API value for TaxCloud-connected merchants. A successful
request returns `201 Created` with the new merchant's `merchantId`, a UUID
you use in every later call for this merchant.

Two fields control the invite:

* **`contactEmail`** — the TaxCloud invite email goes to `contactEmail`.
  The field is optional in the schema, but include it when creating a
  connected merchant: without it there is nowhere to deliver the invite.
* **`sendTaxcloudInvite`** — defaults to `true`, which sends the invite as
  part of creation. Set it to `false` to create the merchant without emailing
  them yet. If the merchant already uses TaxCloud, skip the invite and store
  their existing credentials directly with
  [`/merchant/credentials/set`](#store-taxcloud-credentials).

> **Warning**
>
> Set your account's **Company Name** (General settings in the platform) before
> creating merchants. It appears in the TaxCloud invite, and creation fails
> with `400` and the message "Please add a Company Name in the General settings
> page before creating a merchant." until it is set.

## Connection lifecycle

#### Invite sent

Creating the merchant emails a TaxCloud invite to `contactEmail` (unless
`sendTaxcloudInvite` is `false`). The merchant reports
`status: "taxcloud_invited"`.

#### Merchant sets up TaxCloud

The merchant follows the invite, sets up their own TaxCloud account, and
connects it to your platform.

#### Credentials on file

Once the merchant's TaxCloud credentials are stored, the merchant reports
`status: "taxcloud_connected"` and the
[Merchant Transactions](transactions) endpoints become available for it.

If the credentials are later removed, the merchant moves to
`taxcloud_disconnected`.

Reads (`POST /merchant/get`, `GET /merchant/list`) do not return
`merchantType`; the compliance model is visible through `status`. A
TaxCloud-connected merchant reports one of three values:

| `status`                | Meaning                                    |
| ----------------------- | ------------------------------------------ |
| `taxcloud_invited`      | TaxCloud invite sent, not yet accepted.    |
| `taxcloud_connected`    | TaxCloud credentials set and active.       |
| `taxcloud_disconnected` | Previously connected; credentials removed. |

The fourth status value, `external_compliance`, is what every
[self-managed merchant](self-managed-merchants) reports instead.

> **Info**
>
> For merchants sitting in `taxcloud_invited`, you can send the merchant a
> reminder email from the platform UI. There is no dedicated API endpoint for
> invites or reminders — the invite fires when a connected merchant is created,
> or when a self-managed merchant is converted from the platform UI.

## Store TaxCloud credentials

When a merchant already has a TaxCloud account, or you receive their
credentials out of band, store the merchant's TaxCloud API key and connection
ID with `POST /merchant/credentials/set`:

#### cURL

```bash
curl -X POST "https://api.zip-tax.com/merchant/credentials/set" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "6b3c1f5e-2a8d-4c9b-9f2e-1d7a4b6c8e10",
    "apiKey": "MERCHANT_TAXCLOUD_API_KEY",
    "connectionId": "MERCHANT_TAXCLOUD_CONNECTION_ID"
  }'
```

All three fields are required. `apiKey` and `connectionId` are the
**merchant's TaxCloud credentials** — not your Ziptax API key — and together
they identify the merchant's TaxCloud integration. Credentials are encrypted
at rest with AES-256-GCM.

To disconnect a merchant, call `POST /merchant/credentials/delete` with only
the `merchantId`. The merchant moves to `taxcloud_disconnected`, and its
transaction endpoints stop working until credentials are set again.

> **Warning**
>
> `POST /merchant/credentials/get` is deprecated and removed from the v6.0 API
> reference. Do not build new integrations on it — stored credentials are
> resolved server-side, so your platform never needs to read them back.

## What a connection unlocks

Once a merchant is `taxcloud_connected`, the
[Merchant Transactions](transactions) endpoints operate on that merchant's
TaxCloud account using its stored credentials:

* **Cart tax calculation** — calculate tax on a cart before recording an order.
* **Orders** — create orders (from a cart or directly), retrieve, and update them.
* **Exemption certificates** — store, retrieve, list, and delete customer certificates.
* **Refunds** — refund all or part of a recorded order.

Every call targets a single merchant by `merchantId`. Ziptax resolves the
merchant's TaxCloud credentials server-side, so your integration only ever
handles your own Ziptax API key. A merchant without credentials on file
returns `404` (`credentials not found`) on every transaction call.

## Switching a merchant between models

A self-managed merchant is converted to the connected model by sending it a
TaxCloud invite, either from the platform UI or by sending
`setMerchantType: "taxcloud"` to
[`POST /merchant/update`](/api-reference/merchant/update-merchant). See
[self-managed merchants](self-managed-merchants) for the request and what the
merchant sees.

The reverse works the same way: `setMerchantType: "self-managed"` hands
compliance back to the merchant and its `status` becomes `external_compliance`.
Going this direction **deletes the TaxCloud credentials stored for the
merchant**, so the transaction endpoints below stop working immediately and
reconnecting later means setting credentials again with
[Set Merchant Credentials](/api-reference/merchant/set-merchant-credentials).
Sending a merchant the model it already has changes nothing and deletes
nothing.

## Related

#### [Merchant Management](merchant-management)

Create, read, update, and delete merchants across both compliance models.

#### [Merchant Transactions](transactions)

Cart tax, orders, exemption certificates, and refunds for connected merchants.

#### [Self-Managed Merchants](self-managed-merchants)

Merchants that handle their own compliance while you track their nexus.

#### [Create Merchant API](/api-reference/merchant/create-merchant)

Full request and response schema for POST /merchant/create.