Use market metafields
A market metafield is a metafield that stores your app's custom data on a market. For each buyer, Shopify returns the values from the markets that the buyer matches, based on conditions such as the buyer's region or company location. A child market uses its parent market's metafield values unless it sets its own.
In this guide, you'll learn how to create, read, and delete market metafields, how Shopify resolves them for a buyer, and how to retrieve the resolved values so your app can show a custom experience to different buyers.
Anchor to RequirementsRequirements
- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
read_marketsaccess scope, and either thewrite_market_metafieldsor thewrite_marketsaccess scope. Learn how to configure your access scopes using Shopify CLI.
If your app is migrating from deprecated single-market endpoints, then Shopify will help backfill the market metafield access scopes for your app. Learn how to migrate to market metafields.
If your app is migrating from deprecated single-market endpoints, then Shopify will help backfill the market metafield access scopes for your app. Learn how to migrate to market metafields.
Anchor to LimitationsLimitations
- Each app that's installed on a shop can create up to 256 market metafield definitions in its reserved namespace.
- A shop can have up to 256 merchant-owned market metafield definitions, which use namespaces that aren't app-reserved. This limit is separate from each app's limit, and it includes the merchant-owned definitions that apps create.
Learn more about metafield limits.
Anchor to Create metafields on marketsCreate metafields on markets
To store custom data on a market, create a metafield definition with the MARKET owner type, and then set a metafield value on a market.
Anchor to Step 1: Create a market metafield definitionStep 1: Create a market metafield definition
Use the metafieldDefinitionCreate mutation to create a definition with the MARKET owner type. The following example creates a definition for a discount percentage, an integer, in the app-reserved $app namespace. The PUBLIC_READ storefront access makes the values available to the Storefront API:
POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json
GraphQL mutation
Variables
JSON response
You can also declare app-owned metafield definitions in your app's shopify.app.toml file. Learn more about creating metafield definitions with TOML.
Anchor to Step 2: Set a metafield on a marketStep 2: Set a metafield on a market
Use the metafieldsSet mutation to set the metafield value on a market. Pass the market's ID as the ownerId:
POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json
GraphQL mutation
Variables
JSON response
Anchor to Read metafields on marketsRead metafields on markets
Use the GraphQL Admin API to read the metafields that are set directly on a market. These queries return the value that's stored on each market, not the value that Shopify resolves for a buyer. To get the resolved value, refer to Retrieve resolved market metafields.
To read a metafield on one market, use the market query:
POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json
GraphQL query
JSON response
To read a metafield on many markets, use the markets query. A market that doesn't have the metafield returns null:
POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json
GraphQL query
JSON response
Anchor to Delete metafields on marketsDelete metafields on markets
Use the metafieldsDelete mutation to delete a metafield from a market:
POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json
GraphQL mutation
Variables
JSON response
Anchor to How market metafields resolveHow market metafields resolve
A metafield identifier is a namespace and a key. Shopify evaluates the markets that a buyer matches, and resolves each market metafield identifier to a single value based on market specificity. Specificity is the market precedence and the market's position in the market hierarchy. For example, a B2B market is more specific than a region market, and a child market is more specific than its parent.
To find the parent-child relationships between a shop's markets, use the marketRelationships query. Learn more about market inheritance.
Anchor to Resolution rulesResolution rules
Shopify resolves each metafield identifier separately, so different metafields can resolve from different markets:
- If the buyer matches no market that has a metafield with the identifier, then no value is returned for the identifier.
- If the buyer matches one market that has a metafield with the identifier, then that market's value is returned.
- If the buyer matches more than one market that has a metafield with the identifier, then the value from the most specific market is returned.
- If two markets with equal specificity have a metafield with the identifier, then Shopify breaks the tie. Learn more about tie-breaking.
Anchor to InheritanceInheritance
A metafield value that's set on a parent market applies to all of its child markets. For example, you set an app-owned metafield with the key discount_percent and the value 10 on the North America market. A query for the discount_percent key for a buyer in Canada returns 10, even though no metafield is set on the Canada market.
Anchor to OverrideOverride
A child market can set its own value for the same metafield identifier to override the inherited value. For example, you also set the discount_percent key to 15 on the Canada market. A query for the discount_percent key for a buyer in Canada now returns 15, instead of the value 10 from the North America market.
Anchor to Tie-breakingTie-breaking
If two markets with the same specificity set the same metafield identifier, then Shopify uses the value from the market whose handle is first in alphabetical order. While this behavior rolls out, some stores use the value that was updated most recently instead.
For example, a store has the following markets, which have the same specificity:
| Market name | Market handle | Metafield |
|---|---|---|
| Canada and United States | ca_us | namespace: "$app", key: "discount_percent", value: 10 |
| Canada and Mexico | ca_mx | namespace: "$app", key: "discount_percent", value: 15 |
A buyer in Canada matches both markets. The discount_percent key resolves to 15 from the Canada and Mexico market, because the handle ca_mx is before ca_us in alphabetical order.
Anchor to Retrieve resolved market metafieldsRetrieve resolved market metafields
Each buyer-facing surface returns the market metafield values that Shopify resolves for the current buyer.
Anchor to LiquidLiquid
Use localization.market.metafields to access the resolved market metafields for the buyer. In a theme app extension, use the $app reserved prefix for your app's namespace. The store's own theme code uses the full namespace, app--{your_app_id}:
Liquid
Anchor to Storefront APIStorefront API
The Storefront API returns resolved market metafields through the marketsMetafield and marketsMetafields fields on the Localization object. These fields are available in the unstable version of the Storefront API.
You need the following to query market metafields with the Storefront API:
- A valid Storefront API access token.
- The storefront access of the metafield definition set to
PUBLIC_READ.
The $app namespace resolves to your app's reserved namespace, such as app--123, based on the access token that makes the request. If the request uses a merchant's own Storefront API access token, then use the full namespace, such as app--123, instead of $app.
The $app namespace resolves to your app's reserved namespace, such as app--123, based on the access token that makes the request. If the request uses a merchant's own Storefront API access token, then use the full namespace, such as app--123, instead of $app.
Use the @inContext directive to set the buyer's country, and then query the market metafields through localization.marketsMetafields:
POST https://{shop}.myshopify.com/api/unstable/graphql.json
GraphQL query
Variables
JSON response
To resolve market metafields for a logged-in B2B customer, pass the buyer argument to the @inContext directive. The buyer argument requires a customer access token that you get through the Customer Account API authentication flow:
POST https://{shop}.myshopify.com/api/unstable/graphql.json
GraphQL query
Variables
Learn more about B2B on headless storefronts.
Anchor to Shopify FunctionsShopify Functions
Shopify Functions read resolved market metafields through the localization.marketsMetafield field of the input query. This field is available in the unstable version of the Function APIs, for example in the Discount Function API.
Use an input query variable for the metafield key, so that each function owner, such as a discount, can read a different market metafield:
-
Define the input query with a variable for the metafield key:
src/cart_lines_discounts_generate_run.graphql
query Input($marketMetafieldKey: String!) {localization {marketsMetafield(namespace: "$app", key: $marketMetafieldKey) {value}}} -
In your function's
shopify.extension.tomlfile, setinput_variableson the target. It names the metafield that holds the variable values. That metafield is on the function owner, the resource that the function is attached to, such as a discount:shopify.extension.toml
[[extensions.targeting]]target = "cart.lines.discounts.generate.run"input_query = "src/cart_lines_discounts_generate_run.graphql"input_variables = { namespace = "$app", key = "function_variables" }export = "cart-lines-discounts-generate-run" -
Use the
metafieldsSetmutation to set the JSON metafield thatinput_variablesnames, with the namespace$appand the keyfunction_variables, on the function owner, such as the discount. Each property of the metafield's value sets the input query variable with the same name. The following value sets$marketMetafieldKey, so the function reads the market metafield with the keydiscount_percent:Metafield value
{"marketMetafieldKey": "discount_percent"} -
Read the resolved value in your function code. The
marketsMetafieldfield isnullwhen no market that the buyer matches has the metafield:src/cart_lines_discounts_generate_run.js
const discountPercent = Number(input.localization.marketsMetafield?.value ?? 0);
Anchor to GraphQL Admin APIGraph QL Admin API
The GraphQL Admin API returns the metafields that are set on each market. To read them, refer to Read metafields on markets.
To find out which market metafield value applies to a buyer, query the Storefront API with the buyer's context.
The Storefront API doesn't immediately reflect the changes that a merchant makes to their store's configuration. Use the Storefront API to find what applies to a buyer, not to manage the store's current configuration in the Shopify admin.
The Storefront API doesn't immediately reflect the changes that a merchant makes to their store's configuration. Use the Storefront API to find what applies to a buyer, not to manage the store's current configuration in the Shopify admin.
Anchor to Customer Account APICustomer Account API
To find out which market metafield value applies to a logged-in customer, query the Storefront API with the buyer argument of the @inContext directive.
Anchor to Best practicesBest practices
The following practices help you keep market metafields safe from other apps, and easy for your app and merchants to manage.
Anchor to Use the app-reserved namespaceUse the app-reserved namespace
Use an app-owned reserved prefix, such as $app, in your metafield namespace, so that other apps can't use your metafields.
Anchor to Use JSON metafields for complex configurationsUse JSON metafields for complex configurations
Metafields support many data types, but app configurations often require nested or repeated data structures. A single JSON metafield can make your configuration easier to manage and query.
If you need larger and more structured data, then you can use a metafield with metaobject references.
Your app might have settings that belong together, such as the products in a promotion and their discounts. If you store them in one metafield, then a market inherits or overrides all of them together, instead of each one separately. For example, the North America market gets promotions on products A and B, and the Canada market gets promotions on products A and C, but not on product B.
Use a JSON metafield with the same key, such as promo_config, to store the settings on each market:
Values of the promo_config metafield
North America market
{
"products": [
{ "name": "UltraWide Monitor", "discount_percent": 15 },
{ "name": "Mechanical Keyboard", "discount_percent": 10 }
]
}Canada market
{
"products": [
{ "name": "UltraWide Monitor", "discount_percent": 20 },
{ "name": "Ergonomic Mouse", "discount_percent": 12 }
]
}Your app can then manage and query related settings together, in one metafield.
Shopify resolves each metafield key, not each setting in the metafield. A buyer in Canada gets all of the Canada market's settings, which override the settings of the North America market. Your app must write all of the settings on each child market where the settings are different from its parent's.
Anchor to Reference configurations by nameReference configurations by name
Merchants can see market metafields on the markets in the Shopify admin. Instead of a complex configuration, you can store the name that the merchant gave the configuration. For example, a merchant understands "Summer sale" better than a JSON object.
Your app can use the name to find the full configuration, which it stores in a separate metafield, a metaobject, or the app's database.
Anchor to Next stepsNext steps
- Learn how to migrate your app from deprecated single-market endpoints to market metafields.
- Learn how market inheritance ranks the markets that a buyer matches.
- Learn more about metafields.