New Shipping Capabilities in Storefront API Draft

warning

This document is a draft and what it contains is not available yet in any environment, and is subject to change.

This page covers the new shipping fields and mutations available in the Storefront API — enriched shipping method data, pickup locations, updated set mutations, and session-level shipping metadata.

Get Shipping Methods

ShippingMethod

ShippingMethod is available on checkout.shippingMethods and checkout.deliveryGroups[].shippingMethods (the list of available options), and on checkout.shippingMethod and checkout.deliveryGroups[].shippingMethod (the currently selected method).

Field	Type	Description
`id`	`Int!`	Unique identifier for the shipping method
`name`	`String!`	Human-readable name shown to the customer
`price`	`MonetaryValue!`	Effective price of this shipping method
`originalPrice`	`MonetaryValue`	Pre-discount price — use to display a crossed-out original price
`selected`	`Boolean!`	Whether this method is currently selected on the checkout
`comment`	`String`	Optional commentary about the shipping method
`carrierName`	`String`	Name of the shipping carrier
`serviceCode`	`String`	Carrier service identifier
`deliveryType`	`String`	Fulfillment method — recommended values: `TO_DOOR`, `PICKUP`, `LOCKER`, `MAILBOX`, `STANDARD_SHIPMENT`
`description`	`String`	Additional details about the option
`iconUrl`	`String`	URL to the carrier's icon
`etd`	`ShippingETD`	Estimated time of delivery. At least one of `relative`, `absolute`, or `custom` is provided — `custom` takes precedence when present
`labels`	`[ShippingLabel]`	Visual indicators attached to the option (e.g. sustainability badge, signature required). Each has `type`, `displayName`, `description`, and `iconUrl`
`customerChoices`	`[CustomerChoice]`	Customer-configurable selections — `INPUT` (text entry), `CHECKBOX` (toggle), or `CHOICE` (dropdown with sub-options)
`hasLocation`	`Boolean!`	Whether this method supports selectable pickup/drop-off locations
`locations`	`[ShippingMethodLocation]`	Pre-populated pickup/drop-off locations based on the current shipping address
`selectedLocation`	`ShippingMethodLocation`	The location currently attached to this method, or `null` if none has been set

Full fragment:

fragment ShippingMethodFields on ShippingMethod {
  id
  name
  selected
  comment
  hasLocation
  carrierName
  serviceCode
  deliveryType
  description
  iconUrl
  price { value currency }
  originalPrice { value currency }
  etd {
    relative { min max units }
    absolute { from to }
    custom
  }
  labels {
    type
    displayName
    description
    iconUrl
  }
  customerChoices {
    id
    displayName
    description
    type
    default
    price { value currency }
    options { key displayName description price { value currency } }
  }
  selectedLocation {
    id
    displayName
    address { address1 city zipCode country { name } }
    latitude
    longitude
    distanceMeters
    openingHours { dayOfWeek opens closes }
    openingHoursText
    brickAndMortar
  }
  locations {
    id
    displayName
    address { address1 city zipCode country { name } }
    latitude
    longitude
    distanceMeters
    openingHours { dayOfWeek opens closes }
    openingHoursText
    brickAndMortar
  }
}

ShippingMethodLocation

Represents a physical pickup or drop-off location. Appears on ShippingMethod.locations, ShippingMethod.selectedLocation, and as the return type of getShippingMethodLocations.

Field	Type	Description
`id`	`Int!`	Unique identifier for this location
`displayName`	`String!`	Human-readable name of the location
`address`	`Address`	Physical address
`latitude`	`Float`	Geographic latitude
`longitude`	`Float`	Geographic longitude
`distanceMeters`	`Float`	Distance in meters from the shipping address to this location
`openingHours`	`[OpeningHoursEntry]`	Opening hours per day of week — each entry has `dayOfWeek`, `opens`, and `closes`
`openingHoursText`	`String`	Human-readable opening hours summary
`brickAndMortar`	`Int`	ID of a Centra brick-and-mortar store associated with this location, or `null` if none. When present, indicates the order may be fulfilled by that physical store

ShippingMethod.locations is pre-populated when shipping methods are fetched. Use getShippingMethodLocations to search at a different address, retrieve more results, or when locations came back empty. Only call it when hasLocation is true.

# Search by address
query {
  getShippingMethodLocations(
    shippingMethodId: 42
    address: { address1: "14 Downing Street", city: "London", zipCode: "SW1A 2AA", country: "GB" }
  ) {
    id
    displayName
    address { address1 city zipCode country { name } }
    openingHours { dayOfWeek opens closes }
    distanceMeters
  }
}

# Search by coordinates
query {
  getShippingMethodLocations(shippingMethodId: 42, latitude: 51.5033, longitude: -0.1276) {
    id
    displayName
    address { address1 city zipCode country { name } }
    distanceMeters
  }
}

# Default to the selection's current shipping address
query {
  getShippingMethodLocations(shippingMethodId: 42) {
    id
    displayName
    address { address1 city zipCode country { name } }
    distanceMeters
  }
}

Omitting both address and coordinates defaults to the selection's current shipping address. Providing both is an error.

