Table of Contents
- Key Highlights:
- Introduction
- What changed in the DeliveryProfile APIs
- How the new read model represents shipping options
- How writing shipping options changed: the new inputs you must use
- Backward compatibility and why the responses differ
- Who needs to act and what action to take
- Step-by-step migration plan
- Testing and QA strategies
- Real-world scenarios and examples
- Common pitfalls and how to avoid them
- Data modeling recommendations for your app
- Security, rate limits, and governance
- Monitoring and analytics you should add
- Troubleshooting common errors
- Practical example: mapping legacy responses to the new model
- Best practices for UI and UX after migration
- Versioning and the unstable GraphQL endpoint
- FAQ
Key Highlights:
- Shopify’s DeliveryProfile GraphQL API now supports multiple tiered rates grouped in rateGroups; legacy rateProvider and methodConditions fields are being replaced and will be deprecated.
- Apps that read merchant-managed DeliveryProfile data should migrate read queries to the new fields; any app that writes merchant-managed DeliveryProfile data must migrate to the new write inputs to avoid unexpected behavior.
- New write inputs (rateGroupsToCreate, rateGroupsToUpdate, freeConditions, currencyCode) allow structured creation and updates of complex shipping options; legacy write fields become obsolete once merchants use multiple tiered rates.
Introduction
Shopify updated its DeliveryProfile GraphQL objects and inputs to support multiple tiered shipping rates aggregated under rateGroups. This change affects how shipping options are represented, queried, and mutated. Developers building apps that read or write shipping profiles must evaluate their integrations and migrate where necessary: read clients should use new read fields to fetch richer, grouped rate data; write clients must adopt the new mutation inputs to reliably create and update merchant-managed shipping options. Apps that manage profiles themselves (app-managed) are unaffected unless merchants begin using multiple tiered rates. This article explains precisely what changed, why it matters, how the new API differs from the legacy one, and provides a practical migration plan, examples, testing guidance, and troubleshooting advice.
What changed in the DeliveryProfile APIs
The core of the update is a structural shift from single-rate provider representations to grouped, multi-rate constructs.
- Read API: DeliveryMethodDefinition.rateGroups and DeliveryRateDefinition.conditions replace the legacy DeliveryMethodDefinition.rateProvider and DeliveryMethodDefinition.methodConditions fields.
- Write API: DeliveryMethodDefinitionInput now supports rateGroupsToCreate and rateGroupsToUpdate, plus freeConditions and currencyCode. Legacy write fields such as participant, rateDefinition, priceConditionsToCreate, and weightConditionsToCreate will become obsolete once merchants employ tiered rates in Admin.
Why this matters: shipping rules are rarely flat. Merchants frequently use tiered pricing by weight, price, or other criteria, and they combine carrier-provided rates and custom fixed fees or percentage fees. Grouping multiple rate definitions into a single method definition with defined conditions makes the model more expressive and less awkward to map to real merchant settings. The flip side is that existing integrations may expect one method definition per rate; those expectations must be revisited.
How the new read model represents shipping options
Under the new model, a delivery method (e.g., "Standard") can contain one or more rateGroups. Each rateGroup contains rateProviders. RateProviders are either DeliveryRateDefinition (a price-based or transit-based rate) or DeliveryParticipant (carrier service with fee structure). DeliveryRateDefinition now exposes conditions directly as structured ranges rather than as separate methodConditions.
Key fields to request when querying a delivery profile:
- DeliveryMethodDefinition.id, name, description, active, currencyCode
- rateGroups { nodes { id, rateProviders { nodes { ... on DeliveryRateDefinition { id, price { amount, currencyCode }, minTransitTime, maxTransitTime, conditions { subject, min, max } } ... on DeliveryParticipant { id, carrierService { id, name }, fixedFee { amount, currencyCode }, percentageOfRateFee } } } } }
- freeConditions { subject, min, max }
This single, hierarchical representation reduces duplication. A method that previously required multiple method definitions (one per rate) becomes a single method with grouped rates and explicit free shipping conditions.
Example query (condensed):
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 } }
}
}
}
}
}
}
}
}
}
}
What to take away: query results will now include structured rateGroups and explicit conditions for each rate definition. Clients must navigate rateGroups → rateProviders → DeliveryRateDefinition/DeliveryParticipant to build the usable shipping matrix.
How writing shipping options changed: the new inputs you must use
Write mutations—deliveryProfileCreate and deliveryProfileUpdate—now accept more expressive inputs for shipping options. The significant new properties on DeliveryMethodDefinitionInput:
- rateGroupsToCreate: Create new rate groups with one or more rateDefinitions or participantDefinitions.
- rateGroupsToUpdate: Update existing rate groups and manage nested create/update/delete operations for rateDefinitions.
- freeConditions: Define free shipping rules (by price or weight) at the method level.
- currencyCode: Set currency for price definitions within that method.
Legacy fields such as participant, rateDefinition, priceConditionsToCreate, and weightConditionsToCreate will still exist temporarily but are flagged for obsolescence. If your app uses the write API to manage merchant-managed delivery profiles, you must move to the new inputs. Writing with legacy inputs will produce unexpected results if a merchant configures multiple tiered rates: the legacy model can’t represent multiple rates under a single method cleanly.
Example mutation to update a method with tiered rates and free shipping:
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 }
}
}
Key behaviors:
- Nested updates let you manage rateDefinitions within a rateGroup atomically (create/update/delete).
- freeConditions are declared at the method level rather than as separate zero-price rateDefinitions (as the legacy API did).
- currencyCode is explicit; prices should use consistent currency across rate definitions to avoid ambiguity.
Backward compatibility and why the responses differ
Shopify will temporarily support legacy fields to ease migration, but the difference in shape between legacy and new responses is significant and has functional consequences.
Legacy behavior:
- Each rate definition or free condition was represented as a separate method definition. This meant multiple entries with identical names but different rateProviders and methodConditions.
- Free shipping was modeled as a separate method definition containing a rateProvider with zero price.
- methodDefinitions count reflected the number of discrete rate rows produced by Admin rather than the logical grouping merchants expect.
New behavior:
- A single methodDefinition groups multiple rateDefinitions under rateGroups.
- freeConditions appear as part of the methodDefinition.freeConditions array.
- methodDefinitionCounts in the new response reflect grouped logical methods (rateDefinitionsCount will show the true number of rateDefinitions inside the grouped method).
Practical impact:
- Code that iterates over methodDefinitions expecting one rate per method will misread data. For example, UI that lists shipping choices might show duplicate names (legacy) or fold them into a single entry with multiple selectable tiers (new).
- Counters and analytics derived from methodDefinitionsCount or rateDefinitionsCount will differ.
- Any logic that relies on a one-to-one mapping between methodDefinitions and rateProviders must be updated to respect rateGroups → rateProviders mapping.
Example comparison from Shopify:
- New API Response showed activeMethodDefinitionsCount: 1 and one methodDefinition with rateGroups containing three rateDefinitions and a freeShippingConditions array.
- Legacy API Response represented the same merchant settings as activeMethodDefinitionsCount: 4 (three rate-based method definitions + one free condition method definition), with each methodDefinition containing a rateProvider and methodConditions.
If your app displays shipping options to merchants or to buyers, update the data model to interpret grouped rates correctly. If you persist these structures in your database, migrate storage format to accommodate rateGroups and freeConditions.
Who needs to act and what action to take
Assess your app's integration with shipping profiles along three axes: read usage, write usage, and profile ownership (merchant-managed vs app-managed).
- Apps that read merchant-managed DeliveryProfile
- Action: Migrate read queries to the new fields (rateGroups and DeliveryRateDefinition.conditions) or implement a dual-read strategy that supports both legacy and new fields while monitoring the deprecation timeline.
- Reason: Reading legacy fields will continue temporarily but may produce unexpected results when merchants use tiered rates.
- Apps that write merchant-managed DeliveryProfile
- Action: Migrate write operations to use rateGroupsToCreate / rateGroupsToUpdate and related new inputs before merchants start using tiered rates.
- Reason: Legacy write fields will become obsolete for merchant-managed profiles that include multiple tiered rates; failure to migrate may cause data loss, unexpected transformations, or mutation errors.
- Apps that read/write app-managed DeliveryProfile
- Action: No immediate action required unless your app elects to adopt the new grouped model for clarity or to interoperate with newer merchant configurations.
- Reason: App-managed profiles remain under the control of the app and will not be silently changed by merchant actions in Admin.
Practical checklist:
- Inventory: List all places where your app reads DeliveryProfile, DeliveryMethodDefinition, DeliveryRateDefinition, DeliveryCondition, and related fields.
- Query audit: Identify queries that reference rateProvider or methodConditions and update them to request rateGroups and the new conditions layout.
- Mutation audit: Identify mutations using legacy write inputs and refactor them to use the new nested rateGroups inputs.
- Tests: Create test cases modeling both legacy-style and grouped tiered rates; include at least one merchant scenario with multiple weight tiers and a free shipping threshold.
- Rollout: Use feature flags or API version toggles to stage the migration and revert quickly if needed.
Step-by-step migration plan
Follow these steps for minimal disruption.
- Audit and map current usage
- Export all GraphQL queries and mutations from your codebase and third-party libraries.
- Search for DeliveryMethodDefinition.rateProvider, DeliveryMethodDefinition.methodConditions, DeliveryMethodDefinitionInput.*legacy fields.
- Identify whether these are used in merchant-managed contexts.
- Update read queries
- Replace rateProvider and methodConditions field requests with rateGroups → rateProviders → DeliveryRateDefinition / DeliveryParticipant plus DeliveryRateDefinition.conditions.
- Maintain backward compatibility if your app must support older shops: request both legacy and new fields and prefer new fields when available.
- Update write mutations (critical for writer apps)
- Replace legacy mutation inputs with rateGroupsToCreate and rateGroupsToUpdate structures.
- Explicitly set currencyCode and freeConditions where applicable.
- Test nested create/update/delete operations for rateDefinitions within rateGroups.
- Update business logic and data models
- Adjust how you transform GraphQL responses into internal models or UI components. Stop treating methodDefinitions list as a flat list of rates.
- If you store methodDefinition IDs or rateDefinition IDs, confirm identity mapping remains consistent when a merchant transitions rates in Admin.
- Create migration tests
- Unit tests: Validate the parser maps new shape into app models.
- Integration tests: Use a development store to create merchant-managed profiles with multiple rate tiers and verify your app still reads and updates them correctly.
- Edge cases: Free shipping conditions, overlapping ranges, non-uniform currency usage, participant-based fees.
- Monitor and iterate
- Monitor Shopify changelog and your app’s error logs after deploying changes.
- Log migration-specific errors with context (profile id, method id) to investigate quickly.
- Deprecation adaptation
- Once legacy fields are removed from stable GraphQL, remove fallback code.
- Keep an eye on Shopify’s deprecation announcements for the final removal date.
Testing and QA strategies
Thorough testing prevents shipping configuration errors that directly affect merchant revenue and order fulfillment.
- Build test fixtures that mimic merchant Admin behavior:
- Multiple weight tiers (e.g., 0–10 kg = $10; 10.0001–20 kg = $20; 20.0001+ kg = $30).
- Free shipping threshold (e.g., $100).
- Mixed participant-based rates (carrier service with percentage fee and fixed fee).
- Mixed currencies (confirm mutations fail or handle conversions as expected).
- Use GraphiQL / Playground to run the example queries and mutations against a dev store.
- Validate that your UI shows a single "Standard" method with expanding tiers rather than multiple duplicate "Standard" entries.
- Confirm order calculations: place checkout flow tests that assert expected shipping cost selection given sample cart weights and totals.
- Validate concurrent edits: two merchants updating the same profile should not create inconsistent nested objects.
- Confirm access control: only merchants or apps with appropriate scopes should mutate merchant-managed profiles; verify failure modes and userErrors responses are handled.
Real-world scenarios and examples
Scenario 1: A clothing retailer
- Requirements: Shipping priced by total weight (0–1 kg: $5, 1.0001–3 kg: $8, 3.0001+ kg: $12) and free shipping on orders over $150.
- Legacy API representation: four methodDefinitions (three rates, one free condition).
- New API representation: one methodDefinition "Standard" with one rateGroup holding three DeliveryRateDefinition entries and a freeConditions entry specifying min { amount: 150.0 }.
- Developer action: Present the merchant with a single configurable method in UI, allow adding multiple rateDefinitions within a rateGroup, and store as nested rateGroups. When reading, display the grouped structure to match merchant expectations.
Scenario 2: A marketplace shipping app using carrier services
- Requirements: Provide a carrier-based rate plus a marketplace fee (percentage of carrier rate plus a fixed fee).
- New API: rateGroups may contain DeliveryParticipant definitions representing carrierService with fixedFee and percentageOfRateFee.
- Developer action: Use rateGroupsToCreate to add a rateGroup with a DeliveryParticipant (carrierService id) and set fixedFee/percentageOfRateFee in the participant definition. When reading, compute the marketplace fee and display the combined rate to the buyer.
Scenario 3: Cross-currency concerns
- Problem: A DeliveryMethodDefinition must specify currencyCode. If your app creates rateDefinitions with different currencies under the same method, behavior will be inconsistent.
- Developer action: Enforce single currency per methodDefinition. Validate input before mutation and surface an actionable error for merchants.
Common pitfalls and how to avoid them
- Assuming legacy field shape will persist forever: Shopify plans to deprecate legacy fields. Migrate proactively.
- Treating methodDefinitions as unique shipping choices: a grouped method might contain several rate tiers; present these tiers appropriately instead of making duplicate entries.
- Not handling freeConditions: legacy APIs modeled free shipping as a zero-price method. Under the new model, freeConditions are explicit. Failing to handle freeConditions leads to misrepresented promotions.
- Partial migrations: updating only read or write side leads to inconsistent behavior. Update both where applicable.
- Ignoring participant types: rateProviders can be DeliveryRateDefinition or DeliveryParticipant; code must discriminate and interpret each correctly.
- Incorrectly updating nested entities: nested IDs (rateGroup ID, rateDefinition ID) must be supplied correctly when updating. Deleting or updating wrong IDs can orphan definitions.
Data modeling recommendations for your app
- Normalize the new hierarchy:
- DeliveryProfile → profileLocationGroups → locationGroupZones → methodDefinitions → rateGroups → rateProviders (DeliveryRateDefinition | DeliveryParticipant).
- Persist necessary IDs to allow updates: keep deliveryProfile ID, deliveryProfileLocationGroup ID, deliveryLocationGroupZone ID, deliveryMethodDefinition ID, deliveryRateGroup ID, and deliveryRateDefinition ID.
- Store conditions as structured objects (subject, min, max) rather than single strings to ease comparisons and UI validation.
- Keep currencyCode at the methodDefinition level. Validate currency consistency on rateDefinition creation.
- Build convenience helpers to convert legacy shapes into new structured shapes if you support older stores or need to interpret legacy responses.
Security, rate limits, and governance
- Mutations on merchant-managed delivery profiles require appropriate API scopes. Confirm your app has the necessary Admin API permissions before writing.
- Avoid excessive mutation loops while migrating many merchant profiles. Throttle mutation batches to respect API rate limits.
- Log userErrors from mutations and surface actionable messages to merchants. Shopify returns userErrors with field and message properties; capture both.
- Treat profile and method IDs as sensitive configuration state. Prevent unauthorized access or persistence leakage.
Monitoring and analytics you should add
- Track the number of merchants using legacy vs new fields from your app’s telemetry (if permitted by privacy rules).
- Log mutation error rate spikes after migration and correlate with recent deploys.
- Monitor differences in methodDefinitions counts reported by the app versus direct Shopify data to detect parsing errors.
- Add auditing for write operations: which app user performed an update, previous vs new rateStructures, and timestamps. This helps chase down configuration regressions.
Troubleshooting common errors
- Error: userErrors returned that mention invalid currencyCode or mismatched currency.
- Fix: Ensure currencyCode is present in DeliveryMethodDefinitionInput and rateDefinitions use the same currency.
- Error: Unexpected shipping choices shown to customers (duplicate names, inconsistent prices).
- Fix: Confirm read logic handles rateGroups and discriminates between rateDefinitions and participants; update UI to group rates under a single method where appropriate.
- Error: Mutations succeed but Admin shows fragmented method definitions (legacy appearance).
- Fix: Check whether the merchant edited the method in Admin after your mutation; Admin may translate new data into legacy-visible entries for backward compatibility. Use the read example to see which fields are present.
- Error: Missing free shipping condition in the read response.
- Fix: Make sure you query freeConditions on the methodDefinition; confirm that the merchant’s configuration defines a free condition.
Practical example: mapping legacy responses to the new model
If your app historically ingested legacy API responses and stored methodDefinitions as separate rows per rate, you need a migration routine:
- For a set of methodDefinition rows that share a base method id (or name), group them by base method id or name.
- For each group:
- Create a single logical methodDefinition record.
- Create a rateGroup record containing each rateDefinition corresponding to legacy rateProvider entries.
- Convert methodConditions arrays from legacy to conditions arrays in the rateDefinition by mapping TOTAL_WEIGHT/TOTAL_PRICE to the new subject enumerations and mapping min/max values accordingly.
- Convert legacy zero-price rateDefinitions representing free conditions into freeConditions at the method level.
This mapping ensures your persisted model aligns with the new API shape and your UI renders grouped methods correctly.
Best practices for UI and UX after migration
- Represent grouped methods as expandable rows: show method name and lowest available rate (or a range), with an expand action to reveal tiers and transit times.
- If a method contains both participant-based rates (carrier services) and fixed-priced rates, show a consolidation label (e.g., “Carrier + surcharge”).
- Provide merchant-facing configuration screens that reflect the natural structure: allow adding a rateGroup, then adding rateDefinitions (price & conditions) or participants (carrier mapping & fees).
- Validate input ranges to avoid overlaps and gaps (overlapping ranges can cause ambiguous pricing during checkout).
- Show a preview of buyer-facing pricing for test carts to give merchants confidence immediately after they edit profiles.
Versioning and the unstable GraphQL endpoint
Shopify’s documentation references these fields on the unstable GraphQL branch. When using unstable features:
- Keep API usage under feature flags and test thoroughly against dev stores.
- Watch the Shopify changelog and migration guides for the stable release and deprecation schedule.
- Avoid shipping code that depends on unstable APIs to production without fallbacks, unless your app is prepared for iterative changes and quick rollbacks.
FAQ
Q: Which apps must migrate immediately? A: Any app that writes merchant-managed DeliveryProfile data must migrate writes to the new inputs. Apps that only read merchant-managed DeliveryProfiles should migrate reads to the new fields to avoid unexpected behavior when merchants use tiered rates. Apps interacting exclusively with app-managed DeliveryProfiles do not need to migrate immediately.
Q: Will the legacy fields stop working immediately? A: Shopify will continue supporting legacy fields temporarily for backward compatibility. However, those fields are scheduled for deprecation. You should migrate proactively; do not rely on legacy behavior indefinitely.
Q: How does free shipping appear in the new model? A: Free shipping is represented as freeConditions on the DeliveryMethodDefinition. FreeConditions include subject (e.g., TOTAL_PRICE), min and max (MoneyV2 or Weight) objects. Free shipping is no longer modeled as a separate zero-price methodDefinition in the new API.
Q: Can a rateGroup mix DeliveryRateDefinition and DeliveryParticipant entries? A: Yes. A rateGroup’s rateProviders collection can include both DeliveryRateDefinition entries (explicit price rules) and DeliveryParticipant entries (carrier services with fixed or percentage fees).
Q: What happens to apps that continue using legacy write inputs? A: Mutating merchant-managed profiles with legacy inputs may lead to unexpected behavior if a merchant configures multiple tiered rates in Admin. Shopify will make these legacy fields obsolete once merchants start using rateGroups; apps must adopt the new write inputs to maintain correct behavior.
Q: How should I handle currency for rate definitions? A: Use the currencyCode field at the DeliveryMethodDefinitionInput level and ensure all rateDefinition prices under that method use the same currency. If your application needs to support multi-currency, model separate methodDefinitions per currency.
Q: How should I test shipping calculations end-to-end? A: Create dev stores with representative merchant configurations (weight tiers, price tiers, free shipping thresholds, participant-based carrier rates). Run checkout flows for carts that exercise each tier and confirm charged shipping equals the expected price. Include concurrency tests and mutation round-trips where the merchant updates rates while your app reads or writes.
Q: Are there performance implications for reading rateGroups? A: Grouping reduces duplication in the API response, but you may need to request additional nested fields. Limit fields to those your app requires. Use pagination where appropriate for large numbers of rateGroups or rateProviders.
Q: Where can I find authoritative migration examples? A: Use Shopify’s Developer documentation and the provided example queries and mutations for deliveryProfileCreate and deliveryProfileUpdate. Start with the unstable GraphQL examples and apply them to your dev store to validate behavior.
Q: How do I handle shops that still use the legacy layout? A: Implement a dual-read approach temporarily: request both legacy and new fields. Prefer the new grouped shape when present. Log occurrences of legacy-only data and notify merchants or take appropriate migration steps.
Q: What common mistakes cause mismatched shipping costs? A: Overlapping condition ranges (e.g., two tiers both applying to weight 10.0), wrong currency codes, failing to include freeConditions, or misapplying participant fees are the typical causes. Validate ranges, enforce single currency, and simulate end-to-end checkouts to catch issues.
Final note: Treat this change as an opportunity to simplify how your app models shipping. The grouped rate model better reflects merchant intent and reduces redundant entries. Prioritize updating write paths and then update read paths, test comprehensively, and align your UI to present grouped shipping methods clearly to merchants and buyers.
