Shopify Storefront API 2026-07: New Cart Warning Flags When a Selected Delivery Option Becomes Unavailable

Table of Contents

1. Key Highlights
2. Introduction
3. What changed in 2026-07 and why it matters
4. How the CartWarning integrates with a cart’s lifecycle
5. Technical details: what to query and what to expect
6. Recommended developer workflow to handle the warning
7. Example UI flows and messaging patterns
8. Example implementation: React (Hydrogen / Next.js) pattern
9. Handling substituted options: when to accept automatic fallback
10. Edge cases and pitfalls to handle
11. Migration plan for existing storefronts
12. Real-world examples: how merchants benefit
13. Testing and monitoring strategy
14. Analytics and KPI suggestions
15. Policy and decision considerations for merchants
16. Security, privacy, and compliance considerations
17. Implementation patterns for different storefront types
18. When to block checkout: practical rules
19. Developer checklist: code-level items before rollout
20. Measuring success after deployment
21. Common implementation variations by industry
22. Long-term considerations and future-proofing
23. FAQ

Key Highlights

• The Storefront API (version 2026-07) adds a CartWarning value — DELIVERY_SELECTED_OPTION_NOT_AVAILABLE — so developers can detect when a buyer’s chosen delivery option is no longer valid and notify the buyer.
• Before this change the API silently switched to another delivery option; developers must now surface the warning, prompt for confirmation, and offer an explicit selection workflow to avoid surprises at checkout.

Introduction

Shopify’s Storefront API update for version 2026-07 changes how carts report delivery-option availability. When a buyer’s selected delivery option becomes invalid — for example after an address or cart-content change — the Cart object now emits a specific warning code: DELIVERY_SELECTED_OPTION_NOT_AVAILABLE. That signal gives storefronts a programmatic hook to inform the buyer and request a new selection rather than silently substituting a different option.

This update affects checkout UX, merchant fulfillment expectations, and how developers handle cart-state transitions. Merchants reduce surprise fees or delivery delays; developers gain a dependable way to keep buyers informed. The rest of this article explains the change, shows actionable implementation patterns, covers edge cases and testing, and provides concrete examples for integrating the new warning into production storefronts.

What changed in 2026-07 and why it matters

Previously, the Storefront API automatically switched a cart’s delivery option when it became unavailable. That implicit substitution left buyers unaware of changes to delivery method, timing, or cost. It also made it hard for merchants and developers to present accurate order summaries and for support teams to troubleshoot discrepancies between what a buyer selected and what the order ultimately used.

The 2026-07 release introduces a specific CartWarning enum value — DELIVERY_SELECTED_OPTION_NOT_AVAILABLE — surfaced on the Cart object. That warning explicitly informs client applications that the user's previously chosen delivery option is no longer valid. The warning provides an opportunity to:

• Prompt buyers to confirm or choose a new delivery option before payment.
• Present clear explanations for the change (e.g., address moved outside a carrier zone, cart item out of size limits).
• Avoid unexpected shipping charges or delivery windows at the point of payment.

Detecting the warning programmatically also makes A/B testing, analytics tracking, and merchant notifications more precise. Developers can log occurrences, measure conversion impact, and design recovery flows that minimize friction.

How the CartWarning integrates with a cart’s lifecycle

The store’s cart is a mutable object: buyers add lines, change quantities, and modify addresses. Those actions trigger re-evaluation of available delivery options. The API now fits the warning into this lifecycle:

1. Buyer selects a delivery option and continues shopping or edits address/cart contents.
2. The storefront performs whatever API requests it normally does to refresh cart state.
3. If the selection becomes invalid during re-evaluation, the Cart object’s warnings array will include an entry with code DELIVERY_SELECTED_OPTION_NOT_AVAILABLE and a human-friendly message.
4. The storefront inspects the warnings array and decides how to surface the issue to the buyer (modal, inline banner, toast, or block progression to checkout).
5. The buyer reviews available alternatives and either reselects one or confirms the substituted option if the storefront allows it.

This explicit warning is a reliable signal; do not rely on inferred behavior such as comparing selectedDeliveryOption against availableDeliveryOptions only. Use the provided warning to drive UX and business logic.

