Shopify enables ship-and-pickup in a single order — what merchants and app developers must do now

Table of Contents

1. Key Highlights
2. Introduction
3. How the change actually works: checkouts, deliveryGroups and fulfillment orders
4. Technical details developers need to know
5. How to test your app right now (step-by-step)
6. Common failure modes and how to fix them
7. Operational impacts for merchants and fulfillment centers
8. Sample developer audit checklist
9. Real-world scenarios and examples
10. Migration and rollout plan for development teams
11. Communication tips for merchant-facing changes
12. Monitoring, metrics and post-deployment validation
13. Third-party considerations: carriers, fulfillment partners and marketplaces
14. Example developer fixes: before and after
15. Legal and customer-experience considerations
16. FAQ

Key Highlights

• Shopify Plus and Enterprise stores can now let customers choose shipping or store pickup per item in a single checkout, producing one order with multiple fulfillment orders and differing delivery methods.
• No new API fields were introduced, but existing fields can return multiple deliveryGroups and fulfillment orders with a delivery_method (SHIPPING or PICK_UP); apps must be audited and tested now via feature preview to avoid checkout errors and routing failures.

Introduction

Shopify has updated checkout behavior for Plus and Enterprise merchants so customers can mix shipping and local pickup within the same order. For merchants, that means a single order can be split into multiple fulfillment orders — one group shipped to the customer and another picked up at a store. For developers, the implications are practical and immediate: apps that assume a single delivery method per order must be updated and tested before the change reaches production.

This change does not introduce new API fields. Instead, existing checkout and order objects will present data in new combinations: checkouts may include multiple deliveryGroups, and orders can contain multiple fulfillment orders with a delivery_method field that identifies whether items are SHIPPING or PICK_UP. The window for testing is open now through Shopify’s feature preview. Merchants and app teams that delay could see checkout errors, incorrect totals, failed fulfillment routing, or disrupted customer experiences.

The following article explains the change in technical detail, presents concrete testing steps and examples, surfaces common failure modes and fixes, and delivers a practical rollout and communication plan for development and merchant teams.

How the change actually works: checkouts, deliveryGroups and fulfillment orders

Shopify’s checkout flow now supports per-item delivery choices when both shipping and local pickup are enabled. That means a customer can decide that one item will be shipped while another will be picked up at a store. Shopify aggregates those choices into a single Order resource that contains multiple fulfillment orders. Each fulfillment order represents a set of items sharing the same fulfillment method and, where applicable, the same pickup location.

Key elements to focus on:

• Checkouts can now return multiple deliveryGroups. Each deliveryGroup represents a set of items and a delivery method for those items. Historically many integrations assumed a single deliveryGroup per checkout.
• Orders can contain multiple fulfillment orders, each carrying its own delivery_method field. delivery_method will be either SHIPPING or PICK_UP and indicates how that fulfillment order should be routed and processed.
• No new API endpoints or fields were added; developers must accommodate new combinations of existing data structures.

Concrete example A customer places a cart with three SKUs:

• SKU A: shipped to home
• SKU B: picked up at Store #12
• SKU C: picked up at Store #12

Shopify creates one Order that includes two fulfillment orders:

• Fulfillment order 1 — delivery_method: SHIPPING — contains SKU A
• Fulfillment order 2 — delivery_method: PICK_UP — contains SKU B and SKU C and references Store #12 as the pickup location

Apps and middleware that expect a single fulfillment order per Order can misinterpret these results — for example, trying to route the entire order to a carrier or attempting to mark units as fulfilled in a single step. That leads to routing failures, incorrect rate calculations, or broken UI states for merchants and customers.

Technical details developers need to know

No new schema fields were introduced. The behavior change affects how fields are populated and how many instances of certain objects can appear.

What to inspect in your codebase

