--- title: Manage multiple legal entities in a store description: >- Learn how to use legal entities in a store to access payment providers across different regions. source_url: html: 'https://shopify.dev/docs/apps/build/markets/multiple-entities' md: 'https://shopify.dev/docs/apps/build/markets/multiple-entities.md' --- ExpandOn this page * [Requirements](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#requirements) * [Limitations](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#limitations) * [How it works](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#how-it-works) * [Step 1: Access the Business​Entity Graph​QL API](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#step-1-access-the-businessentity-graphql-api) * [Step 2: Enable payment providers per legal entity](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#step-2-enable-payment-providers-per-legal-entity) * [Step 3: Contextualize buyers to a legal entity](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#step-3-contextualize-buyers-to-a-legal-entity) * [Step 4: Add a bank account for an entity-specific Shopify Payments account](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#step-4-add-a-bank-account-for-an-entity-specific-shopify-payments-account) * [Other queries for business entities](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#other-queries-for-business-entities) * [Next steps](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#next-steps) # 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. *** ## Requirements * Your app can make [authenticated requests](https://shopify.dev/docs/api/admin-graphql#authentication) to the GraphQL Admin API. * Your app is installed on either a partner dev store or a store with Shopify's plus plan. *** ## Limitations 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. *** ## How it works Legal entities can be managed and onboarded through the [Organizations dashboard](https://help.shopify.com/manual/your-account/manage-orgs-and-stores). 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. Note At present, associating an entity to a Shop can only be completed by contacting Shopify with the relevant entity information. *** ## Step 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. ### List all entities on a shop ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql query { businessEntities { id companyName displayName } } ``` ## JSON response ```json { "data": { "businessEntities": [ { "id": "gid://shopify/BusinessEntity/MTkyNTEyATUqOTM0", "companyName": "test company", "displayName": "Test Company" }, { "id": "gid://shopify/BusinessEntity/MDI4AzXwNzA", "companyName": "test company 1", "displayName": "Test Company 1" }, { "id": "gid://shopify/BusinessEntity/MDI0N1A4Mzg", "companyName": "test company 2", "displayName": "Test Company 2" }, { "id": "gid://shopify/BusinessEntity/MDI40KZ2MDY", "companyName": "test company 3", "displayName": "Test Company 3" } ] } } ``` A full definition of fields for the `BusinessEntity` GraphQL object can be found [here](https://shopify.dev/docs/api/admin-graphql/unstable/objects/BusinessEntity). *** ## Step 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. ![Screenshot of store with multiple business entities enabled, activating payments for each legal entity](https://shopify.dev/assets/assets/images/api/payments-apps/enable_sp_per_entity-CV8QF-Oa.png) *** ## Step 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](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/marketCreate) and [marketUpdate](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/marketUpdate) mutations and setting the corresponding `business_entity_id` as an input parameter. ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql mutation marketCreate { marketCreate(input: { name: "AU Market", handle: "au", businessEntityId: "gid://shopify/BusinessEntity/MDI40KZ2MDY", conditions:{ regionsCondition:{ regions: [{ countryCode: AU }] } }, ... }) { market { id handle status } } } ``` ## JSON response ```json { "data": { "marketCreate": { "market": { "id": "gid://shopify/Market/10123798", "handle": "au", "status": "ACTIVE" }, "userErrors": [] } } } ``` *** ## Step 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. *** ## Other queries for business entities ### Querying 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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) * [`DraftOrder`](https://shopify.dev/docs/api/admin-graphql/latest/objects/DraftOrder) * [`Market`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Market) * [`ShopifyPaymentsPayout`](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShopifyPaymentsPayout) The `BusinessEntity` field is exposed on these objects via the `merchantBusinessEntity` field. For example: ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql query { order(id: "gid://shopify/Order/9759593103382") { merchantBusinessEntity { id companyName displayName } } } ``` ## JSON response ```json { "data": { "order": { "merchantBusinessEntity": { "id": "gid://shopify/BusinessEntity/MTkyNTEyATUqOTM0", "companyName": "test company", "displayName": "Test Company" } } }, } ``` Entity information is also present under the field `merchantBusinessEntityId` on Shopify’s [Order REST API](https://shopify.dev/docs/api/admin-rest/unstable/resources/order) and [Order webhooks](https://shopify.dev/docs/api/admin-rest/2024-10/resources/webhook#event-topics-orders-create). ### Querying 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`. ## POST https\://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL query ```graphql query { businessEntity(id: "gid://shopify/BusinessEntity/MTg0MzQ5MTI0NjMw") { shopifyPaymentsAccountNext { ... } } } ``` ## JSON response ```json { "data": { "businessEntity": { "shopifyPaymentsAccountNext": { "name": "Shopify Payments", "id": "gid://shopify/ShopifyPaymentsAccountNext/123", "country": "CA", ... } } } } ``` *** ## Next steps * Learn more about [Shopify markets](https://shopify.dev/docs/apps/build/markets). *** * [Requirements](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#requirements) * [Limitations](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#limitations) * [How it works](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#how-it-works) * [Step 1: Access the Business​Entity Graph​QL API](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#step-1-access-the-businessentity-graphql-api) * [Step 2: Enable payment providers per legal entity](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#step-2-enable-payment-providers-per-legal-entity) * [Step 3: Contextualize buyers to a legal entity](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#step-3-contextualize-buyers-to-a-legal-entity) * [Step 4: Add a bank account for an entity-specific Shopify Payments account](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#step-4-add-a-bank-account-for-an-entity-specific-shopify-payments-account) * [Other queries for business entities](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#other-queries-for-business-entities) * [Next steps](https://shopify.dev/docs/apps/build/markets/multiple-entities.md#next-steps)