Move every address assigned to one vendor over to another vendor in a single call.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Overview
Move every address currently assigned to one vendor over to another vendor on the same site, in a single call. Only the vendor assignment changes; all other address data is left untouched.
Example: a delivery route changes hands. Instead of editing each address one at a time, reassign every address held by the outgoing vendor to the incoming vendor in one request.
Preview before moving anything
Set preview to true to find out how many addresses a reassignment would affect without writing anything.
A preview returns matched_addresses together with up to five sample_address_ids, so the scope can be confirmed before the real run. On a preview, reassigned_addresses is always 0 and operation_id is null.
Run the same request again with preview omitted or set to false to perform the reassignment.
Narrowing the scope
By default every address the source vendor holds on the site is moved. The optional fields below narrow that set. They combine — an address must satisfy all of the filters supplied to be included.
| Field | Effect |
|---|---|
address_ids | Restrict the run to specific addresses. Up to 1,000 identifiers per request. |
type | Only addresses of this type: shipping, billing or account_primary. |
city | Only addresses in this city. |
state | Only addresses in this state, province or region. |
country | Only addresses in this country, as an ISO3166 alpha-2 code. |
postal_code | Only addresses with this ZIP or postal code. |
Outcomes
| Situation | Result |
|---|---|
| The reassignment would affect more than 50,000 addresses | 422, and nothing is written. Narrow the scope and try again. |
| No addresses match | 200, with matched_addresses of 0 and a null operation_id. |
| The source or destination vendor is not on your account | 400 |
| The destination vendor is the same as the source vendor | 400 |
What is not affected
- Only the vendor assignment is updated. Every other address attribute keeps its current value.
- Reassignment does not fire address update events, so no
address.updatedwebhook is sent and no payment processor or tax recalculation is triggered. - Addresses belonging to deleted customers are never included.
Auditing a run
A reassignment that moves at least one address returns an operation_id. Every address moved by that run is recorded against it, so a single reassignment can be reviewed as one operation after the fact.