Company Locations¶
The Company Locations push creates and updates the locations of B2B companies: the branches or sites that order, each with its own addresses, tax settings and payment terms.
On a push connector, select Company Locations as the Shopify Import Type. The push needs a store with B2B. See Building a B2B Customer for where it fits.
Creating and Updating¶
Company Id is required on every record. Location Id and External ID then decide what the record does:
| Location Id | External ID | Result |
|---|---|---|
| Set | Any | Updates that location. The location must belong to the company. External ID is then just a field to update |
| Blank | Set | Updates the company's location with that External ID, matching exactly. With no match, creates the location |
| Blank | Blank | Creates the location |
IMan writes the location's gid back into Location Id after a create or an External ID match. Under Insert, a record that finds an existing location fails. Under Update, a record that would create one fails.
A company with two locations that share an External ID fails the record. Set the Location Id to choose one.
IMan leaves a blank field out of the request, and the location keeps its value.
Fields¶
| Field | Rule |
|---|---|
| Company Id | Required. The company the location belongs to, as a numeric id or a gid |
| Location Id | Updates this location. Blank matches on External ID, else creates. Written back |
| External ID | The location's id in your system. Finds the location when Location Id is blank |
| Location Admin Role Id | Written back after each create or update: the company's Location admin contact role, for Company - Contact Assign Roles. Blank when the company has no such role |
| Location Name, Location Locale, Location Note, Location Phone | The location's details |
| Location Payment Terms Id | The location's payment terms template, as a numeric id or a gid |
| Location Checkout To Draft | True makes the location's checkouts into draft orders for review |
| Location Editable Shipping Address | True lets the location's buyers change the shipping address at checkout |
| Location Tax Registration Id | The location's tax registration number |
| Location Tax Exempt | True exempts the location from tax |
| Location Tax Exemptions | Shopify tax exemption values separated by commas, such as CA_STATUS_CARD_EXEMPTION. On an update this becomes the location's full list |
| Shipping and Billing fields | The addresses, including Shipping State Code and Billing State Code. An address replaces the location's address whole. Map every part of it |
| Billing Same As Shipping | True uses the shipping address for billing too, and ignores the billing fields |
| Use Bulk Operations | True sends the run through bulk operations |
Errors¶
An update sends the details, the addresses and the tax settings as separate requests. When one fails, the earlier ones stay applied, and the message names the step:
Running an update again is safe. Run a create again only with an External ID or the written-back Location Id, or it creates a second location.
Bulk Operations¶
With Use Bulk Operations on, IMan first reads every company in the store, with its contact roles and locations, in one bulk query. If that query fails, IMan writes nothing and fails every record. IMan matches each record against what it read, then sends the creates, updates, addresses and tax settings as bulk operations.
Records that name the same location go in successive rounds. A second record with the same new External ID then updates the location the first one created, and the last record wins. When a create ends with an unknown outcome, later records for that location fail rather than risk a second one. See Bulk Operations.
Access Scopes¶
The push needs write_companies. See Access Scopes.
Shopify Reference¶
companyLocationCreate and companyLocationUpdate in Shopify's GraphQL Admin API reference.