Starting with API version 2026-07, the Market object gains delivery.shipping was added. You can now configure shipping rates and delivery methods per market via GraphQL, without creating a separate shipping profile.
Market.delivery.shipping) ). Apps can implement per-market shipping without adding more profiles.
When you wanted to serve different shipping per market, you created an independent shipping profile. Resources ended up scattered, making app management more complex.
Market.delivery.shipping read and write.marketCreate/marketUpdate handled entirely with existing mutations.
Market marketCreate marketUpdate .
Shipping options are DeliveryOptionDefinitionCreateInput / DeliveryOptionDefinitionUpdateInput Managed here. The API supports these four types.
DeliveryFlatRateOptionDefinitionDeliveryValueBasedOptionDefinitionDeliveryWeightBasedOptionDefinitionDeliveryCarrierCalculatedOptionDefinitioncurrency and a isActive and can optionally set a freeDeliveryMinimumValue(the minimum amount that qualifies for free shipping). A rate group can be limited to specific product collections or origin locations via conditionspossible.Expresses "don't set", "set but don't show", and "revert to inheriting from the parent" as three separate fields. Don't confuse them.
| State | Setting | How customers see it |
|---|---|---|
| Unset = inherit from parent | Market.delivery.shipping is null |
Inherit Inherits the parent market's shipping. A market with no parent inherits the shop default (= no shipping) |
| Keep the setting but stop showing it | shipping.isEnabled: false |
Hidden Don't present shipping options at checkout. App-managed shipping is disabled at the same time |
| Delete the market-specific setting | delivery.removeShipping: true |
Revert to inheriting Discard your own setting and return to inheriting shipping from the parent |
isEnabled: false and removeShipping: true are different. The formerkeeps the setting but only stops displaying it, the latterdeletes the setting itself and reverts to inheriting. Use "temporarily not selling" versus "remove this market's custom rules" accordingly.| What you want to do | Input fields to use |
|---|---|
| A market's delivery settingsRead | Market.delivery.shipping(isEnabled / activeOptionDefinitionsCount / optionDefinitions) |
| Delivery at creation timeAdd | MarketCreateInput.delivery.shipping |
| An existing market's deliveryUpdate | MarketUpdateInput.delivery.shipping |
| Per-market deliveryDelete (revert to inherited) | MarketUpdateInput.delivery.removeShipping |
| An optionCreate | shipping.optionDefinitionsToCreate(flatRate / valueBased / weightBased / carrierCalculated) |
| An optionUpdate | optionDefinitionsToUpdate(by id; flat can be updated individually via rateGroupsToUpdate) |
| An optionDelete | optionDefinitionsToDelete(an array of option IDs) |
carrierServiceId/autoIncludeNewServices/percentageAdjustment).read_markets is required.
read_markets and write_markets ofbothare required.
You can attach delivery directly to a Market without creating a separate resource (shipping profile). Apps can implement different delivery strategies for different markets with fewer resources.
There is no root query or standalone mutation for market delivery. You always Market / marketCreate / marketUpdate access it via, by design.
shipping When null is not "unset" butinherited from the parent. If there's no parent, it inherits the shop default (no shipping). Building logic that treats it as empty leads to false positives.
isEnabled:false keeps the settings but only stops the display (app-managed shipping also stops).removeShipping:true removes the settings and reverts to inheritance. The behavior is fundamentally different.
Flat / Value-based can have multiple rate groups, butWeight-based must have exactly one,Carrier-calculated is single. Furthermore, rate groups can be scoped with conditions to aproduct collectionororigin location. When implementing, branch the group-count validation per type.
marketUpdate on each Market with delivery.shipping . Feed flat and weight-based rates per market, and manage the configuration IaC-style with GraphQL scripts.freeDeliveryMinimumValue . Switch it over via API only during the campaign period.optionDefinitionsToUpdate when it ends.currency . Specify amounts explicitly with amount / currencyCode.carrierServiceId with the Carrier-calculated option.autoIncludeNewServices:true auto-imports new services, andpercentageAdjustment adds a margin on top.