• Checkout deliveryGroups: code that reads checkout.deliveryGroups (or equivalent) must handle 0, 1, or many groups. Previously single-group assumptions will fail.
• Order.fulfillmentOrders: processes should iterate over order.fulfillmentOrders and not assume one-to-one mapping between order and fulfillment action.
• FulfillmentOrder.delivery_method: always read this field when determining route, handler, or workflow. Values are SHIPPING and PICK_UP.
• Pickup location metadata: fulfillment orders for pickup often include metadata about the pickup location (store ID, address). Ensure apps correctly parse and display pickup location to merchant and customer.
• Price and tax calculations: verify that shipping charges, calculated shipping rates, and taxes apply correctly to deliveryGroups and their items. Promo logic that applies sitewide shipping discounts may require per-fulfillment-order adjustments.

Webhooks and events to prioritize

• fulfillment_orders/create and fulfillment_orders/update: critical to detect newly created fulfillment orders and route them to the correct systems (pick-pack for pickup, shipping carriers for shipment).
• order/updated and checkout/update: monitor these for changes in deliveryGroups or fulfillment orders, particularly if customers edit orders or merchants modify fulfillment.
• fulfillment_events or fulfillment_updates used by third-party fulfillment apps: ensure those webhooks are listened to per fulfillment order and that actions are taken at the fulfillment order level.

Concurrency and idempotency

• Operations that fulfill or modify an Order must be implemented at the fulfillment order level to avoid race conditions. Two parallel processes trying to fulfill different fulfillment orders within the same Order should target separate fulfillment order IDs to remain idempotent.
• Use fulfillment order IDs as the unit of work for routing, inventory allocation, and fulfillment updates.

Security and permissions

• Ensure access tokens and scopes used by apps include permissions to read and mutate fulfillment orders. Review app scopes to confirm they cover the necessary resources for both pickup and shipping flows.

Sample pseudocode for routing logic The following pseudocode shows how to iterate fulfillment orders and route them appropriately. Adapt to your stack and language.

for each fulfillmentOrder in order.fulfillmentOrders:
    method = fulfillmentOrder.delivery_method
    items = fulfillmentOrder.line_items
    if method == "PICK_UP":
        pickup_location = fulfillmentOrder.pickup_location_id
        route_to_pickup_queue(pickup_location, items, fulfillmentOrder.id)
    else if method == "SHIPPING":
        shipping_address = order.shipping_address
        rates = calculate_shipping_rates(items, shipping_address)
        select_carrier_and_create_shipment(items, rates, fulfillmentOrder.id)
    else:
        log_error("Unknown delivery method", fulfillmentOrder.id)

This approach prevents treating an Order as a monolithic unit for fulfillment.

How to test your app right now (step-by-step)

Shopify’s feature preview is open; use it to validate changes thoroughly before they reach merchants without warning.

1. Enable feature preview
   • Go to dev.shopify.com/dashboard and sign in.
   • Under “Dev stores,” create a new dev store.
   • Select “Plus” as the Shopify Plan for that dev store.
   • Under “Test a feature preview on this store,” enable “Ship and pickup.”
   • If you already have a dev store, add the feature preview to it.
2. Create test products and locations
   • Create multiple products with distinct SKUs and inventory tracked at multiple locations.
   • Add at least one local pick-up location (representing a real store) and ensure inventory exists there for the SKUs you’ll test.
3. Place varied test orders
   • Test orders that are:
     • All shipping
     • All pickup
     • Mixed: some items shipping, some items pickup (same store)
     • Mixed: pickup items assigned to different stores (if supported)
   • For each order, verify checkout displays correct pickup options and shipping rates for the corresponding items.
4. Validate API responses
   • Fetch the checkout object and inspect checkout.deliveryGroups. Confirm you can handle multiple groups and that each group contains correct line items and method.
   • Fetch the created Order and inspect order.fulfillmentOrders. Validate the delivery_method for each fulfillment order and confirm items match the expected groups.
   • Confirm fulfillment orders include pickup metadata (pickup location ID, address) where applicable.
5. Verify app logic end-to-end
   • Ensure your app reads and uses the delivery_method in fulfillment order workflows.
   • Trigger fulfillment_order.create/update webhooks and confirm your service processes each fulfillment order separately.
   • For shipping-related fulfillment orders, confirm shipping rate calculations and carrier label creation apply only to the SHIPPING fulfillment order.
   • For pickup-related fulfillment orders, confirm merchant notifications, pick lists, and point-of-sale integrations reflect the PICK_UP fulfillment order and location.
