Skip to main content

Create a catalog for a specific market

Note

Not all merchant stores are eligible for the new markets experience. As an app developer, you must check if the shop is onboarded on the new markets experience before you can use the new marketCreate and marketUpdate mutations.

Catalogs define the set of products that are available to customers in a market, and the prices of each product. The market that's associated to a catalog defines the target audience. For example, a catalog that's associated to a market with a European region condition might allow customers shipping to Europe to purchase all items except electronics lacking CE certification. With a few exceptions, customers need to pay 10% higher prices.

In this guide, you’ll learn how to create a catalog that includes a price list and publication settings to manage prices and control product availability, and then link the catalog to a specific market.

Anchor to RequirementsRequirements

Anchor to Step 1: Create a new catalogStep 1: Create a new catalog

By default, markets aren't automatically associated with catalogs. You must create a catalog and associate it with a market. The catalog determines the products that are published to customers in that market. You can use the catalogCreate mutation to create a new catalog:

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

GraphQL mutation

mutation CreateCatalog {
catalogCreate(input: {
title: "Europe"
status: ACTIVE
context: {marketIds: []}
}) {
catalog {
id
title
status
priceList { id }
publication { id }
... on MarketCatalog {
markets(first: 1) {
nodes {
id
name
}
}
}
}
}
}

JSON response

{
"data": {
"catalogs": {
"nodes": [
{
"id": "gid://shopify/MarketCatalog/CATALOG-ID",
"title": "Europe",
"status": "ACTIVE",
"priceList": null,
"publication": null,
"markets": {
"nodes": []
}
}
]
}
}
}

To create a catalog that you'll later associate to a market, you need to specify the empty marketIds array in the context field. If you have a market ID, then you can use it to assign the catalog to the market immediately, but you won't be able to control pricing or product availability until you associate a price list and publication with it.

Tip

You can create a catalog for a business-to-business (B2B) company location using the catalogCreate mutation. Learn how to create a B2B catalog.

Anchor to Step 2: Associate a publication with the catalogStep 2: Associate a publication with the catalog

After you create a catalog, you can use the catalog ID to associate a publication with the catalog. The publication determines the products that are published to customers in a market.

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

GraphQL mutation

mutation CreatePublication {
publicationCreate(input: {
catalogId: "gid://shopify/MarketCatalog/CATALOG-ID",
defaultState: ALL_PRODUCTS,
autoPublish: true
}) {
publication {
id
autoPublish
catalog {
id
title
}
}
}
}

JSON response

{
"data": {
"publicationCreate": {
"publication": {
"id": "gid://shopify/Publication/PUBLICATION-ID",
"autoPublish": true,
"catalog": {
"id": "gid://shopify/MarketCatalog/CATALOG-ID",
"title": "Europe"
}
}
}
}
}

Anchor to Step 3: Associate a price list with the catalogStep 3: Associate a price list with the catalog

After you create a catalog, you can use the catalog ID to associate a price list with the catalog. The price list determines the prices that are shown to customers in a market. If a price list isn’t associated with the catalog, then customers in the associated market receive the initial variant prices converted to the market currency.

Anchor to Create a new price listCreate a new price list

Use the priceListCreate mutation to create a new price list for the catalog. You can set the name, a percentage-based adjustment, a currency, and the ID of the catalog to associate.

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

GraphQL mutation

mutation priceListCreate($input: PriceListCreateInput!) {
priceListCreate(input: $input) {
priceList {
id
}
userErrors {
field
message
}
}
}

Variables

{
"input": {
"name": "European prices",
"currency": "EUR",
"catalogId": "gid://shopify/MarketCatalog/CATALOG-ID",
"parent": {
"adjustment": {
"type": "PERCENTAGE_INCREASE",
"value": 10.0
}
}
}
}
{
"input": {
"name": "Prices for Company's European location",
"currency": "EUR",
"catalogId": "gid://shopify/CompanyLocationCatalog/CATALOG-ID",
"parent": {
"adjustment": {
"type": "PERCENTAGE_DECREASE",
"value": 30.0
},
"settings": {
"compareAtMode": "NULLIFY"
}
}
}
}

JSON response

{
"data": {
"priceListCreate": {
"priceList": {
"id": "gid://shopify/PriceList/ID"
},
"userErrors": []
}
}
}

Anchor to Associate an existing price listAssociate an existing price list

Use the priceListUpdate mutation to associate an existing price list with a catalog. You can also make changes to the name, currency, or percentage-based adjustments with the priceListUpdate mutation.

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

GraphQL mutation

mutation priceListUpdate($id: ID!, $input: PriceListUpdateInput!) {
priceListUpdate(id: $id, input: $input) {
priceList {
id
}
userErrors {
field
message
}
}
}

Variables

{
"id": "gid://shopify/PriceList/ID",
"input": {
"catalogId": "gid://shopify/MarketCatalog/CATALOG-ID"
}
}
{
"id": "gid://shopify/PriceList/ID",
"input": {
"catalogId": "gid://shopify/CompanyLocationCatalog/CATALOG-ID"
}
}

JSON response

{
"data": {
"priceListUpdate": {
"priceList": {
"id": "gid://shopify/PriceList/ID"
},
"userErrors": []
}
}
}

Anchor to Step 4: Set fixed prices for specific product variantsStep 4: Set fixed prices for specific product variants

