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:

• Market
• MarketDeliveryConfigurations
• ShippingConfiguration
• DeliveryOptionDefinition
• DeliveryFlatRateOptionDefinition
• DeliveryValueBasedOptionDefinition
• DeliveryWeightBasedOptionDefinition
• DeliveryCarrierCalculatedOptionDefinition

Rate groups, rates, and conditions:

• DeliveryOptionDefinitionRateGroup
• DeliveryFlatRateGroup
• DeliveryValueBasedRateGroup
• DeliveryWeightBasedRateGroup
• DeliveryCarrierCalculatedRateGroup
• DeliveryRate
• DeliveryRateGroupConditions

Mutations and inputs:

• marketCreate
• marketUpdate
• MarketCreateInput
• MarketUpdateInput
• MarketDeliveryConfigurationsCreateInput
• MarketDeliveryConfigurationsUpdateInput
• ShippingConfigurationCreateInput
• ShippingConfigurationUpdateInput
• DeliveryOptionDefinitionCreateInput
• DeliveryOptionDefinitionUpdateInput