--- title: Migrate to catalogs description: Learn how to migrate your app to use catalogs to publish and sell products in different markets. source_url: html: https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs?itcat=partnersblog&itterm=b2b-apis md: https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs.md?itcat=partnersblog&itterm=b2b-apis --- ExpandOn this page * [Requirements](https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs#requirements) * [Considerations](https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs#considerations) * [Step 1: Update price list mutations](https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs#step-1-update-price-list-mutations) * [Step 2: Update price list queries](https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs#step-2-update-price-list-queries) * [Next steps](https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs#next-steps) # Migrate to catalogs The [`Catalog`](https://shopify.dev/docs/api/admin-graphql/unstable/interfaces/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. *** ## Requirements * You've built an app that creates and manages [price lists](https://shopify.dev/docs/api/admin-graphql/2023-01/objects/pricelist). * 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. *** ## Considerations * To be eligible to use market catalogs, merchants must be using [Shopify Markets](https://help.shopify.com/manual/markets). [Merchants on legacy country price lists](https://help.shopify.com/en/manual/markets/stores-excluded-from-markets) aren't eligible to use market catalogs. * To be eligible for B2B catalogs, merchants must be on the [Shopify Plus](https://www.shopify.com/plus) plan. *** ## Step 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`](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/pricelistcreate) and [`priceListUpdate`](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/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 ```graphql 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 } } } ``` ```graphql mutation PriceListUpdate { priceListUpdate( id: "gid://shopify/PriceList/1" input: { catalogId: "gid://shopify/MarketCatalog/1" } ) { priceList { id catalog { id } } userErrors { field code message } } } ``` ## JSON response ```json { "data": { "priceListCreate": { "priceList": { "id": "gid://shopify/PriceList/1", "catalog": { "id": "gid://shopify/MarketCatalog/1" } }, "userErrors": [] } } } ``` ```json { "data": { "priceListCreate": { "priceList": { "id": "gid://shopify/PriceList/1", "catalog": { "id": "gid://shopify/MarketCatalog/1" } }, "userErrors": [] } } } ``` Tip You can also use the [`catalogUpdate`](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/catalogupdate) mutation to associate a price list with an existing catalog. *** ## Step 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`](https://shopify.dev/docs/api/admin-graphql/unstable/queries/pricelist) and [`priceLists`](https://shopify.dev/docs/api/admin-graphql/unstable/queries/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 ```graphql query PriceList { priceList(id: "gid://shopify/PriceList/1") { id name parent { adjustment { type value } } catalog { id ... on MarketCatalog { markets(first: 10) { nodes { id } } } } } } ``` ```graphql query PriceLists { priceLists(first: 10) { nodes { id name parent { adjustment { type value } } catalog { id ... on MarketCatalog { markets(first: 10) { nodes { id } } } } } } } ``` ## JSON response ```json { "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" } ] } } } } } ``` ```json { "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" } ] } } } ] } } } ``` *** ## Next steps * Learn [how catalogs work](https://shopify.dev/docs/apps/build/markets/catalogs-different-markets), and [how to create catalogs for B2B company locations](https://shopify.dev/docs/apps/build/b2b/start-building#step-2-create-a-b2b-catalog). *** * [Requirements](https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs#requirements) * [Considerations](https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs#considerations) * [Step 1: Update price list mutations](https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs#step-1-update-price-list-mutations) * [Step 2: Update price list queries](https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs#step-2-update-price-list-queries) * [Next steps](https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs#next-steps)