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 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 instead.

Create a connected merchant

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

$
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": "Dana",
>
    "contactLast": "Whitfield",
>
    "contactEmail": "dana@acmeoutfitters.example",
>
    "referenceId": "acct-10042",
>
    "merchant_type": "taxcloud",
>
    "sendTaxcloudInvite": true
>
  }'

taxcloud is the API value for TaxCloud-connected merchants (note the snake_case field name, unlike the other camelCase fields). 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.

Connection lifecycle

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

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

The fourth status value, external_compliance, is what every self-managed merchant reports instead.

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 -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.

What a connection unlocks

Once a merchant is taxcloud_connected, the Merchant 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.

Converting a self-managed merchant

A self-managed merchant can be converted to the connected model by sending it a TaxCloud invite from the platform UI. The conversion is one-way: once invited, the merchant is no longer self-managed, and there is no path back. There is no documented API path for the conversion today. See self-managed merchants for the details.

Related