Update Merchant

Available on Pro and Enterprise Plans

Updates a merchant’s details, its compliance model, or both.

Send update to change the merchant’s name and contact details, setMerchantType to switch the merchant between the taxcloud and self-managed compliance models, or both together. At least one of the two is required.

Switching the compliance model sets the merchant’s status:

`setMerchantType`	Resulting `status`
`taxcloud`	`taxcloud_invited`, and a TaxCloud invite is emailed to the merchant
`self-managed`	`external_compliance`

Switching to self-managed disconnects the merchant from TaxCloud. Their stored TaxCloud credentials are removed, so the order, exemption certificate, and refund endpoints return 403 for them and cart calculation switches to Ziptax’s own rate engine. Reconnecting later means switching back to taxcloud and setting their credentials again with Set Merchant Credentials.

Sending the compliance model a merchant already has changes nothing and does not re-send the invite, so a request is safe to repeat.

You can only update merchants that belong to your account. Requests for any other merchant, or for one that has been deleted, return 403.

<span class="plan-badge plan-badge--pro">Available on Pro and Enterprise Plans</span> Updates a merchant's details, its compliance model, or both. Send `update` to change the merchant's name and contact details, `setMerchantType` to switch the merchant between the `taxcloud` and `self-managed` compliance models, or both together. At least one of the two is required. Switching the compliance model sets the merchant's `status`: | `setMerchantType` | Resulting `status` | | --- | --- | | `taxcloud` | `taxcloud_invited`, and a TaxCloud invite is emailed to the merchant | | `self-managed` | `external_compliance` | **Switching to `self-managed` disconnects the merchant from TaxCloud.** Their stored TaxCloud credentials are removed, so the order, exemption certificate, and refund endpoints return 403 for them and cart calculation switches to Ziptax's own rate engine. Reconnecting later means switching back to `taxcloud` and setting their credentials again with Set Merchant Credentials. Sending the compliance model a merchant already has changes nothing and does not re-send the invite, so a request is safe to repeat. You can only update merchants that belong to your account. Requests for any other merchant, or for one that has been deleted, return 403.

Authentication

X-API-KEYstring

API Key authentication via header

Request

This endpoint expects an object.

merchantIdstringRequired

UUID of the merchant to update. The merchant must be owned by the calling account.

sendTaxcloudInvitebooleanOptional

Whether to email the merchant a TaxCloud invite when this request switches them to ‘taxcloud’. Defaults to true. It has no effect on a request that does not change the compliance model, so repeating a request will not invite the merchant twice. The invite goes to the merchant’s stored contactEmail; include an ‘update’ block to change that address first. A merchant with no contact email cannot be invited.

Whether to email the merchant a TaxCloud invite when this request switches them to 'taxcloud'. Defaults to true. It has no effect on a request that does not change the compliance model, so repeating a request will not invite the merchant twice. The invite goes to the merchant's stored contactEmail; include an 'update' block to change that address first. A merchant with no contact email cannot be invited.

setMerchantTypeenumOptional

Switches the merchant to a different compliance model. Use ‘taxcloud’ to have TaxCloud handle the merchant’s registration, filing, and remittance: their status becomes ‘taxcloud_invited’ and they are emailed an invite. Use ‘self-managed’ to hand compliance back to the merchant: their status becomes ‘external_compliance’ and their stored TaxCloud credentials are removed. ‘connected’ and ‘offline’ are deprecated names for ‘taxcloud’ and ‘self-managed’. Sending the merchant’s current model changes nothing. Omit this field to leave the compliance model as it is.

Switches the merchant to a different compliance model. Use 'taxcloud' to have TaxCloud handle the merchant's registration, filing, and remittance: their status becomes 'taxcloud_invited' and they are emailed an invite. Use 'self-managed' to hand compliance back to the merchant: their status becomes 'external_compliance' and their stored TaxCloud credentials are removed. 'connected' and 'offline' are deprecated names for 'taxcloud' and 'self-managed'. Sending the merchant's current model changes nothing. Omit this field to leave the compliance model as it is.

Allowed values:

updateobjectOptional

New values for the merchant's name and contact details. Every field in this block is replaced, so send the current value for anything you do not want to clear. Omit the block to change only the compliance model.

Response

merchantIdstring

UUID of the updated merchant.

messagestring

Human-readable description of the result.

statusstring

Result status of the operation (e.g. ‘success’).

Errors

400

Update Merchant Body Bad Request Error

401

Update Merchant Body Unauthorized Error

403

Update Merchant Body Forbidden Error

404

Update Merchant Body Not Found Error

409

Update Merchant Body Conflict Error

422

Update Merchant Body Unprocessable Entity Error

500

Update Merchant Body Internal Server Error

Available on Pro and Enterprise Plans

Updates a merchant’s details, its compliance model, or both.

Switching the compliance model sets the merchant’s status:

`setMerchantType`	Resulting `status`
`taxcloud`	`taxcloud_invited`, and a TaxCloud invite is emailed to the merchant
`self-managed`	`external_compliance`

Sending the compliance model a merchant already has changes nothing and does not re-send the invite, so a request is safe to repeat.

You can only update merchants that belong to your account. Requests for any other merchant, or for one that has been deleted, return 403.

$	curl -X POST https://api.zip-tax.com/merchant/update \
>	-H "X-API-KEY: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"merchantId": "2c0534ea-eb8a-4732-9cdb-2476f244029d",
>	"update": {
>	"merchantName": "Blue Ridge Outfitters",
>	"contactEmail": "dana@blueridgeoutfitters.example",
>	"contactFirst": "Dana",
>	"contactLast": "Reyes",
>	"referenceId": "seller-4417"
>	}
>	}'

1	{
2	"merchantId": "2c0534ea-eb8a-4732-9cdb-2476f244029d",
3	"message": "merchant updated successfully",
4	"status": "success"
5	}