Skip to main content
Back to Developer changelog

Tags:

  • Admin GraphQL API
  • 2026-07

Market-driven shipping Admin API

Starting in API version 2026-07, the GraphQL Admin API supports market-driven shipping configuration. You can now configure shipping directly on a market, which helps apps support different shipping strategies for different markets without creating a separate shipping profile resource.

What changed

The Market object now includes a delivery field for market delivery settings. Use Market.delivery.shipping to read the shipping configuration for a market.

Use the existing marketCreate and marketUpdate mutations to create, update, or remove a market's shipping configuration:

  • Use MarketCreateInput.delivery.shipping to add shipping configuration when creating a market.
  • Use MarketUpdateInput.delivery.shipping to update shipping configuration on an existing market.
  • Use MarketUpdateInput.delivery.removeShipping to remove a market-level shipping configuration so the market inherits shipping from its parent.

Shipping options are managed through DeliveryOptionDefinitionCreateInput and DeliveryOptionDefinitionUpdateInput. The API supports these option types:

  • DeliveryFlatRateOptionDefinition for fixed-price shipping options.
  • DeliveryValueBasedOptionDefinition for rates based on cart value.
  • DeliveryWeightBasedOptionDefinition for rates based on package weight.
  • DeliveryCarrierCalculatedOptionDefinition for rates calculated by carrier services.

Each shipping option includes fields such as currency and isActive. You can optionally configure a free delivery threshold with freeDeliveryMinimumValue. Flat and value-based options can include one or more rate groups. Weight-based options include exactly one weight-based rate group, and carrier-calculated options include a single carrier-calculated rate group.

What you can do

  • Configure shipping options for a specific market.
  • Offer different flat, value-based, weight-based, or carrier-calculated rates by market.
  • Restrict rate groups to specific product collections or origin locations.
  • Unconfigured markets naturally inherit shipping from their parents.
  • Disable shipping for a market by setting isEnabled to false.

What you need to know

  • Queries require read_markets access.
  • Mutations require both read_markets and write_markets access.
  • A null value for Market.delivery.shipping means the market inherits shipping from its parent. For markets without a parent, shipping inherits the shop default of no shipping
  • isEnabled: false means customers in that market will not see shipping options at checkout. This also disables any app managed shipping options that may otherwise apply to this market.
  • There are no root queries or standalone mutations for market shipping configuration. Read and write shipping configuration through Market, marketCreate, and marketUpdate.

Example query

This query reads a market's shipping configuration, including whether shipping is enabled, how many active shipping options are configured, and the details for each flat-rate option.

{
market(id: "gid://shopify/Market/123") {
delivery {
shipping {
isEnabled
activeOptionDefinitionsCount {
count
}
optionDefinitions(first: 10) {
nodes {
__typename
currency
isActive
freeDeliveryMinimumValue {
amount
currencyCode
}
... on DeliveryFlatRateOptionDefinition {
name
rateGroups(first: 10) {
nodes {
conditions {
collectionsCount {
count
}
originLocationsCount {
count
}
}
rate {
price {
amount
currencyCode
}
transitTimeMinSeconds
transitTimeMaxSeconds
}
}
}
}
}
}
}
}
}
}

Example mutation

This mutation updates an existing market with shipping enabled and adds a standard flat-rate shipping option with a fixed price and estimated transit time.

mutation {
marketUpdate(
id: "gid://shopify/Market/123"
input: {
delivery: {
shipping: {
isEnabled: true
optionDefinitionsToCreate: [
{
flatRate: {
name: "Standard Delivery"
currency: USD
rateGroups: [
{
rate: {
price: { amount: "5.99", currencyCode: USD }
transitTimeMinSeconds: 432000
transitTimeMaxSeconds: 604800
}
}
]
}
}
]
}
}
}
) {
market {
id
delivery {
shipping {
isEnabled
optionDefinitions(first: 10) {
nodes {
__typename
currency
isActive
}
}
}
}
}
userErrors {
field
message
}
}
}

Example: Disable shipping for a market

