Skip to content

Shopify Dude Fix

Shopify Delivery Customization Parses Shipping Titles? Read Delivery Option Metafields Instead

Shopify Functions 2026-10 lets delivery customizations read metafields on generated shipping options. Replace fragile title parsing and test namespace access and null values.

Quick answer: On Shopify Functions API 2026-10, a Delivery Customization Function can read a delivery option’s metafield(namespace:, key:) instead of trying to decode business rules from a shipping-rate title. The value must be attached by the delivery option generator or carrier service that produced the option. It is checkout-scoped, may be null, and is not persisted to the order after checkout.
On this page

Shipping titles were never a reliable data contract

A common integration pattern is to hide, rename, or reorder a shipping option according to a piece of metadata supplied by the rate provider. Before the new field, a developer might embed a code such as priority=express into a rate title or handle and parse it in a second function. That can fail as soon as the merchant renames the service, a carrier changes its labels, or the checkout is localized.

Shopify’s September 15, 2026 update provides a cleaner boundary. The Functions cart graph now exposes CartDeliveryOption.metafield on API 2026-10. A generating service can attach structured data to an option, and a downstream customization can request it by namespace and key.

Read the metadata in the function input query

Here is the input selection documented by Shopify. Use it in the GraphQL input query for a Delivery Customization Function targeting the 2026-10 Functions API.

{
  cart {
    deliveryGroups {
      deliveryOptions {
        handle
        ownNamespace: metafield(
          namespace: "$app:carrier"
          key: "priority"
        ) {
          value
          type
          jsonValue
        }
        shared: metafield(
          namespace: "carrier"
          key: "priority"
        ) {
          value
        }
      }
    }
  }
}

The ownNamespace and shared aliases are examples of two lookup strategies, not two fields Shopify creates automatically. Metafield exposes value, type, and jsonValue. In your function logic, check for a missing value before applying a rule.

Where the option metafield comes from

This is not a product metafield or a general shipping-profile metafield. Shopify says a delivery option generator function or a shipping carrier service response attaches it when producing the option. The data belongs to that option for the current checkout and is not persisted after checkout.

If your store has ordinary flat shipping rates and no generating integration attaches a priority metafield, the example query can legitimately return null. Do not create a product metafield with the same key and expect it to appear here. First establish a contract between the rate generator and the customization function.

Choose a namespace both sides can access

Shopify enforces metafield ownership. A Function can read its own app-reserved namespace and shared unprefixed namespaces, but a namespace reserved by another app resolves to null. If the generator and customization belong to the same app, an app-reserved namespace can be appropriate. If separate apps need to exchange the data, agree on a shared namespace and document the value format.

Do not rely on an internal namespace that another vendor’s function cannot access. Treat null as a normal compatibility state, not automatically as a missing-rate bug. The generating service might have produced the rate without metadata, or the consumer might lack access to that namespace.

Use metadata to decide, handles to operate

The delivery customization API can hide, rename, and move delivery options. It does not create a new carrier rate or guarantee a rate is offered in a shipping zone. Your function reads the metadata to decide what to do, then uses the option handle in the appropriate operation. This is different from parsing the handle itself to infer business intent.

For example, an option with carrier.priority = overnight might be moved above other eligible options when the rule allows it. But don’t promise that the option will become the default selection: Shopify documents selection-order constraints, including the cheapest shipping option being selected first. Your test must inspect actual checkout behavior.

If a rate is completely absent, start with shipping profiles, zones, and the carrier service configuration. A Delivery Customization Function cannot transform a missing rate into an available one. For the separate 2026-10 carrier registration change, see why an active carrier service may have no checkout rate.

Design a safe fallback

A production rule should explicitly decide what happens when metadata is absent or malformed. For non-critical presentation rules, leaving the option unchanged is often safer than hiding it. For restrictions that must be enforced, use a supported backend rule with complete inputs and test every delivery group; do not make the only eligible shipping method disappear because a string could not be parsed.

An order can have multiple delivery groups. Iterate all groups and options rather than assuming the first option in the first group represents the entire checkout. Also remember that the option metafield does not survive as order metadata. If fulfillment needs a persistent instruction, design a separate supported order-level data flow rather than reading it later from this transient field.

Common misunderstanding: “I added carrier.priority to a product, so my delivery function can read it from the shipping option.” The field is attached to the generated delivery option, not copied from arbitrary product metafields. It is ephemeral, and access to app-reserved namespaces is restricted.

How to test this

  1. Use a development checkout with a generator or carrier integration that deliberately attaches a known delivery-option metafield.
  2. Confirm the function targets API 2026-10 and its input query requests the correct namespace and key.
  3. Test two options with different metadata values; inspect the input and confirm the correct value is associated with each option handle.
  4. Test an option without the metafield and verify the function leaves it in a safe, documented state.
  5. Test a namespace reserved by another app and confirm the expected null result is handled rather than treated as a string.
  6. Rename or localize the visible shipping title and verify the rule still uses the metadata, not the title text.
  7. Test a cart with multiple delivery groups, including pickup and shipping when supported, and confirm the rule evaluates each group.
  8. Complete a test checkout and verify that no downstream system assumes the option metafield was persisted to the order.