Technical details: what to query and what to expect

The CartWarning type is returned as part of the Cart object in the Storefront API. When a cart’s selected delivery option becomes unavailable, one of the CartWarning entries has the code DELIVERY_SELECTED_OPTION_NOT_AVAILABLE. Typical fields on the warning will include:

• code: the machine-readable warning key (DELIVERY_SELECTED_OPTION_NOT_AVAILABLE).
• message: a human-readable string suitable for display or for developer logging.
• maybe additional context fields: depending on the Storefront API evolution, warnings may include identifiers or references to the invalid delivery option.

To detect the condition, query the cart’s warnings field and the delivery-related fields. A minimal GraphQL query pattern looks like this:

query GetCartForDeliveryStatus($cartId: ID!) {
  cart(id: $cartId) {
    id
    selectedDeliveryOption {
      id
      title
    }
    deliveryOptions {
      id
      title
      price {
        amount
        currencyCode
      }
      forecast {
        minDay
        maxDay
      }
    }
    warnings {
      code
      message
    }
    lines(first: 10) {
      edges { node { id quantity merchandise { ... on ProductVariant { id title } } } }
    }
  }
}

When the selected option becomes unavailable, warnings will include an item similar to:

• code: DELIVERY_SELECTED_OPTION_NOT_AVAILABLE
• message: "The delivery option you selected is no longer available for the cart's current address or items."

Client applications must parse warnings[].code and compare against the DELIVERY_SELECTED_OPTION_NOT_AVAILABLE constant.

Recommended developer workflow to handle the warning

The API provides the signal. The storefront developer is responsible for the flow that follows. The recommended workflow focuses on clarity for the buyer and resilience for the cart:

1. Detect the warning: after operations that could affect delivery (address update, line change), re-fetch the cart and inspect cart.warnings.
2. Pause progression: if a checkout process is in progress (e.g., buyer clicked “Proceed to payment”), halt progression until delivery selection is resolved.
3. Surface the issue with context: show which delivery option was invalidated, why (if message provides a reason), and present current available options.
4. Provide clear choices: allow the buyer to select a new option, keep the substituted option if that is acceptable to your merchant policies, or cancel order creation.
5. Update cart and confirm: after buyer chooses, call the appropriate mutation to set or confirm the delivery option and re-fetch to ensure warnings cleared.
6. Track events: emit analytics events for conversions, step abandonment, or repeated warning occurrences to help merchant operations.

Implementing this pattern reduces last-minute surprises and gives merchants a chance to enforce rules (for example, disallowing substitution without buyer consent).

Example UI flows and messaging patterns

Consistent language and placement of the warning matter. Buyers expect clarity around delivery windows and costs. Tailor messaging by use case.

Flow A — Inline, non-blocking notification

• Display a short inline banner in the cart: “Your previously selected delivery option is no longer available for your updated address. Choose another option to proceed.”
• Show current available delivery options beneath the banner with buttons to select.
• Allow the buyer to continue browsing until they try to checkout. At checkout, verify a valid selection exists.

Flow B — Modal and blocking

• Immediately show a modal when the buyer modifies the address or cart that caused the invalidation.
• Modal contains: previous selection (grayed), reason text from warning, list of valid options with selection controls, and an explicit “Continue” button that confirms the chosen option.
• Use this for conversions where shipping choice materially affects price or tax.

Flow C — Checkout gate

• If the buyer is in the checkout flow and the warning appears, block payment forms until user re-selects a delivery option.
• Present precise estimates for price and delivery window to avoid abandonment.

Message examples (direct, customer-facing):

• “Your selected delivery method is no longer available for this address. Please choose a new option.”
• “The previously selected pickup slot is no longer valid. Select a different pickup time to complete your order.”
• “Delivery option unavailable due to item changes — select an alternative or edit your cart.”

UX patterns should avoid technical jargon. Use the API’s message for internal logging but display simplified consumer-facing text.

Example implementation: React (Hydrogen / Next.js) pattern

Below is a conceptual React hook and component pattern. This example focuses on detecting the warning and presenting a modal for choice. The mutation to set delivery options depends on your storefront architecture and the exact Storefront API mutation names; adapt accordingly.

