Tags:
- Action Required
- Admin GraphQL API
New APIs to read and write shipping options in delivery profile
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 and 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
, you might need to migrate to the new read API. Refer to the [Read API](#Read API) and backwards compatibility sections. - If your app writes merchant-managed
, 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
, then no action is needed.
Glossary:
- Merchant-managed
: Shipping profiles that merchants create and edit in the Shopify admin. - App-managed
: 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 and fields. These replace the legacy and fields.
To prevent unexpected behavior, migrate to these new fields. Refer to the example query to learn how to use these fields to fetch a .
The legacy fields are scheduled for deprecation. For details on their current behavior, see backward compatibility for queries.
Write API
The following new input fields have been added to :
*
The following legacy fields will become obsolete when merchants start using multiple tiered rates:
To learn how to update a using the new fields, see the example mutation
Examples
How to query shipping options
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 and mutations, the following new input fields are added to :
Here's how to update a shipping option using the new input fields:
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 and 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
and. - Free conditions are represented as separate method definitions with a zero-price rate definition as the
.
For example, a method definition with three rate definitions and a free condition will yield different results in the new and legacy APIs. The and will reflect these differences.
New API response
{
"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:
{
"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"
}
}
]
}
]
}
}
]
}
}
]
}
}
}
Was this section helpful?