Executive summary
- On API version 2026-10, Shopify Functions can read metafields attached to delivery options via a new metafield field on CartDeliveryOption.
- It replaces a fragile pattern where shipping logic was encoded into option titles or handles and parsed back out downstream, which broke whenever an option was renamed or translated.
- Relevant to anyone building or commissioning Delivery Customization Functions, and to merchants running carrier-driven or rules-heavy shipping at checkout.
What changed
CartDeliveryOption now exposes a metafield field that accepts a namespace and key and returns a Metafield with value, type and jsonValue. Because CartDeliveryOption is shared across the Functions cart graph, the field is available to every Functions API whose input includes cart.deliveryGroups.deliveryOptions. Functions that do not query it see no behavioral change at all.
Two constraints matter. First, these metafields are not persisted after checkout. A delivery option generator function or a carrier service response attaches them at the moment the option is created, and they exist only for that checkout session. Second, access follows the existing ownership rules: a function can read metafields in its own app-reserved namespace and in any unprefixed shared namespace, while a namespace reserved by a different app resolves to null. In the legacy Order Discounts and Product Discounts APIs, cart.deliveryGroups is always empty, so the field appears in the schema but never returns a value.
Why it matters
The workaround this replaces was genuinely brittle. If a generator function wanted to tell a downstream customization function that a rate was expedited, or came from a specific carrier contract, the only reliable channel was the option title or handle. Downstream logic then pattern-matched on a string that changes when a merchant renames an option, when the storefront is localized, or when two options match the same pattern. Failures were silent and surfaced as wrong shipping rates at checkout, which is an expensive place to be wrong.
A typed metafield gives the two functions an explicit contract: the generating function writes a typed value into a namespace it owns, and the customizing function reads it by name. For merchants running complex fulfillment rules, this is the difference between shipping logic you can reason about and shipping logic you test by hoping. If you are already investing in Shopify checkout extensibility, this closes a real gap in the delivery half of that stack.
Role-specific impact
- Marketers: No direct change, but shipping promotions that depend on identifying a specific rate type become more reliable, and localized markets stop breaking rate logic that was keyed to English option names.
- Developers: Update function input queries to API version 2026-10 and request metafield on CartDeliveryOption. No action is required to keep existing functions working; every released version continues to behave as before.
- Store admins: You can rename delivery options in settings without worrying that a rename will quietly change how a customization function behaves, provided your developers have migrated off title parsing.
Use-case example
Real-world scenario
A distributor offers same-day delivery in three metros through a regional carrier and standard ground everywhere else. A generator function creates the same-day options and a customization function hides them for orders containing hazardous items. The customization function previously identified same-day rates by checking whether the option title contained "Same Day". After the merchant launched a French storefront, the localized title no longer matched, hazardous orders received same-day options, and roughly 40 orders over two weeks were routed to a carrier that could not legally accept them. Tagging the option with a typed metafield at generation time makes that class of failure structurally impossible.
Implementation checklist
- Identify any Delivery Customization Function in your stack that parses option titles or handles to make decisions.
- Move those functions to API version 2026-10 in your function configuration.
- Define a metafield contract between the generating and customizing functions, using an app-reserved namespace where the data is private to one app.
- Update the generator function or carrier service response to attach the typed metafield when it creates each option.
- Update the input query to request metafield(namespace:, key:) on deliveryOptions and handle null returns explicitly.
- Test with a localized storefront and with renamed delivery options to confirm the old string-matching failure modes are gone.
FAQ
Q: Do we need to do anything if we already have delivery customization functions in production?
A: No. Existing functions continue to work unchanged on every released API version. This is an additive field, and adoption is entirely optional.
Q: Can we read these metafields after the order is placed, for reporting or ERP sync?
A: No. Delivery option metafields are not persisted past checkout. If you need the value downstream, copy it onto a resource that does persist, such as the order, during checkout processing.
Resources
Delivery Customization Function API reference
Need guidance? Talk to Makro.