Hook (conceptual):

import { useState, useEffect } from 'react';

export function useCartDeliveryMonitor(cartId, fetchCart) {
  const [warning, setWarning] = useState(null);
  const [cart, setCart] = useState(null);

  async function refresh() {
    const data = await fetchCart(cartId);
    setCart(data.cart);
    const warn = (data.cart.warnings || []).find(w => w.code === 'DELIVERY_SELECTED_OPTION_NOT_AVAILABLE');
    setWarning(warn || null);
  }

  useEffect(() => {
    refresh();
  }, [cartId]);

  return { cart, warning, refresh };
}

Component (conceptual):

function DeliveryWarningModal({ cart, warning, onClose, onSelectOption }) {
  if (!warning) return null;
  const options = cart.deliveryOptions || [];
  return (
    <Modal onClose={onClose} title="Delivery option changed">
      <p>{warning.message || 'Your selected delivery option is no longer available.'}</p>
      <div>
        {options.map(opt => (
          <div key={opt.id}>
            <label>
              <input type="radio" name="delivery" value={opt.id} onChange={() => onSelectOption(opt.id)} />
              {opt.title} — {opt.price?.amount} {opt.price?.currencyCode}
            </label>
          </div>
        ))}
      </div>
      <button onClick={onClose}>Continue without change</button>
    </Modal>
  );
}

Server-side or mutation handling will call the appropriate Storefront API mutation to update the cart’s selected delivery option, then re-fetch the cart.

Handling substituted options: when to accept automatic fallback

The API historically substituted another available delivery option when the selected one became invalid. The new warning does not prevent a substitution; it introduces visibility. Merchants must choose policies:

• Require explicit buyer confirmation: Never accept a substituted option without buyer consent. Block checkout until buyer selects.
• Allow silent substitution but notify: If substitutions are minor (e.g., switching from one courier to another with same cost), allow substitution and show a non-blocking notice.
• Permit substitution for specific SKUs or low-cost items: Use business logic on the backend to decide when silent substitution is acceptable.

Make the policy explicit in your storefront UI and merchant settings. Customers respond better when expectations are clear; unexpected changes at payment cause support friction.

Edge cases and pitfalls to handle

1. Race conditions: Simultaneous cart updates from multiple devices can trigger warnings. Use last-write-wins patterns for cart updates and ensure your client re-fetches cart after any mutate operation.
2. Partial availability: A delivery option might be available for some cart lines but not others. Present per-line or per-item details if your fulfillment model requires it.
3. International shipping zones: Address changes that cross fulfillment zones will often invalidate previously valid options. Validate address input early to prevent downstream invalidations.
4. Payment token timing: If a payment method was created when a different delivery option was selected, changing the delivery option later may affect payment totals and require creating a new payment intent. Handle re-authentication flows accordingly.
5. Offline or slow connections: If you can’t re-fetch cart warnings due to connectivity, show an explicit “Cannot validate delivery option — please check your connection” message and block checkout if your policy requires confirmed delivery selection.

Anticipate these conditions during QA and load testing.

Migration plan for existing storefronts

Most storefronts will need to update only the client-side logic that handles cart re-evaluation and checkout gating. Follow this migration checklist:

• Re-run integration/acceptance tests that touch address changes, line changes, and checkout flows.
• Add warnings parsing in the cart refresh logic.
• Add UI for the warning: modal, banner, or checkout gate as per business policy.
• Add analytics events for when the warning appears and the buyer's resolution (accepted substitution, selected new option, canceled order).
• Monitor the frequency of DELIVERY_SELECTED_OPTION_NOT_AVAILABLE occurrences in production for the first weeks after deployment.
• Train customer-support staff: provide scripts and documentation explaining why a delivery option was invalidated and how agents can resolve.

The change is backward-compatible for stores that ignore the warnings, but doing so reintroduces the silent-substitution behavior the update sought to address.

Real-world examples: how merchants benefit

