Manage multiple legal entities in a store

In a typical use case, one Shopify store corresponds to one legal entity, based on the information merchants provide when they set up their store. However, you can also use multiple legal entities in a store to enable merchants to sell their products in international markets.

This guide describes how to set up and manage multiple legal entity in a Shopify store.

Anchor to RequirementsRequirements

• Your app can make authenticated requests to the GraphQL Admin API.
• Your app is installed on either a partner development store or a store with Shopify's plus plan.

Anchor to LimitationsLimitations

The following limitations apply when working with multiple legal entities:

• You can only assign one legal entity for each country.
• The following features do not support multiple entities, and are available only for the primary entity:
  • Third party payment providers
  • Subscriptions
  • Reporting and Analytics
• Currently, only Shopify Payments, PayPal Express, and manual payment methods are supported across multiple entities. Other payment providers support associating only with the primary entity.

Anchor to How it worksHow it works

Legal entities can be managed and onboarded through the Organizations dashboard. After adding entities to your organization, you can associate them with one or more of your organization's shops. Each shop requires a designated primary entity that handles default settings and features that don't yet support multiple entities.

Anchor to Step 1: Access the ,[object Object], GraphQL APIStep 1: Access the BusinessEntity GraphQL API

A Shop’s legal entities are represented by the BusinessEntity GraphQL object and is accessible on Shopify’s Admin API.

Anchor to List all entities on a shopList all entities on a shop

A full definition of fields for the BusinessEntity GraphQL object can be found here.

Anchor to Step 2: Enable payment providers per legal entityStep 2: Enable payment providers per legal entity

Using multiple entities in a single shop permits you to onboard payment providers per legal entity. This means that each legal entity associated with your shop can onboard its own Shopify Payments account, tied to the country of the legal entity, allowing payments and orders on these accounts to be routed to a specific legal entity. This makes it possible to process domestic transactions when selling to an international market in which you have a legal entity presence, and also allows you to support a wider range of potential payout currencies. Other payment providers such as PayPal are also supported for multi-entity support.

Having multiple entities on a single store will also satisfy any country specific regulations (for example, for retail transacting) that may require business be conducted against an entity that is domiciled in the same region.

Anchor to Step 3: Contextualize buyers to a legal entityStep 3: Contextualize buyers to a legal entity

Buyers can be contextualized to use a payment provider for a specific entity based on market configurations. Each individual market in your store can be assigned one of your shop’s legal entities. Based on this mapping, all customers that are contextualized into this market will only be shown the set of payment methods that have been enabled for the respective legal entity (whilst also abiding by any other checkout restrictions).

Attributing a Market to one of your legal entities can be achieved through the marketCreate and marketUpdate mutations and setting the corresponding business_entity_id as an input parameter.

Anchor to Step 4: Add a bank account for an entity-specific Shopify Payments accountStep 4: Add a bank account for an entity-specific Shopify Payments account

As the use of multiple entities within one store permits the presence of multiple Shopify Payments accounts on the same store, you are able to add bank accounts that are tied to each of these accounts. The set of available settlement currencies is still dependent on the region that the individual Shopify Payments account country is tied to.

Anchor to Other queries for business entitiesOther queries for business entities

Anchor to Querying for entity attribution on associated objectsQuerying for entity attribution on associated objects

With multiple entity support, a subset of GraphQL objects can be queried to determine their respective entity attribution. These include:

• Order

• DraftOrder

• Market

• ShopifyPaymentsPayout

  The BusinessEntity field is exposed on these objects via the merchantBusinessEntity field. For example:

Entity information is also present under the field merchantBusinessEntityId on Shopify’s Order REST API and Order webhooks.

Anchor to Querying for Shopify Payments account by legal entityQuerying for Shopify Payments account by legal entity

As multiple Shopify Payments accounts are possible in a multi-entity shop, retrieving the relevant Shopify Payments account GraphQL object can be obtained by querying through a BusinessEntity.

Anchor to Next stepsNext steps

• Learn more about Shopify markets.