6. Test edge cases
   • Partial refunds that affect only one fulfillment order
   • Returns that involve pickup items and shipped items differently
   • Order edits where a previously-shipped item is converted to pickup or vice versa
   • Promotions that apply free shipping to some items but not others
   • Inventory allocation when a pickup location runs out of stock for one item in a mixed fulfillment order
7. Monitor logs and failures
   • Check your system logs for exceptions related to undefined deliveryGroups or missing fulfillmentOrder properties.
   • Add alerting around failed webhook processing for fulfillment_orders events.
8. Communicate to merchants
   • If the app changes merchant-facing data or requires new setup (for example, mapping pickup locations), prepare release notes and step-by-step admin guides.

Common failure modes and how to fix them

Apps and merchant operations that previously assumed only one fulfillment method per order will encounter a predictable set of issues. Below are practical failure modes and concrete remedies.

Failure: App attempts to fulfill an order as a single unit

• Symptom: Fulfillment or shipping label logic triggers for the whole order and tries to fulfill items that must be picked up.
• Fix: Change fulfillment processes to operate at the fulfillmentOrder level. Use fulfillment_order.id as the unit for fulfillment actions and carrier label creation.

Failure: Shipping rates or discounts applied globally to the whole order

• Symptom: A customer receives incorrect shipping totals because a free-shipping promotion was applied incorrectly across both shipped and pickup items.
• Fix: Recalculate shipping totals per deliveryGroup or fulfillmentOrder. Implement logic to apply promotions and discounts to the relevant subset of line items only.

Failure: Pickup scheduling or location displayed incorrectly

• Symptom: Merchant or customer interface shows wrong pickup location for pickup items.
• Fix: Verify fulfillment order pickup metadata is parsed and surfaced (store ID, address, pickup instructions). Ensure mapping from fulfillment order to POS or in-store pickup systems uses the pickup_location_id supplied in the fulfillment order.

Failure: Webhook handlers make single-order assumptions

• Symptom: Webhook processing errors when receiving fulfillment order events because code tries to access a single fulfillment order or map webhooks to the old order-level flow.
• Fix: Update webhook handlers to iterate and process each fulfillment order independently. Add idempotency keys keyed by fulfillment_order.id.

Failure: Inventory allocation mismatches across locations

• Symptom: Items promised for pickup are not reserved at the pickup location, causing fulfillment failure at pickup time.
• Fix: Ensure inventory allocation uses the fulfillment order’s pickup location and allocate inventory at that location when the fulfillment order is created or confirmed.

Failure: Analytics and reporting aggregates incorrectly

• Symptom: Reports that assumed a one-to-one relationship between order and fulfillment method show wrong counts for shipped vs pickup orders.
• Fix: Update back-end reporting to account for fulfillmentOrder-level delivery_method and compute metrics based on fulfillment orders rather than orders for delivery-type metrics.

Operational impacts for merchants and fulfillment centers

Merchants will gain operational flexibility but must adjust store processes and systems to realize the benefits without friction.

Fulfillment routing and staffing

• In-store teams must expect pickup-specific task lists even when the core order also contains shipped items. Prepare pick lists and signage that reference fulfillment order IDs to avoid confusion.
• Warehouse and shipping teams should focus strictly on shipping fulfillment orders; they must not attempt to fulfill items slated for pickup.

Point-of-sale (POS) and in-store pickup

• POS systems and register staff should be updated to link pickups to the proper fulfillment order and to mark items as picked up once customers arrive.
• Consider setting up a dedicated pickup counter workflow that references fulfillment order IDs and pickup codes or barcodes.

Customer notifications and pickup windows

• Pickup notifications should reference the pickup location and specify which items are ready. Avoid notifications that generically say “your order is ready,” which could confuse customers who have both pickup and shipped items.
• If your pickup flow uses redemption codes or QR codes, generate them per fulfillment order so only pickup-eligible items can be claimed.