Example 1 — Grocery delivery with time windows A regional grocery chain offers narrow time windows for same-day delivery. A buyer selects a 6–7pm slot and, while shopping, adds bulky items that push the order beyond driver capacity for that slot. Previously the platform might substitute a later slot and the buyer would notice only at order confirmation. With the new warning, the storefront immediately informs the buyer the chosen slot is no longer available and prompts to pick another. Merchants reduce complaints about missed delivery windows and lower the need for compensation or redelivery.

Example 2 — Marketplace with multiple carriers A marketplace sells fragile items fulfilled by multiple carriers. An address update moves the order to a carrier service area with higher fragility constraints. The selected "standard fragile" option becomes invalid; the platform offers an alternate option (insured fragile with different price). Notifying the buyer prevents disputes and ensures the merchant receives consent for higher shipping costs.

Example 3 — Click-and-collect (store pickup) A buyer selects pickup at Store A. After adding items, one item becomes out-of-stock at Store A but available at Store B. The store pickup option for Store A becomes invalid. The storefront uses the warning to present options: pickup at Store B, waitlist, or remove the item. This flow reduces canceled pickups and optimizes inventory allocation.

These examples show practical reductions in support overhead and improved buyer trust.

Testing and monitoring strategy

Comprehensive testing and monitoring are essential for a reliable rollout.

Testing

• Unit tests: parse a variety of warnings payloads including DELIVERY_SELECTED_OPTION_NOT_AVAILABLE, null/empty warnings, and multiple warnings.
• Integration tests: simulate address changes, quantity changes, and cart merges to ensure warning surfaces and UX responds correctly.
• E2E tests: run full checkout scenarios where warnings are triggered and verify the buyer flow leads to a valid selection before payment.
• Load tests: ensure re-fetching carts and resolving warnings under high concurrency does not increase latency significantly.

Monitoring

• Log occurrences of DELIVERY_SELECTED_OPTION_NOT_AVAILABLE with contextual metadata (cartId, userId, event type: address-change/line-change).
• Track conversion rates for carts with warnings vs without. A spike in abandonment suggests UX friction.
• Track resolution times: average time between warning appearance and buyer selecting a new option.
• Use alerts for unusual patterns — e.g., a sudden global increase in the warning may indicate a carrier or pricing service outage.

Collect numbers for merchant teams to evaluate whether inventory updates, carrier configurations, or address-validation steps should be improved.

Analytics and KPI suggestions

Key metrics to monitor post-deployment:

• Warning incidence rate: warnings per 1,000 cart updates.
• Resolution rate: percentage of warnings resolved by buyer selection vs carts abandoned.
• Time-to-resolution: median seconds/minutes from warning to user selection.
• Revenue impact: average order value comparison pre- and post-warning.
• Support load: ticket volume related to shipping discrepancies.

These KPIs help determine whether to tighten address validation, adjust delivery-option computation timing, or change UX presentation.

Policy and decision considerations for merchants

Adopt clear rules about substitution. Consider the following when defining merchant policy:

• Price-sensitive substitution: For orders where substitution changes the total by more than a threshold (e.g., $5 or 5% of cart value), require explicit buyer consent before finalizing payment.
• Per-product rules: For restricted items (e.g., hazardous goods, regulated items), block substitution and require a new selection.
• Time-sensitive orders: For scheduled deliveries with per-minute windows, prioritize blocking substitution and require buyer confirmation.
• Exceptions: Define scenarios where substitutions are permitted silently (e.g., same-day switching between equivalent-local carriers at same price).

Publish these rules for customer-facing policies and ensure customer support has scripts aligned to them.

Security, privacy, and compliance considerations

Handling delivery validations and warnings usually involves personal data (addresses). Follow standard security and privacy guidance:

• Minimize logging of full addresses in analytics; log hash or region codes instead.
• Use HTTPS and token-based authentication for API calls.
• Avoid returning internal error details to the buyer. Show human-friendly messages while logging technical context.
• If merchant policy requires consent to a price increase, ensure consent events are auditable and tied to the buyer’s session or account.

If your compliance requirements involve storing proof of buyer consent for changes in price or shipping method, capture that consent using server-side records with timestamps and cart snapshots.

Implementation patterns for different storefront types

Headless storefront (Hydrogen, Next.js, custom SPA)