Use the priceListFixedPricesAdd mutation to set a fixed price for specific product variants.

If a product variant is published to the catalog and doesn’t have a set fixed price, then its price is automatically calculated using the percentage-based adjustment that’s specified in the PriceListParent object.

Warning

The priceListFixedPricesAdd mutation accepts a maximum of 250 prices for each request and acts as an add and replace operation. If a fixed price for a given variant already exists on the price list, then it’s replaced.

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

GraphQL mutation

mutation priceListFixedPricesAdd(
$priceListId: ID!,
$prices: [PriceListPriceInput!]!
) {
priceListFixedPricesAdd(priceListId: $priceListId, prices: $prices) {
prices {
variant {
id
}
}
userErrors {
field
message
}
}
}

Variables

{
"priceListId": "gid://shopify/PriceList/ID",
"prices": [
{
"variantId": "gid://shopify/ProductVariant/ID",
"price": {
"amount": "10.00",
"currencyCode": "EUR"
},
"compareAtPrice": {
"amount": "12.00",
"currencyCode": "EUR"
}
},
{
"variantId": "gid://shopify/ProductVariant/ID-2",
"price": {
"amount": "15.00",
"currencyCode": "EUR"
}
}
]
}

JSON response

{
"data": {
"priceListFixedPricesAdd": {
"prices": [
{ "variant" : { "id" : "gid://shopify/ProductVariant/ID" } },
{ "variant" : { "id" : "gid://shopify/ProductVariant/ID" } }
],
"userErrors": []
}
}
}

Anchor to Delete fixed pricesDelete fixed prices

To delete a partial set of fixed prices on a price list, you can use the priceListFixedPricesDelete mutation. After a fixed price is deleted, the price for the affected product variant is automatically calculated using the price list parent's percentage-based adjustment.

To delete fixed prices, you need to specify the variant ID. You can specify a maximum of 250 variant IDs in the array.

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

GraphQL mutation

mutation priceListFixedPricesDelete(
$priceListId: ID!,
$variantIds: [ID!]!
) {
priceListFixedPricesDelete(priceListId: $priceListId, variantIds: $variantIds) {
userErrors {
field
message
}
}
}

Variables

{
"priceListId": "gid://shopify/PriceList/ID",
"variantIds": ["gid://shopify/ProductVariant/ID"]
}

JSON response

{
"data": {
"priceListFixedPricesDelete": {
"deletedFixedPriceVariantIds": [
"gid://shopify/ProductVariant/ID"
],
"userErrors": []
}
}
}

Anchor to Step 5: Unpublish specific products to restrict them from saleStep 5: Unpublish specific products to restrict them from sale

If there are specific products that must be restricted from sale in the market, then use the publicationUpdate mutation to remove them from the market’s publication. The publicationUpdate mutation allows you to republish a product to the market.

Note

Associating catalogs to markets is just one part of the product publication story. Sales channels have their own publications that determine what products are available to a customer. Only products that are published in all applicable catalogs are available for purchase. For example, if a European customer accesses an online store, then they can purchase a product that’s published both to the European market and to the Online Store channel. However, a product that’s unpublished in either the European market or the Online Store channel can’t be purchased by the customer.

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

GraphQL mutation

mutation UnpublishProducts {
publicationUpdate(
id: "gid://shopify/Publication/1"
input: {
publishablesToRemove: [
"gid://shopify/Product/1",
"gid://shopify/Product/2"
]
}
) {
userErrors { field message }
}
}

JSON response

{
"data": {
"userErrors": []
}
}

Anchor to Step 6 (Optional): Delete a price listStep 6 (Optional): Delete a price list

You can use the priceListDelete mutation to delete a price list so that it no longer applies for products in that market catalog. To delete a price list, you need to specify the price list ID. When deleting a priceList, all of the priceListPrices are also deleted.

Note

If you delete a price list for a market using the API and then also use the Shopify admin to save an adjustment, then a new price list for the market is created.

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

GraphQL mutation

mutation priceListDelete($id: ID!) {
priceListDelete(id: $id) {
deletedId
userErrors {
field
message
}
}
}

Variables

{
"id": "gid://shopify/PriceList/ID"
}

JSON response

{
"data": {
"priceListDelete": {
"deletedId": "gid://shopify/PriceList/DELETED-ID",
"userErrors": []
}
}
}

Anchor to Step 7: Associate the catalog with a marketStep 7: Associate the catalog with a market

With a catalog created and a publication and price list associated, you can now associate the catalog with a market. Ensure you have a market ID to use in the context field and then use the marketUpdate mutation to add the catalog to the market.

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

GraphQL mutation

mutation MarketUpdate {
marketUpdate(input: {
id: "gid://shopify/MarketCatalog/MARKET-ID",
catalogsToAdd: ["gid://shopify/MarketCatalog/CATALOG-ID"]
}) {
market {
id
catalogs(first: 1) {
nodes {
id
title
}
}
}
}
}

JSON response

{
"data": {
"marketUpdate": {
"market": {
"id": "gid://shopify/Market/MARKET-ID",
"catalogs": {
"nodes": [
{
"id": "gid://shopify/MarketCatalog/CATALOG-ID",
"title": "Europe"
}
]
}
}
}
}
}

Anchor to Next stepsNext steps

Was this page helpful?