Skip to main content

Checking for eligibility to the new markets experience

The new Markets APIs provide capabilities that aren't all compatible with the previous Markets APIs. As an app developer, you need to check if the new markets experience is enabled on a shop to be able to use the new features in the 2025-04 version of the API.

Anchor to Store eligibilityStore eligibility

You can check if a merchant's store is eligible to use the new markets experience by querying the unifiedMarkets field on the ShopFeatures type.

If the ShopFeatures type returns true, then you can use the new fields on marketCreate and marketUpdate mutations.

Anchor to Step 1: Verify eligibilityStep 1: Verify eligibility

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Check store eligibility

query shopFeatures {
shop {
features {
unifiedMarkets
}
}
}

JSON response

{
"data": {
"shop": {
"features": {
"unifiedMarkets": true
}
}
}
}

Anchor to Step 2: Use the new fields on market mutationsStep 2: Use the new fields on market mutations

Now that you have verified the store's eligibility to the new markets, you can use the new fields on the marketCreate and marketUpdate mutations, allowing you to create and update the new types of markets and customizations.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Create a Canada retail market

mutation CreateRetailCanada {
marketCreate(input: {
name: "Canada Retail",
conditions: {
locationsCondition: {
applicationLevel: ALL
}
regionsCondition: {
regions: [{
countryCode: CA
}]
}
}
}) {
market {
id
name
conditions {
conditionTypes
regionsCondition {
applicationLevel
regions(first: 10) { nodes { id name } }
}
locationsCondition {
applicationLevel
locations(first: 10) { nodes { id name } }
}
}
}
userErrors { field code message }
}
}

JSON response

{
"data": {
"marketCreate": {
"market": {
"id": "gid://shopify/Market/1",
"name": "Canada Retail",
"conditions": {
"conditionTypes": [
"LOCATION",
"REGION"
],
"regionsCondition": {
"applicationLevel": "SPECIFIED",
"regions": {
"edges": [
{
"node": {
"id": "gid://shopify/MarketRegionCountry/1",
"name": "Canada"
}
}
]
}
},
"locationsCondition": {
"applicationLevel": "ALL",
"locations": {
"edges": []
}
}
}
},
"userErrors": []
}
}
}

Anchor to Stores that aren't eligibleStores that aren't eligible

If you haven't checked the store's eligibility for the new markets experience, and you try to use the same mutation as above, then you'll encounter a UNIFIED_MARKETS_NOT_ENABLED error, and the market won't be saved.

The following example shows the error response that's returned if a store isn't eligible.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

Attempt to create a retail market for a non-eligible shop

mutation CreateRetailCanada {
marketCreate(input: {
name: "Canada Retail",
conditions: {
locationsCondition: {
applicationLevel: ALL
}
regionsCondition: {
regions: [{
countryCode: CA
}]
}
}
}) {
market {
id
name
conditions {
conditionTypes
regionsCondition {
applicationLevel
regions(first: 10) { nodes { id name } }
}
locationsCondition {
applicationLevel
locations(first: 10) { nodes { id name } }
}
}
}
userErrors { field code message }
}
}

JSON response

{
"data": {
"marketCreate": {
"userErrors": [
{
"code": "UNIFIED_MARKETS_NOT_ENABLED",
"message": "This action can't be performed because unified markets are not enabled.",
"field": ["input", "conditions"],
},
],
"market": null
}
}
}

Anchor to Next stepsNext steps

Was this page helpful?