• Integrate detection at cart refresh points and during checkout transition.
• Use a modal or inline banner pattern with camera focus management to ensure accessibility.
• Block the checkout button if the warning is present and your policy requires explicit selection.

Server-rendered storefronts

• Server-render responses for cart pages to include warnings so a fresh page load will surface the issue.
• For near-real-time detection when the buyer edits the cart via forms or JavaScript, still use an async fetch to revalidate the cart and show server-side messages to the buyer.

Progressive enhancement

• If JavaScript is disabled, include a server-side check before showing payment forms and deliver a server-rendered banner or redirect to the cart page with a highlighted message.

Mobile apps

• Implement cart-refresh on lifecycle events (app foreground, cart edit) and surface native dialogs or screens.
• For push notifications triggered by merchant services (e.g., fulfillment services), ensure the app validates cart state on open.

When to block checkout: practical rules

Blocking checkout must balance conversion with correctness. The following rules are pragmatic starting points:

• Block when the warning is present and the substitution affects price, delivery window, or pickup location.
• Do not block when substitution is strictly cosmetic (internal carrier change with identical price and window) and the buyer has an explicit merchant policy indicating such substitutions are permitted.
• If unsure, favor blocking and prompt for selection. Conversion loss from a brief modal is preferable to chargebacks or refunds from unexpected shipping changes.

Test both blocking and non-blocking flows with A/B tests to measure behavioral differences for your customer base.

Developer checklist: code-level items before rollout

• Add parsing for cart.warnings and check for DELIVERY_SELECTED_OPTION_NOT_AVAILABLE.
• Add UI component(s) for notifying and prompting buyer choices.
• Add API integration to set selected delivery option and re-fetch cart.
• Ensure analytics events are recorded for warning emission and resolution.
• Add automated tests for warning scenarios.
• Add server-side logging with context but no full PII in analytics.
• Confirm mobile and server-rendered flows handle the warning consistently.
• Validate payment flows for re-calculation when delivery selection changes.

Completing this checklist ensures smooth deployment and consistent buyer experiences.

Measuring success after deployment

Expect an initial increase in visible shipping-choice interactions as buyers are asked to confirm selection. Success indicators include:

• Decrease in post-order shipping disputes or refunds that stem from incorrect expectation of delivery method.
• Reduction in support tickets referencing “my shipping changed” and increased first-contact resolution from CS teams.
• Stable or slightly lower abandonment rates if the UX is designed with minimal friction. If abandonment increases substantially, refine messaging or consider different gating policies.
• Decrease in merchant manual interventions related to delivery mismatches.

Collect qualitative feedback from support channels and directly from buyers where possible. Use the data to tighten or relax policies.

Common implementation variations by industry

• Grocery and meal kit companies: prefer blocking with explicit confirmation due to narrow delivery windows.
• Fashion and marketplace sellers: may allow substitution for carrier differences but block if substitution impacts delivery speed or insurance.
• High-value electronics: require explicit consent for substitution because of insurance and value-related policies.
• Global sellers: emphasize clear address validation to reduce zone-related invalidations.

Tailor the default behavior to your vertical requirements; the new warning supports flexible policy enforcement.

Long-term considerations and future-proofing

The introduction of explicit warning codes opens possibilities for richer server-side logic and richer buyer interactions. Consider these longer-term improvements:

• Persistent delivery preferences: remember buyer delivery preferences and present fallbacks to reduce friction when warnings occur repeatedly.
• Predictive validation: validate addresses and heavy-line items earlier in the flow to reduce invalidation surprises.
• Automated recovery workflows: for returning customers, offer quick-reselect options or saved alternate delivery methods.
• Analytics-driven adaptation: use warning incidence and resolution analytics to optimize delivery-option generation logic and partner carrier choices.

Design code and UX with hooks to add richer contextual data to warnings later, such as expected replacement options or probability scores for each delivery alternative.

FAQ

Q: What exactly triggers DELIVERY_SELECTED_OPTION_NOT_AVAILABLE? A: The warning appears when a cart’s previously chosen delivery option becomes invalid as a result of changes to the cart’s address, contents, or other conditions evaluated by delivery-option logic. Examples include address moving outside a carrier zone, an item causing the option to exceed carrier size or weight limits, or a pickup location becoming unavailable.

