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: