Create Nexus Locations

<span class="plan-badge plan-badge--pro">Available on Pro and Enterprise Plans</span> Records one or more physical locations for a merchant. A merchant's physical locations are what establish its nexus, and nexus is what decides whether a sale is sourced at its origin or its destination, so this is the data a self-managed cart calculation depends on. Each address is geocoded as it is written, and the normalized result is what every response returns; expect the address you get back to differ from the one you sent. If any address in the request cannot be resolved to a US state the whole request is rejected with 422 and nothing is stored, so a retry cannot duplicate the locations that would otherwise have succeeded. Address resolution for the whole request is budgeted at 10 seconds. A batch that exceeds it returns 504 and stores nothing; send fewer locations per call if you hit this. Geocoding that had already completed is still billed, because the lookups were still performed. Available to self-managed merchants only. A TaxCloud-connected merchant's nexus is held in TaxCloud, so this returns 403 for them.

Authentication

X-API-KEYstring
API Key authentication via header

Request

This endpoint expects an object.
locationslist of objectsRequired

The locations to record. Up to 25 per call; each one is geocoded as it is written, which is what bounds the batch.

merchantIdstringRequired

UUID of the merchant these locations belong to. Must be owned by the calling account and must be self-managed.

nexusType"physical"Optional

The kind of nexus being recorded. Only ‘physical’ can be created: economic nexus is derived from a merchant’s sales activity rather than declared, so sending ‘economic’ is rejected rather than silently stored as physical.

Response

OK
merchantIdstring
UUID of the merchant the locations were recorded for.
locationslist of objectsOptional

The stored locations, in the order submitted, each with its server-issued locationId and normalized address.

Errors

400
Merchant Nexus Create Body Bad Request Error
401
Merchant Nexus Create Body Unauthorized Error
403
Merchant Nexus Create Body Forbidden Error
404
Merchant Nexus Create Body Not Found Error
422
Merchant Nexus Create Body Unprocessable Entity Error
429
Merchant Nexus Create Body Too Many Requests Error
500
Merchant Nexus Create Body Internal Server Error
503
Merchant Nexus Create Body Service Unavailable Error
504
Merchant Nexus Create Body Gateway Timeout Error