ShippingETD

Estimated time of delivery. At least one field is provided. If custom is present, it takes precedence and is shown to the customer in place of any derived label from relative or absolute.

Field	Type	Description
`relative`	`ShippingETDRelative`	Range with `min`, `max`, and `units`. Valid units: `HOURS`, `DAYS`, `BUSINESS_DAYS`, `WEEKS`
`absolute`	`ShippingETDAbsolute`	Date range with `from` and `to` datetimes
`custom`	`String`	Free-form text (e.g. `"Delivered by Christmas"`)

ShippingLabel

Visual indicators attached to a shipping option — sustainability badges, signature-required notices, and similar.

Field	Type	Description
`type`	`String!`	Machine-readable label type
`displayName`	`String!`	Human-readable label name
`description`	`String`	Additional detail about the label
`iconUrl`	`String`	URL to the label's icon

CustomerChoice

Customer-configurable selections attached to a shipping method. Three interaction types are supported: INPUT (text entry), CHECKBOX (toggle), and CHOICE (dropdown with sub-options).

Field	Type	Description
`id`	`String!`	Identifier for this choice
`displayName`	`String!`	Label shown to the customer
`description`	`String`	Explanatory text
`type`	`String!`	`INPUT`, `CHECKBOX`, or `CHOICE`
`default`	`String`	Default value. For `INPUT`: shown in the input box, defaults to empty. For `CHOICE`: the option with the matching `key` is pre-selected, defaults to the first option. For `CHECKBOX`: `"1"` means checked, defaults to unchecked
`price`	`MonetaryValue`	Additional cost for selecting a non-default value
`options`	`[CustomerChoiceOption]`	Sub-options for `CHOICE` type — required when `type` is `CHOICE`

CustomerChoiceOption

Field	Type	Description
`key`	`String!`	Choice identifier
`displayName`	`String!`	Customer-facing label
`description`	`String`	Explanatory text
`price`	`MonetaryValue`	Overrides the price on the parent `CustomerChoice` if set

Set Shipping Method

setShippingMethod now accepts an optional locationId parameter. When provided, the chosen pickup or drop-off location is attached to the method in the same call. The selected location is then readable on checkout.shippingMethod.selectedLocation.

# Without a location
mutation {
  setShippingMethod(id: 12) {
    selection {
      checkout {
        shippingMethod { id name }
      }
    }
  }
}

# With a location
mutation {
  setShippingMethod(id: 12, locationId: 7) {
    selection {
      checkout {
        shippingMethod {
          id
          name
          selectedLocation {
            id
            displayName
            address { address1 city zipCode country { name } }
          }
        }
      }
    }
  }
}

When the checkout has multiple delivery groups, use setDeliveryGroupShippingMethod instead. The locationId parameter works the same way.

# Without a location
mutation {
  setDeliveryGroupShippingMethod(deliveryGroupId: 1, shippingMethodId: 12) {
    selection {
      checkout {
        deliveryGroups {
          id
          shippingMethods { id name selected }
        }
      }
    }
  }
}

# With a location
mutation {
  setDeliveryGroupShippingMethod(deliveryGroupId: 1, shippingMethodId: 12, locationId: 7) {
    selection {
      checkout {
        deliveryGroups {
          id
          shippingMethods {
            id
            name
            selected
            selectedLocation { id displayName }
          }
        }
      }
    }
  }
}

warning

Use setShippingMethod only when the selection has no delivery groups, and setDeliveryGroupShippingMethod only when it does. Using the wrong mutation for the selection's structure will result in an error.

External Provider Shipping Metadata

shippingProviderMetadata is a new field on Session — an array of entries that a shipping provider integration can attach to the session server-side. The frontend does not need to do anything to populate it; Centra stores and exposes it automatically whenever it receives metadata from the provider.

Each entry has the following fields:

Field	Type	Description
`key`	`String!`	Metadata key, defined by the provider
`value`	`String!`	Metadata value, defined by the provider
`provider`	`String!`	Identifier of the shipping provider that set this entry
`version`	`String!`	Version of the provider integration

query {
  session {
    shippingProviderMetadata {
      key
      value
      provider
      version
    }
  }
}

Keys and values are defined by the provider — Centra passes them through without interpretation. Typical contents include:

Delivery window tokens — identifiers the provider uses to track a promised delivery slot
Widget initialization data — a session token or config blob a third-party shipping widget can use to bootstrap itself on the frontend, without requiring a separate authentication step
Delivery promises — human-readable strings such as "Delivered by Tuesday"
Session correlation IDs — references the provider backend uses to look up the corresponding session on their side

This makes shippingProviderMetadata a general-purpose side-channel between the shipping provider's backend and your frontend: the provider writes to it, and the frontend reads it back from the session.

Express Checkout

note

The impact of new shipping capabilities on express checkout flows (e.g. Shop Pay, Apple Pay) is still under discussion.

Get Shipping Methods​

ShippingMethod​

ShippingMethodLocation​

ShippingETD​

ShippingLabel​

CustomerChoice​

CustomerChoiceOption​

Set Shipping Method​

External Provider Shipping Metadata​

Express Checkout​