How do multi-location company hierarchies (headquarters plus regional branches, each with different pricing) migrate to Shopify B2B's company/location model?
Shopify B2B has exactly two levels: a company and its company locations. The Company object in the Admin API carries no parent or child company field, so a three-level headquarters-to-region-to-branch tree flattens on import (Shopify developer docs, September 2026). Per-branch pricing survives, because catalogs and payment terms both attach at the location.
The model you are landing in
A company is "the parent organization for one or more company locations." A company location "represents the business that you're selling to in a B2B transaction," and creating a company creates one location automatically (per Shopify Help Center, September 2026).
The hard ceiling is that this is the whole hierarchy. The Company object exposes id, name, note, externalId, createdAt, updatedAt, customerSince, lifetimeDuration, locations, contacts, contactRoles, defaultRole, and the counts contactsCount, locationsCount, ordersCount, totalSpent. There is no parentCompany and no childCompanies (per Shopify developer docs, September 2026). Regions cannot be a level.
What the limits allow
| Limit | Value |
|---|---|
| Company locations per company | 10,000 |
| Customers per company | 10,000 |
| Customers per company location | 50 |
| Catalogs per company location | 25 |
Ten thousand locations is generous enough that the flattening is almost never a capacity problem. Fifty customers per location is the one that bites a large branch with a wide purchasing department.
What lives where
| Setting | Company | Location |
|---|---|---|
| Payment terms | Yes, inherited by all locations | Yes, overrides the company setting |
| Catalogs and pricing | Yes | Yes, up to 25 |
| Shipping and billing addresses | No | Yes |
| Tax ID and tax exemptions | No | Yes |
| Checkout configuration (draft-order submission) | Yes | Yes |
| Metafields | Yes | Yes |
| Contacts and permissions | Contacts belong to the company | Assignment and role are per location |
This is why the flattening is survivable: everything a regional branch needs to be priced, taxed and shipped differently already lives at the location. What you lose is the region as an addressable thing.
Modelling the region you cannot nest
Three approaches, and the right one depends on why the region exists.
Region as a metafield on the location. Add a region company-location metafield and set it on import. Regions become a reporting dimension and a Flow condition rather than a structural level. This is our default, because most regional tiers in legacy hierarchies exist for reporting and for a price band, and both of those survive as attributes.
Region as a catalog. If the region's only real function is a price tier, the region is a catalog. Each branch location gets the regional catalog assigned. On Plus that assignment is direct; on Basic, Grow and Advanced, catalogs attach through B2B markets and you get 3 active ones, which is the parent page's constraint arriving from a different direction.
Region as the company. Where regions are genuinely separate legal entities with their own credit relationships, terms and tax registrations, they should be separate companies and the group is not a Shopify structure at all. It is a structure in your ERP. Trying to express a legal-entity group inside Shopify B2B produces a model that reports well and invoices wrong.
The constraint that decides it: a buyer belongs to one company
A customer can be added to only one company, though they can be assigned to multiple locations within it (per Shopify Help Center, September 2026). Matrixify's B2B documentation states the same rule from the import side: "One Customer of the store can exist only in one Company," and you cannot link the same customer to several companies.
That single rule settles most hierarchy debates. If a central purchasing manager at headquarters buys on behalf of six branches, all six branches must be locations of one company. If you model regions as companies, that person cannot span them, and your import will either fail or silently duplicate them.
So the sequence is: find every buyer who touches more than one node in the source hierarchy, and let those buyers define your company boundaries. The org chart does not define them. The purchasing behaviour does.
Migration order
- Export the source hierarchy with the ship-to nodes marked. Anything that ships and gets priced is a candidate location.
- Map every buyer to the nodes they transact against. This is the step that determines company boundaries.
- Draw company boundaries so that no buyer spans two companies. Where that is impossible, you have found a genuine multi-entity case, and the answer is separate companies with separate buyers.
- Create companies and locations, carrying the legacy node identifier into
externalIdon the company and a metafield on the location. Do this even if you think you will not need it. - Set payment terms at the company and override only where a branch genuinely differs.
- Assign catalogs at the location and check each is within 25.
- Assign contacts with roles, watching the 50-per-location ceiling.
Matrixify handles companies, company locations, linked customers with roles, catalogs assigned to a location by name, payment terms including net 7 through 90, and company-location store credit (per Matrixify documentation, September 2026), which makes this a bulk load rather than a scripted one for most mid-market hierarchies.
When NOT to flatten
- When regions are separate legal entities. Separate companies, and accept that the group lives in your ERP.
- When a branch has its own credit relationship and its own limit. Terms are per location, so this one is fine flattened. Credit limits are not stored anywhere, which is a different problem covered in the net-terms thread.
- When a single buyer must span regions. Then the regions are locations of one company, and the debate is over.
The Deploi point of view
Our own position, from building on Shopify. Separate from the facts above.
- Our take: Let purchasing behaviour draw the company boundaries, not the org chart. The one-buyer-one-company rule is the only hard constraint in this model, and every hierarchy question resolves against it faster than it resolves against a diagram.
- What we’ve seen: Legacy hierarchies carry nodes that have never transacted: a holding company, a dissolved division, a region created for a report. Importing them as locations creates dead company locations that show up in every picker a buyer sees. Mark every node with its last order date before deciding what to bring.
- Where we disagree: The usual advice is to preserve the source hierarchy as faithfully as possible. We think fidelity is the wrong goal when the target has two levels and the source has four. Preserve the facts the hierarchy encoded, which are pricing, shipping, tax and reporting, and let the shape go. Keeping the shape means keeping dead nodes and inventing relationships Shopify cannot enforce.
- What this page adds: that the Company object has no parent or child field so nesting is structurally impossible, that a customer can belong to only one company which is the rule that actually draws the boundaries, the per-company and per-location ceilings, and the three ways to preserve a region once it cannot be a level.
Reviewed by Martin Dejnicki, Director of SEO & AI Search. Facts verified 2026-09-14.
Where we worked this out
Our decision records