About split carts in checkout

With split carts in checkout, each order a customer completes can contain more than one delivery group. A delivery group might represent a separate shipment, a different shipping option, or a pickup group.

Split carts support two related checkout experiences:

• Split shipping, where items ship in separate packages such as those from different locations or those that ship with different rates.
• Ship and pickup in one order, where some items ship to the customer and other items are picked up from a location.

After checkout, Shopify represents each group as a fulfillment order. The same order can have one or many fulfillment orders. To support split carts, use fulfillment orders as the source of truth for fulfillment work, and read each fulfillment order's deliveryMethod to understand whether it represents shipping, or another delivery method type.

Anchor to How split carts affect appsHow split carts affect apps

A single order can generate more than one FulfillmentOrder for the same location. This doesn't require API schema changes, because delivery and fulfillment data is already modeled as collections.

This can happen when a checkout includes:

• Multiple shipments with different delivery promises, shipping profiles, or fulfillment locations.
• Multiple delivery method types, such as a shipping group and a pickup group in the same order.

If your app already reads fulfillment data from the FulfillmentOrder object and processes each fulfillment order independently, then you might not need to make changes. If your app reads line item information from the Order object or assumes a one-to-one mapping between an order, location, and fulfillment order, then update it to read fulfillment order data and the fulfillment order deliveryMethod.

Anchor to Split cart scenariosSplit cart scenarios

The following scenarios show how a checkout can split into multiple delivery groups and fulfillment orders. In each scenario, process fulfillment orders independently and use fulfillment order delivery method data instead of order-level assumptions.

Anchor to Split shippingSplit shipping

An order can split into multiple fulfillment orders when it includes any of the following:

• Preorders and one-time purchase products.
• Subscriptions and one-time purchase products.
• Products shipping from different locations.
• Products from different shipping profiles.

When a cart meets any of these conditions, Shopify creates multiple fulfillment orders, one per delivery group.

Anchor to Ship and pickup in one orderShip and pickup in one order

Ship and pickup in one order is a split cart scenario where a customer chooses to ship some items and pick up other items during the same checkout. Shopify creates separate fulfillment orders for the shipping and pickup groups.

For apps, the key difference from split shipping is that fulfillment orders can have different deliveryMethod.methodType values. For example:

• SHIPPING identifies a fulfillment order that ships to the customer.
• PICK_UP identifies a fulfillment order that the customer picks up from a location.

Don't infer the delivery method from shippingLines, delivery profile names, location count, or the presence of a shipping address. Use the fulfillment order deliveryMethod field instead.

Anchor to How split carts work with APIsHow split carts work with APIs

After a customer completes checkout and Shopify creates an order, order routing creates one or more fulfillment orders. Each fulfillment order represents work for a specific group of items at a specific location, and includes the deliveryMethod that describes how those items reach the customer.

For split shipping, multiple fulfillment orders might all use the SHIPPING delivery method type, but have different shipping options, delivery promises, shipping profiles, or assigned locations. For ship and pickup in one order, fulfillment orders for the same order can use different delivery method types, such as SHIPPING and PICK_UP.

Fulfillment order data is available in the GraphQL Admin API and REST Admin API.

Anchor to Get notified after order routing is completeGet notified after order routing is complete

Your app can subscribe to the fulfillment_orders/order_routing_complete webhook to be notified after Shopify finishes order routing and creates the related fulfillment orders. You can also refer to the API documentation for creating a webhook subscription and fetching existing webhook subscriptions.

Anchor to Fetch relevant data using existing APIsFetch relevant data using existing APIs

While you can integrate with Shopify APIs in different ways, we recommend that you fetch order details that include line items, shipping lines, fulfillment orders, fulfillment order line items, and delivery method information.

Anchor to GraphQL Admin APIGraphQL Admin API

Anchor to Fetch order detailsFetch order details

You can fetch a first page of order details, such as the order ID, line items, shipping lines, fulfillment orders, fulfillment order line items, and delivery methods, in a single GraphQL query on the Order object.

For example, you might want to fetch the following information:

• Line items: You can fetch details about the items in an order, such as the product variant, its price, and more, using the lineItems connection on the Order object. Each connection edge exposes a LineItem.

• Shipping lines: You can fetch a summary of shipping costs for an order using the shippingLines connection on the Order object. Don't use shipping lines as the only source of delivery groups, because pickup fulfillment orders might not have a matching shipping line.

• Fulfillment orders: You can access fulfillment orders using the fulfillmentOrders connection on the Order object. Use fulfillment order line items to map the fulfillment order back to order line items. Use the deliveryMethod.methodType field on the FulfillmentOrder object to identify whether a fulfillment order is for shipping, pickup, local delivery, or another delivery method type.

  The GraphQL connection types are paginated. For orders with many line items, shipping lines, or fulfillment orders, paginate each connection and keep nested connection page sizes small to stay within GraphQL Admin API query cost limits.

  The following example fetches the information listed above:

Anchor to Interpret delivery methodsInterpret delivery methods

Each fulfillment order has its own deliveryMethod. For split shipping, multiple fulfillment orders can have methodType: "SHIPPING", but different presentedName, serviceCode, or delivery promise dates. For ship and pickup in one order, use methodType to separate shipping and pickup work.

Use methodType to choose fulfillment behavior:

• SHIPPING: Ship items to the fulfillment order destination.
• PICK_UP: Prepare items at the assigned location for customer pickup. Use additionalInformation.instructions and additionalInformation.phone when they're present.
• Other values, such as LOCAL, PICKUP_POINT, RETAIL, and NONE: Handle or ignore these values explicitly, depending on what your app supports.

Anchor to REST Admin APIREST Admin API

Delivery information can also be fetched using the REST Admin API Order and FulfillmentOrder resources. In REST responses, use delivery_method.method_type for the same decision that you make with deliveryMethod.methodType in GraphQL Admin API responses.

Anchor to Fetch order detailsFetch order details

You can fetch order details, such as the order ID, status, line items, and shipping lines, using the Order resource.

Anchor to Fetch fulfillment order detailsFetch fulfillment order details

Use the Fulfillment Order REST resource to fetch fulfillment order details, such as the fulfillment order ID, status, fulfill_at date, assigned location, line items, and delivery method.