Returns, exchanges and customer care

• Support agents need training to understand multi-fulfillment orders. A single Order ID may encompass items shipped and picked up; refunds or exchanges may apply to one fulfillment order only.
• Provide scripts and case-handling guides that instruct representatives to confirm delivery_method per line item before taking action.

Inventory management

• Inventory reservations must be per fulfillment order and per location. Avoid global decrements that don’t reflect where items will be collected.
• Replenishment policies should track pickup demand separately from shipped demand when pickup becomes a significant percentage of orders.

Example operational flow for a mixed order

1. Customer places order with two pickup items and one shipment.
2. Shopify creates two fulfillment orders (PICK_UP and SHIPPING).
3. Your system receives fulfillment_orders/create for both orders.
4. The shipping fulfillment order is routed to the warehouse system to create a shipping label.
5. The pickup fulfillment order is routed to the local store’s pick list and generates a pickup code.
6. Shipping and pickup notifications are generated and targeted to the relevant fulfillment orders.
7. Once pickup is completed at the store, the pickup fulfillment order is marked as fulfilled without affecting the shipping fulfillment order’s state.

Sample developer audit checklist

Use this checklist to run through code and architecture areas likely to be affected.

Codebase

• Identify all places where code reads checkout.deliveryGroups or order.fulfillmentOrders.
• Confirm iteration over multiple deliveryGroups and fulfillmentOrders; remove single-instance assumptions.
• Ensure your UI renders multiple delivery options when checkout.deliveryGroups length > 1.
• Check shipping calculation code to apply rates per deliveryGroup.

Webhooks and events

• Verify webhook handlers support fulfillment_orders/create and fulfillment_orders/update and process by fulfillment order ID.
• Confirm retry and idempotency logic keyed by fulfillment_order.id.
• Add alerting for unhandled webhook payload attributes.

Integrations

• Validate external fulfillment services accept per-fulfillment-order requests or update middleware to split orders.
• Test carrier label generation per fulfillment order and ensure labels are linked to fulfillment_order.id.
• Update POS integrations to accept pickup metadata and mark fulfillment orders as picked up.

User interface and UX

• Merchant dashboards display fulfillment orders independently and show delivery_method for each.
• Customer emails and notifications call out which items are pickup vs shipped.
• Admin workflows allow merchants to manage fulfillment orders separately.

Testing

• Run the dev store feature preview and execute mixed checkout scenarios.
• Cover edge cases: refunds, edits, returns, partial fulfillments.
• Add automated tests that simulate multiple deliveryGroups and multiple fulfillment orders.

Documentation and support

• Prepare release notes explaining behavioral changes for merchants.
• Update developer documentation and public support articles.
• Prepare merchant-facing FAQs and walkthroughs.

Real-world scenarios and examples

Retail chain with multiple stores A regional retailer with ten stores offers same-day pickup in selected locations. Previously, if a customer bought multiple items with mixed availability across channels, the merchant encouraged separate orders. Now a customer can place a single order: two pieces will be ready in-store at Store #4, while a large item ships from the central warehouse. The retailer must ensure the pickup team uses fulfillment_order IDs to avoid taking actions on shipped items and that inventory at Store #4 is reserved for the pickup fulfillment order.

Subscription or replenishment business A subscription box vendor sells both subscription boxes and add-on single-purchase items. If a customer adds a one-off item for store pickup while subscription items are shipped, the subscription fulfillment process must remain isolated from pickup flows. Subscription shipment automation should ignore pickup fulfillment orders and handle only SHIPPING fulfillment orders.

Third-party logistics (3PL) integration A 3PL provider that receives order payloads to generate pick-and-pack instructions must now identify and process only fulfillment orders that indicate SHIPPING. The 3PL should ignore PICK_UP orders and let the merchant’s stores handle pickup fulfillment.

Marketplace and multi-seller scenarios Marketplaces that aggregate offers from multiple sellers must route fulfillment orders back to the correct seller based on fulfillment order contents and pickup location. Sellers that provide local fulfillment at brick-and-mortar locations should receive PICK_UP fulfillment orders routed directly to their store systems.

