Process payments through multiple business entities

Merchants that operate through more than one legal entity can process each Shop Pay Wallet payment through the business entity that should own it. The charge, the order, and the payout all belong to that entity's Shopify Payments account. You choose the entity when you create the payment request session, and you can change it while the buyer checks out, for example when the shipping address changes.

Anchor to RequirementsRequirements

• Multi-entity is available on the Shop Pay Wallet Enterprise plan.
• Storefront API and GraphQL Admin API version 2027-01 or later. Earlier versions don't include the business entity arguments, fields, mutation, and error codes for payment request sessions and receipts.
• Business entities added to the store, each with Shopify Payments connected.
• A working Shop Pay Wallet integration. To set one up, refer to Get started with Shop Pay Wallet and Sessions and events.
• Error handling for business entity errors on session creation, business entity updates, and submit. Refer to Handle errors.

Anchor to How it worksHow it works

1. You can pass a business entity ID when you create the payment request session with ShopPayPaymentRequestSessionCreate. If you don't pass one, then the store's primary business entity processes the payment.
2. Shop Pay uses the session's business entity to decide which payment methods are available to the buyer, based on the payment methods that are active for that business entity.
3. While the buyer checks out, your backend can change the business entity associated with the session.
4. When you submit the payment, Shopify checks the session's business entity again and records it on the payment request receipt. The charge, the order, and the payout go through that entity's Shopify Payments account.

Anchor to Get business entity IDsGet business entity IDs

Use the GraphQL Admin API businessEntities query to list the store's business entities:

The results include archived business entities. An archived entity can't process payments, so leave out every entity where archived is true.

Keep a mapping in your system from your own routing rule, such as the buyer's shipping country, to the entity's id. Pass the full id value, such as gid://shopify/BusinessEntity/1002, as businessEntityId.

A business entity can process payments only when its Shopify Payments account is enabled and can accept charges, Shop Pay is active on it, and it has at least one active payment method.

Don't query businessEntities for every checkout. The result changes only when the merchant adds or changes a business entity in the Shopify admin, so querying it on each transaction returns the same data and adds latency to your checkout. Read the entity from your mapping instead, and refresh the mapping after the merchant adds or changes an entity in the Shopify admin, or after a request fails with a business entity error code.

Anchor to Create a session with a business entityCreate a session with a business entity

In the sessionrequested listener, send your backend whatever it needs to choose the business entity, such as the country of the storefront that the buyer is on:

On your backend, pass the entity's ID as businessEntityId to the ShopPayPaymentRequestSessionCreate mutation. From version 2026-10, only sourceIdentifier is required and the paymentRequest argument is deprecated, so the example doesn't pass a payment request:

If the business entity can't process payments, then Shopify doesn't create the session. Refer to On session creation.

Anchor to Change the business entity during checkoutChange the business entity during checkout

If the right business entity depends on something the buyer chooses in the Shop Pay checkout, such as the shipping address, then change the session's entity while handling the event that triggers the change. Call the ShopPayPaymentRequestSessionBusinessEntityUpdate mutation from your backend, and wait for it to return before you call the event's complete method:

On your backend, pass the session token and the new entity's ID:

When you change the business entity, keep the following in mind:

• Update the entity before you call the complete method for the event, so that Shopify applies the new entity to the checkout.
• businessEntityId is required on this mutation. To move the session back to the primary business entity, pass the primary entity's ID.
• You can change the entity until you submit the payment. If a payment attempt fails, then you can change it again before the buyer retries.

Anchor to Submit the paymentSubmit the payment

The ShopPayPaymentRequestSessionSubmit mutation doesn't take a business entity. Shopify reads the entity from the session, checks it again, and records it on the payment request receipt. Request businessEntityId on the receipt to confirm the entity that processes the payment:

If the business entity can no longer process payments, for example if the entity was archived after the session was created, then the submit fails and Shopify doesn't create a receipt. Refer to On submit.

Anchor to Reconcile ordersReconcile orders

The payment request receipt records the business entity that the charge, the order, and the payout went through. In your reconciliation job, request businessEntity on the GraphQL Admin API shopPayPaymentRequestReceipt or shopPayPaymentRequestReceipts query:

businessEntity also returns archived entities, so an order stays attributed to the entity that took the payment after the merchant archives it. For the rest of the reconciliation flow, refer to Monitoring and resiliency.

Anchor to Handle errorsHandle errors

Your integration is responsible for handling business entity errors. Shopify doesn't retry with a different entity, so decide what your checkout does when an entity can't process a payment, such as creating the session again with a different entity, or showing the buyer a message and stopping the checkout.

Shopify returns business entity errors in userErrors. Request code in every userErrors selection, and use it to decide what to do next.

Anchor to Business entity error codesBusiness entity error codes

Anchor to On session creationOn session creation

The error's field is ["businessEntityId"], and Shopify doesn't create a session. You don't get a token to pass to completeSessionRequest(), so close the Shop Pay dialog with session.close() and handle the failure in your own checkout. Your system decides whether to create the session again with a different entity, because Shopify doesn't fall back to the primary entity.

Anchor to On a business entity updateOn a business entity update

The error's field is ["businessEntityId"], and the session keeps its previous business entity. If the buyer can't pay through the previous entity for their new choice, then reject the change in the complete call. For example, return a shippingAddressError for a shipping address that no business entity can process:

The update mutation can also return the following codes on the token field:

• PAYMENT_REQUEST_NOT_FOUND: the token doesn't match a payment request session on this store.
• PAYMENT_REQUEST_SESSION_ALREADY_SUBMITTED: you already submitted the payment and the attempt hasn't failed, so the business entity can't change. Create a new session for another payment attempt.

For more ways to return errors from a complete call, refer to Handle errors in Sessions and events.

Anchor to On submitOn submit

The error's field is null, and Shopify doesn't create a receipt. The session's business entity was valid when you selected it, but its state changed before you submitted the payment.

Return a generalError from completePaymentConfirmationRequest() so that the buyer stays in the Shop Pay dialog:

Before the buyer tries again, move the session to a business entity that can process payments with ShopPayPaymentRequestSessionBusinessEntityUpdate. MULTI_ENTITY_NOT_SUPPORTED on submit means that the store stopped using multiple business entities after you created the session, so your system decides how to handle the checkout.

Anchor to Next stepsNext steps

Sessions and events

Create payment request sessions and handle checkout events.

GraphQL pre-payment

Create, update, and submit payment request sessions using the Storefront API.

Monitoring and resiliency

Set up webhooks, handle disputes, and implement reconciliation.