Skip to main content

Migrate to catalogs

The Catalog object connects product publications with buyer contexts. This resource enables apps to create product catalogs that can be targeted to specific markets or business-to-business (B2B) company locations. In the future, the Catalog object will be used to contextualize more aspects of merchandising, such as B2B quantity rules, volume pricing, and discounts.

In this guide, you'll learn how to migrate your app to use catalogs instead of context rules.


  • You've built an app that creates and manages price lists.
  • Your app is on API version 2023-01 or earlier, and uses the PriceList.contextRule field to determine a customer's price list eligibility, instead of the Catalog resource.


Anchor to Step 1: Update price list mutationsStep 1: Update price list mutations

Previously, price lists were associated with markets and countries through the contextRule field to provide international pricing. In API version 2023-04, an international price list needs to be associated with the catalog that's associated with a market or set of countries. Because of this change, you need to update the priceListCreate and priceListUpdate mutations to accept inputs for a catalog ID instead of the contextRule field.

The following example shows how to use these mutations to associate a price list with a catalog:

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

GraphQL mutation

mutation PriceListCreate {
priceListCreate(input: {
name: "Market Price List",
currency: CAD,
parent: {
adjustment: {
value: 10,
type: PERCENTAGE_INCREASE
}
}
catalogId: "gid://shopify/MarketCatalog/1"
}) {
priceList {
id
catalog { id }
}
userErrors {
field
code
message
}
}
}
mutation PriceListUpdate {
priceListUpdate(
id: "gid://shopify/PriceList/1"
input: {
catalogId: "gid://shopify/MarketCatalog/1"
}
) {
priceList {
id
catalog { id }
}
userErrors {
field
code
message
}
}
}

JSON response

{
"data": {
"priceListCreate": {
"priceList": {
"id": "gid://shopify/PriceList/1",
"catalog": {
"id": "gid://shopify/MarketCatalog/1"
}
},
"userErrors": []
}
}
}
{
"data": {
"priceListCreate": {
"priceList": {
"id": "gid://shopify/PriceList/1",
"catalog": {
"id": "gid://shopify/MarketCatalog/1"
}
},
"userErrors": []
}
}
}
Tip

You can also use the catalogUpdate mutation to associate a price list with an existing catalog.


Anchor to Step 2: Update price list queriesStep 2: Update price list queries

Previously, you could query a price list's eligible markets and countries through the contextRule field. In API version 2023-04, you need to query the eligible markets and countries through the catalog field instead. Because of this, you need to update the priceList and priceLists queries to retrieve information through the catalog field instead of the contextRule field.

The following example shows how to use these queries to retrieve market information through the catalog:

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

GraphQL query

query PriceList {
priceList(id: "gid://shopify/PriceList/1") {
id
name
parent {
adjustment {
type
value
}
}
catalog {
id
... on MarketCatalog {
markets(first: 10) { nodes { id } }
}
}
}
}
query PriceLists {
priceLists(first: 10) {
nodes {
id
name
parent {
adjustment {
type
value
}
}
catalog {
id
... on MarketCatalog {
markets(first: 10) { nodes { id } }
}
}
}
}
}

JSON response

{
"data": {
"priceList": {
"id": "gid://shopify/PriceList/1",
"name": "Market Pricing",
"parent": {
"adjustment": {
"type": "PERCENTAGE_INCREASE",
"value": 10
}
},
"catalog": {
"id": "gid://shopify/MarketCatalog/1",
"markets": {
"nodes": [
{
"id": "gid://shopify/Market/1"
}
]
}
}
}
}
}
{
"data": {
"priceLists": {
"nodes": [
{
"id": "gid://shopify/PriceList/1",
"name": "Market Pricing",
"parent": {
"adjustment": {
"type": "PERCENTAGE_INCREASE",
"value": 10
}
},
"catalog": {
"id": "gid://shopify/MarketCatalog/1",
"markets": {
"nodes": [
{
"id": "gid://shopify/Market/1"
}
]
}
}
}
]
}
}
}


Was this page helpful?