Migration and rollout plan for development teams

A staged rollout reduces customer disruption and gives teams time to adapt.

1. Discovery and inventory (1–2 days)
   • Run the audit checklist across the codebase and integrations.
   • Identify downstream systems and partners that will be impacted.
2. Implement per-fulfillment-order processing (1–3 weeks depending on complexity)
   • Update backend processing to use fulfillment_order.id as the primary unit.
   • Update shipping and pickup handlers to select logic based on delivery_method.
3. Update UI and merchant communications (1 week)
   • Modify admin dashboards and merchant-facing UI to present multiple fulfillment orders and pickup metadata clearly.
   • Draft helpdesk scripts for support teams.
4. Test in feature preview (ongoing during development)
   • Run the test matrix on dev stores with Shopfiy’s feature preview enabled.
   • Include QA scenarios for refunds, partial fulfillments, and edits.
5. Pilot with selected merchants (2–4 weeks)
   • Offer the updated app or integration to a small set of merchants for real-world validation.
   • Monitor logs and merchant feedback.
6. Full rollout and monitoring (biweekly)
   • Release to all merchants once pilot issues are resolved.
   • Continue to monitor webhook error rates, fulfillment failures, and customer complaints.
7. Post-rollout follow-up (ongoing)
   • Collect metrics showing pickup vs shipping volumes, failures, and time-to-pickup. Use this data to iterate.

Communication tips for merchant-facing changes

Clear communication prevents confusion for merchants and reduces support load.

• Announce the change with concrete examples: show a mixed-order flow that previously required two orders.
• Provide a short checklist for merchants: verify pickup locations, update in-store staff, confirm POS integration.
• Create step-by-step guides for setup: enabling local pickup, assigning inventory to locations, and testing mixed checkouts.
• Offer training sessions or webinars for high-volume merchants and enterprise customers.
• Provide templates for customer-facing copy (emails, pickup instructions) so merchants can update wording quickly.

Suggested merchant-facing message outline

• What changed: one-order mixed ship-and-pickup capability.
• Why it matters: simpler checkout for customers and fewer abandoned carts.
• Action required: test checkout, update store staff, and review shipping discounts or promotions.
• Support resources: testing guide link, developer forum link, contact support.

Monitoring, metrics and post-deployment validation

Track the right metrics to ensure the change is working as intended and to quickly detect problems.

Operational metrics

• Fulfillment order creation success rate: percent of fulfillment_orders/create webhooks processed without errors.
• Fulfillment order routing failures: number and cause of failures to route fulfillment orders to carriers or stores.
• Time-to-pickup: median time between pickup fulfillment order creation and fulfillment by store staff.
• Shipping label errors: number of shipping label creation failures per SHIPPING fulfillment order.
• Support tickets related to mixed orders: volume and average response time.

Data validation

• Reconcile order and fulfillment order totals daily to detect inconsistencies in taxes, promotions or shipping charges.
• Compare inventory decrements by location against fulfillment orders to detect allocation failures.

Alerts and thresholds

• Alert on webhook retry spikes for fulfillment_orders events.
• Alert on sudden drops in fulfillment order processing throughput.
• Trigger incident response if customer checkout errors increase after a release.

Third-party considerations: carriers, fulfillment partners and marketplaces

Notify and coordinate with partners that consume order payloads.

Carriers and shipping label providers

• Confirm whether carrier integrations accept per-fulfillment-order requests. If not, create middleware to emit carrier label requests only for SHIPPING fulfillment orders.
• Confirm insurance and tracking are attached at the label level and map back to the fulfillment order ID.

Fulfillment service apps and 3PLs

• Ensure partners receive fulfillment_orders/create events and can process them independently from order-level payloads.
• For partners that can’t cope with multiple fulfillment orders, provide a transformation layer that splits the original Order into separate work items.

Marketplace partners

• For marketplaces that use your platform to route orders to sellers, update mapping logic so pickup items are routed to the seller’s pickup location rather than the marketplace shipping flow.

