--- title: >- New APIs to read and write shipping options in delivery profile - Shopify developer changelog description: >- Shopify’s developer changelog documents all changes to Shopify’s platform. Find the latest news and learn about new platform opportunities. source_url: html: >- https://shopify.dev/changelog/posts/new-apis-to-read-and-write-shipping-options-in-delivery-profile md: >- https://shopify.dev/changelog/posts/new-apis-to-read-and-write-shipping-options-in-delivery-profile.md metadata: effectiveApiVersion: '' affectedApi: - displayName: Admin GraphQL API handle: admin-graphql primaryTag: displayName: API handle: api secondaryTag: displayName: Breaking API Change handle: breaking-api-change indicatesActionRequired: true createdAt: '2026-02-19T20:10:43-05:00' postedAt: '2026-02-24T10:35:00-05:00' updatedAt: '2026-02-24T10:35:19-05:00' effectiveAt: '2026-02-20T12:00:00-05:00' --- February 24, 2026 # New APIs to read and write shipping options in delivery profile DateFebruary 24, 2026 Flags[Breaking API Change](https://shopify.dev/changelog?filter=breaking-api-change)[Action required](https://shopify.dev/changelog?action_required=true) SurfacesAPI Affected APIs[Admin GraphQL API](https://shopify.dev/changelog?api_type=admin-graphql) As part of the enhanced UI for creating shipping options, a shipping option can now include multiple tiered rates grouped together. If your app integrates with delivery profiles and uses [`DeliveryMethodDefinition`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/DeliveryMethodDefinition) and [`DeliveryMethodDefinitionInput`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/DeliveryMethodDefinitionInput) to manage shipping options, then evaluate if you need to transition to the new APIs in the unstable version: * If your app reads merchant-managed `DeliveryProfile`, you might need to migrate to the new read API. Refer to the \[Read API]\(#Read API) and [backwards compatibility](#backwards-compatibility-for-queries) sections. * If your app writes merchant-managed `DeliveryProfile`, then you must migrate to the new write API to avoid unexpected behaviour. Refer to the \[Write API]\(#Write API) section. * If your app reads and/or writes app-managed `DeliveryProfile`, then no action is needed. **Glossary:** * Merchant-managed `DeliveryProfile`: Shipping profiles that merchants create and edit in the Shopify admin. * App-managed `DeliveryProfile`: Shipping profiles that the app creates and edits. This guide outlines the new GraphQL fields and input types for managing shipping options within shipping profiles. ## What's changed? ### Read API We're introducing the [`DeliveryMethodDefinition.rateGroups`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/DeliveryMethodDefinition#field-DeliveryMethodDefinition.fields.rateGroups) and [`DeliveryRateDefinition.conditions`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/DeliveryRateDefinition#field-DeliveryRateDefinition.fields.conditions) fields. These replace the legacy [`DeliveryMethodDefinition.rateProvider`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/DeliveryMethodDefinition#field-DeliveryMethodDefinition.fields.rateProvider) and [`DeliveryMethodDefinition.methodConditions`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/DeliveryMethodDefinition#field-DeliveryMethodDefinition.fields.methodConditions) fields. To prevent unexpected behavior, migrate to these new fields. Refer to the [example query](#how-to-query-shipping-options) to learn how to use these fields to fetch a `DeliveryMethodDefinition`. The legacy fields are scheduled for deprecation. For details on their current behavior, see [backward compatibility for queries](#backward-compatibility-for-queries). ### Write API The following new input fields have been added to [`DeliveryMethodDefinitionInput`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/DeliveryMethodDefinitionInput): \*[ `rateGroupsToCreate`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/DeliveryMethodDefinitionInput#fields-priceConditionsToCreate) * [`rateGroupsToUpdate`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/DeliveryMethodDefinitionInput#fields-rateGroupsToUpdate) * [`freeConditions`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/DeliveryMethodDefinitionInput#fields-freeConditions) * [`currencyCode`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/DeliveryMethodDefinitionInput#fields-currencyCode) The following legacy fields will become obsolete when merchants start using multiple tiered rates: * [`DeliveryMethodDefinitionInput.participant`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/DeliveryMethodDefinitionInput#fields-participant) * [`DeliveryMethodDefinitionInput.rateDefinition`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/DeliveryMethodDefinitionInput#fields-rateDefinition) * [`DeliveryMethodDefinitionInput.priceConditionsToCreate`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/DeliveryMethodDefinitionInput#fields-priceConditionsToCreate) * [`DeliveryMethodDefinitionInput.weightConditionsToCreate`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/DeliveryMethodDefinitionInput#fields-weightConditionsToCreate) . To learn how to update a `DeliveryMethodDefinition` using the new fields, see the [example mutation](#how-to-create-and-update-shipping-options) ## Examples ### How to query shipping options ```graphql query DeliveryProfile { deliveryProfile(id: "gid://shopify/DeliveryProfile/123") { profileLocationGroups { locationGroup { id } locationGroupZones(first: 10) { edges { node { methodDefinitions(first: 10) { edges { node { id name description active currencyCode rateGroups(first: 10) { edges { node { id rateProviders(first: 10) { edges { node { ... on DeliveryRateDefinition { id price { amount currencyCode } minTransitTime maxTransitTime conditions { subject min { ... on MoneyV2 { amount currencyCode } ... on Weight { value unit } } max { ... on MoneyV2 { amount currencyCode } ... on Weight { value unit } } } } ... on DeliveryParticipant { id carrierService { id name } fixedFee { amount currencyCode } percentageOfRateFee } } } } } } } freeConditions { subject min { ... on MoneyV2 { amount currencyCode } ... on Weight { value unit } } max { ... on MoneyV2 { amount currencyCode } ... on Weight { value unit } } } } } } } } } } } } ``` ### How to create and update shipping options For the [`deliveryProfileCreate`](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/deliveryProfileCreate) and [`deliveryProfileUpdate`](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/deliveryProfileUpdate) mutations, the following new input fields are added to `DeliveryMethodDefinitionInput`: * `rateGroupsToCreate` * `rateGroupsToUpdate` * `freeConditions` * `currencyCode` Here's how to update a shipping option using the new input fields: ```graphql mutation ProfileUpdate { deliveryProfileUpdate( id: "gid://shopify/DeliveryProfile/123" profile: { profileLocationGroups: [ { id: "gid://shopify/DeliveryProfileLocationGroup/456" zonesToUpdate: [ { id: "gid://shopify/DeliveryLocationGroupZone/789" methodDefinitionsToUpdate: [ { id: "gid://shopify/DeliveryMethodDefinition/321" rateGroupsToUpdate: [ { id: "gid://shopify/DeliveryRateGroup/555" rateDefinitionsToUpdate: [ { id: "gid://shopify/DeliveryRateDefinition/666" price: { amount: 7.50 currencyCode: USD } minTransitTime: 172800 } ] rateDefinitionsToDelete: [ "gid://shopify/DeliveryRateDefinition/777" ] rateDefinitionsToCreate: [ { price: { amount: 15.00 currencyCode: USD } conditions: [ { subject: PACKAGE_WEIGHT min: 20.0 unit: "kg" } ] } ] } ] } ] } ] } ] } ) { profile { id } userErrors { field message } } } ``` ### Backwards compatibility for queries The `DeliveryMethodDefinition.rateProvider` and `DeliveryMethodDefinition.methodConditions` fields will continue to be supported temporarily to facilitate a smooth transition. When using the legacy API: * If a method definition includes multiple rate definitions, then each additional rate is represented as a separate method definition with its own `rateProvider` and `methodConditions`. * Free conditions are represented as separate method definitions with a zero-price rate definition as the `rateProvider`. For example, a method definition with three rate definitions and a free condition will yield different results in the new and legacy APIs. The [`activeMethodDefinitionsCount`](https://shopify.dev/docs/api/admin-graphql/latest/objects/DeliveryProfile#field-DeliveryProfile.fields.activeMethodDefinitionsCount) and [`methodDefinitionCounts`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/DeliveryLocationGroupZone#field-DeliveryLocationGroupZone.fields.methodDefinitionCounts) will reflect these differences. **New API response** ```json { "data": { "node": { "activeMethodDefinitionsCount": 1, "profileLocationGroups": [ { "locationGroupZones": { "nodes": [ { "methodDefinitionCounts": { "rateDefinitionsCount": 1, "participantDefinitionsCount": 0 }, "methodDefinitions": { "nodes": [ { "id": "gid://shopify/DeliveryMethodDefinition/825837944888", "name": "Standard", "rateGroups": { "nodes": [ { "rateProviders": { "nodes": [ { "id": "gid://shopify/DeliveryRateDefinition/760813584440", "price": { "amount": "10.0", "currencyCode": "CAD" }, "conditions": [ { "subject": "PACKAGE_WEIGHT", "min": { "value": 0, "unit": "KILOGRAMS" }, "max": { "value": 10, "unit": "KILOGRAMS" } } ] }, { "id": "gid://shopify/DeliveryRateDefinition/760813617208", "price": { "amount": "20.0", "currencyCode": "CAD" }, "conditions": [ { "subject": "PACKAGE_WEIGHT", "min": { "value": 10.0001, "unit": "KILOGRAMS" }, "max": { "value": 20, "unit": "KILOGRAMS" } } ] }, { "id": "gid://shopify/DeliveryRateDefinition/760813649976", "price": { "amount": "30.0", "currencyCode": "CAD" }, "conditions": [ { "subject": "PACKAGE_WEIGHT", "min": { "value": 20.0001, "unit": "KILOGRAMS" }, "max": null } ] } ] } } ] }, "freeShippingConditions": [ { "min": { "amount": "100.0", "currencyCode": "CAD" } } ] } ] } } ] } } ] } } } ``` **Legacy API response** With the legacy API, you receive multiple method definitions, one for each rate definition and one for the free condition: ```json { "data": { "node": { "activeMethodDefinitionsCount": 4, "profileLocationGroups": [ { "locationGroupZones": { "nodes": [ { "methodDefinitionCounts": { "rateDefinitionsCount": 4, "participantDefinitionsCount": 0 }, "methodDefinitions": { "nodes": [ { "id": "gid://shopify/DeliveryMethodDefinition/825837944888", "name": "Standard", "rateProvider": { "__typename": "DeliveryRateDefinition", "id": "gid://shopify/DeliveryRateDefinition/760813584440", "price": { "amount": "10.0", "currencyCode": "CAD" } }, "methodConditions": [ { "id": "gid://shopify/DeliveryCondition/21530181688?operator=greater_than_or_equal_to", "field": "TOTAL_WEIGHT", "conditionCriteria": { "value": 0, "unit": "KILOGRAMS" } }, { "id": "gid://shopify/DeliveryCondition/21530181688?operator=less_than_or_equal_to", "field": "TOTAL_WEIGHT", "conditionCriteria": { "value": 10, "unit": "KILOGRAMS" } } ] }, { "id": "gid://shopify/DeliveryMethodDefinition/825837944888?source=RateDefinition&source_id=760813617208", "name": "Standard", "rateProvider": { "__typename": "DeliveryRateDefinition", "id": "gid://shopify/DeliveryRateDefinition/760813617208", "price": { "amount": "20.0", "currencyCode": "CAD" } }, "methodConditions": [ { "id": "gid://shopify/DeliveryCondition/21530214456?operator=greater_than_or_equal_to", "field": "TOTAL_WEIGHT", "conditionCriteria": { "value": 10.0001, "unit": "KILOGRAMS" } }, { "id": "gid://shopify/DeliveryCondition/21530214456?operator=less_than_or_equal_to", "field": "TOTAL_WEIGHT", "conditionCriteria": { "value": 20, "unit": "KILOGRAMS" } } ] }, { "id": "gid://shopify/DeliveryMethodDefinition/825837944888?source=RateDefinition&source_id=760813649976", "name": "Standard", "rateProvider": { "__typename": "DeliveryRateDefinition", "id": "gid://shopify/DeliveryRateDefinition/760813649976", "price": { "amount": "30.0", "currencyCode": "CAD" } }, "methodConditions": [ { "id": "gid://shopify/DeliveryCondition/21530247224?operator=greater_than_or_equal_to", "field": "TOTAL_WEIGHT", "conditionCriteria": { "value": 20.0001, "unit": "KILOGRAMS" } } ] }, { "id": "gid://shopify/DeliveryMethodDefinition/825837944888?source=RateRangeCondition&source_id=21530279992", "name": "Standard", "rateProvider": { "__typename": "DeliveryRateDefinition", "id": "gid://shopify/DeliveryRateDefinition/0?source=RateRangeCondition&source_id=21530279992", "price": { "amount": "0.0", "currencyCode": "CAD" } }, "methodConditions": [ { "id": "gid://shopify/DeliveryCondition/21530279992?operator=greater_than_or_equal_to", "field": "TOTAL_PRICE", "conditionCriteria": { "amount": "100.0", "currencyCode": "CAD" } } ] } ] } } ] } } ] } } } ```