Q: Does the warning prevent the API from substituting another delivery option? A: Not necessarily. The warning signals the invalidation; whether the system substitutes another option or blocks checkout depends on storefront policies and how the developer handles the warning. Merchants can require explicit buyer confirmation or accept a substitution with notification.

Q: How should I surface the warning in my storefront? A: Surface it where it causes least surprise and greatest clarity: the cart page, the checkout gate, or a modal triggered immediately after the action that caused the change (address change or quantity update). Use concise language, show previously selected option and available alternatives, and make the required action clear.

Q: Will ignoring the warning revert my storefront to the previous silent behavior? A: If you do not inspect or act on the warning, the backend may continue to substitute a valid delivery option as before. However, ignoring the warning loses the opportunity to notify the buyer and could recreate the prior issues of surprise changes at order confirmation.

Q: Are there additional fields in CartWarning to help explain why the option was invalid? A: The standard warning includes a code and a message intended for logging or display. Depending on Storefront API evolution, warnings may include contextual fields. Design your UI to use the message for display and to fall back to generic text if detailed context is not present.

Q: How should I handle payment sessions that were created under a prior delivery option? A: Changing the delivery option may affect the payment amount. Ensure your payment integration supports recalculation and re-authentication where required. For card authorizations, obtain a fresh authorization after the final order totals are confirmed.

Q: Should I block checkout every time the warning appears? A: Not necessarily. Block when substitutions materially affect price, delivery window, or pickup location, or if your merchant policy requires explicit consent. For benign substitutions with no cost or window changes, a non-blocking notification may suffice.

Q: What analytics should I instrument? A: At minimum log: (1) the warning emission event with cartId and context, (2) the buyer’s resolution action (selected new option / accepted substitution / abandoned), and (3) conversion outcome. Track incidence and resolution rates over time.

Q: How should customer support handle queries about this warning? A: Provide CS with scripts explaining that a delivery option became unavailable due to address or cart changes. If policy requires consent for substitutions, instruct CS to offer a refund or reschedule. Give CS access to cart snapshots (without exposing PII unnecessarily) to verify what changed.

Q: Is this warning available in Storefront API versions prior to 2026-07? A: No. The DELIVERY_SELECTED_OPTION_NOT_AVAILABLE warning is introduced in Storefront API version 2026-07. Older versions lack this explicit code and may silently substitute another delivery option.

Q: Can merchant apps or backend services trigger resolution automatically? A: Merchant backend services can decide to programmatically set a replacement option when appropriate. However, for buyer consent and auditing, surface the choice to the buyer if the change affects cost or delivery timeframe unless your policy explicitly allows silent substitution.

Q: How do I handle multi-item carts where the selected option is invalid for only part of the cart? A: Surface item-level details where feasible. Offer granular choices such as splitting shipment, removing affected items, or selecting an alternate delivery method that covers all items. Ensure the UI explains the trade-offs clearly.

Q: Will this affect headless storefronts differently than traditional themes? A: The signal is the same across storefront types. Headless storefronts often already re-fetch cart state on client operations and can quickly integrate warning detection. Server-rendered themes should ensure server-side cart validation occurs before finalizing checkout and may need to add additional client-side checks for real-time UX.

Q: Are there performance considerations to keep in mind? A: Re-fetching cart state more frequently after edits adds API calls. Implement batching and debounce updates where appropriate. Monitor latencies and avoid blocking UI unnecessarily; provide optimistic UX while confirming the cart state.

Q: Where should I start implementing this change? A: Add warnings parsing to the cart refresh logic, implement a minimal UI to surface DELIVERY_SELECTED_OPTION_NOT_AVAILABLE, and run integration tests covering address and item changes. Then expand to analytics, support training, and policy enforcement.

---

This update gives storefronts a clear and reliable signal about delivery-option invalidation. Properly surfaced and handled, it reduces buyer confusion, lowers support overhead, and improves order accuracy. Merchants and developers should adopt detection, clear UX, and logging as part of their checkout lifecycle to realize those benefits.