Example developer fixes: before and after

Before (problematic code snippet) Many apps previously used order-level logic like this:

if order.delivery_method == "PICK_UP":
    route_to_pickup(order.id, order.items)
else:
    create_shipment(order.id, order.shipping_address, order.items)

This fails because order.delivery_method may not exist or because multiple methods can exist in different fulfillment orders.

After (corrected approach) Process fulfillment orders directly:

for fulfillmentOrder in order.fulfillmentOrders:
    if fulfillmentOrder.delivery_method == "PICK_UP":
        route_to_pickup(fulfillmentOrder.id, fulfillmentOrder.line_items, fulfillmentOrder.pickup_location_id)
    else:
        create_shipment(fulfillmentOrder.id, fulfillmentOrder.line_items, order.shipping_address)

This ensures correct routing for each portion of the customer’s order.

Legal and customer-experience considerations

Terms and conditions and fulfillment promises may need adjustment when a single order includes different delivery experiences.

• Shipping and pickup promises: Clarify messaging around shipping dates vs pickup availability. Do not promise “all items will be delivered together” unless your fulfillment strategy guarantees it.
• Refund and cancellation policies: Ensure policies articulate how refunds work for partially fulfilled orders.
• Data retention and privacy: Pickup metadata (pickup location, store staff interactions) can include personally identifiable data. Confirm compliance with privacy policies and data retention rules.
• Contracts with 3PLs and carriers: Update service-level agreements to account for fulfillment-order-level processing and any fee adjustments.

FAQ

Q: Which merchants will see this feature immediately? A: Shopify Plus and Enterprise merchants can opt into the feature preview now. Shopify has opened a developer feature preview that must be enabled on a dev store for testing.

Q: Are there any new API fields to learn? A: No new fields or schema changes were introduced. The change lies in how existing fields can be combined: checkouts can return multiple deliveryGroups, orders can contain multiple fulfillmentOrders, and fulfillment orders include a delivery_method that identifies SHIPPING or PICK_UP.

Q: What must my app do differently? A: Stop assuming a single delivery method per order. Read and process fulfillment orders individually. Use fulfillment_order.id as the unit of work for routing, fulfillment, label creation, notifications, and inventory allocation.

Q: Will this affect shipping rate calculations and promotions? A: Yes. Shipping rates and promotions must be evaluated per deliveryGroup/fulfillmentOrder. Global promotions or discounts that apply to the entire order might need adjustments so they affect only eligible items.

Q: Which webhooks should I test? A: Prioritize fulfillment_orders/create and fulfillment_orders/update events, along with order and checkout update events. Ensure handlers process events per fulfillment order and include idempotency by fulfillment_order.id.

Q: What are the most common bugs to watch for? A: Common issues include attempting to fulfill the entire order at once, misrouting pickup items to carriers, failing to allocate inventory at pickup locations, and broken merchant or customer UIs that assume a single delivery option.

Q: How should merchant-facing notifications change? A: Notifications should be specific: clearly state which items are ready for pickup, which are shipping, and include pickup location and pickup codes when relevant. Avoid ambiguous language that could conflate pickup and shipped items.

Q: Where can I get more support or ask questions? A: Use Shopify’s developer forum for questions and updates and consult the feature preview testing guide available in the Shopify developer documentation.

Q: What happens if I do nothing? A: Apps that are not updated risk checkout errors, incorrect totals, failed fulfillment routing, and poor customer experiences. Merchants could see increased support tickets and lost sales.

Q: Any final best practices? A: Design all fulfillment workflows to be fulfillment-order-centric. Test extensively in the feature preview environment. Communicate proactively with merchants and partners. Monitor webhooks and fulfillment metrics closely after deployment.

---

Prepare technical teams, coordinate with operational staff, and validate every integration path. The change enables a smoother shopping experience for customers who want flexibility between delivery and pickup. It also raises the bar for apps and merchants: systems must now think in terms of multiple fulfillment orders per order and route, notify, and reconcile accordingly. Start testing now to ensure a seamless transition.