Use isEnabled: false when the market should keep its market-level shipping configuration, but not show shipping options at checkout.

mutation {
marketUpdate(
id: "gid://shopify/Market/123"
input: {
delivery: {
shipping: {
isEnabled: false
}
}
}
) {
market {
id
delivery {
shipping {
isEnabled
}
}
}
userErrors {
field
message
}
}
}

Example: Remove market-level shipping configuration

Use removeShipping: true when the market should inherit shipping from its parent instead of using its own shipping configuration.

mutation {
marketUpdate(
id: "gid://shopify/Market/123"
input: {
delivery: {
removeShipping: true
}
}
) {
market {
id
delivery {
shipping {
isEnabled
}
}
}
userErrors {
field
message
}
}
}

Example: Add a value-based shipping option

This mutation creates a shipping option where the rate depends on cart value.

mutation {
marketUpdate(
id: "gid://shopify/Market/123"
input: {
delivery: {
shipping: {
optionDefinitionsToCreate: [
{
valueBased: {
name: "Cart Value Shipping"
currency: USD
isActive: true
rateGroups: [
{
rates: [
{
price: { amount: "9.99", currencyCode: USD }
minValue: { amount: "0.00", currencyCode: USD }
maxValue: { amount: "49.99", currencyCode: USD }
}
{
price: { amount: "0.00", currencyCode: USD }
minValue: { amount: "50.00", currencyCode: USD }
}
]
}
]
}
}
]
}
}
}
) {
market {
id
}
userErrors {
field
message
}
}
}

Example: Add a weight-based shipping option

Weight-based options uses a similar form but can only take a single rate group. The rate group can contain weight-based rates.

mutation {
marketUpdate(
id: "gid://shopify/Market/123"
input: {
delivery: {
shipping: {
optionDefinitionsToCreate: [
{
weightBased: {
name: "Weight-Based Shipping"
currency: USD
isActive: true
rateGroups: [
{
rates: [
{
price: { amount: "12.99", currencyCode: USD }
minWeight: { value: 0, unit: POUNDS }
}
]
}
]
}
}
]
}
}
}
) {
market {
id
}
userErrors {
field
message
}
}
}

Example: Add a carrier-calculated shipping option

Carrier-calculated options also takes only a single rate group that references an existing carrier service.

mutation {
marketUpdate(
id: "gid://shopify/Market/123"
input: {
delivery: {
shipping: {
optionDefinitionsToCreate: [
{
carrierCalculated: {
currency: USD
isActive: true
rateGroups: [
{
carrierServiceId: "gid://shopify/DeliveryCarrierService/987"
autoIncludeNewServices: true
percentageAdjustment: 10
}
]
}
]
}
}
}
) {
market {
id
}
userErrors {
field
message
}
}
}

Example: Update an existing flat-rate shipping option

Use optionDefinitionsToUpdate with the option ID. For flat-rate options, you can also update individual rate groups.

mutation {
marketUpdate(
id: "gid://shopify/Market/123"
input: {
delivery: {
shipping: {
optionDefinitionsToUpdate: [
{
flatRate: {
id: "gid://shopify/DeliveryFlatRateOptionDefinition/456"
name: "Standard Delivery"
isActive: true
rateGroupsToUpdate: [
{
id: "gid://shopify/DeliveryFlatRateGroup/789"
rate: {
price: { amount: "6.99", currencyCode: USD }
transitTimeMinSeconds: 432000
transitTimeMaxSeconds: 604800
}
}
]
}
}
]
}
}
}
) {
market {
id
}
userErrors {
field
message
}
}
}

Example: Delete a shipping option

Use optionDefinitionsToDelete with the shipping option ID.

mutation {
marketUpdate(
id: "gid://shopify/Market/123"
input: {
delivery: {
shipping: {
optionDefinitionsToDelete: [
"gid://shopify/DeliveryFlatRateOptionDefinition/456"
]
}
}
}
) {
market {
id
}
userErrors {
field
message
}
}
}

Related docs

Core objects and interfaces:

Rate groups, rates, and conditions:

Mutations and inputs:

Was this section helpful?