Skip to main content

Build a catalog

Catalogs are used to define the set of products that are published to customers in different contexts, and the prices of each product. The context of each catalog determines which group it applies to. For example, a catalog assigned to the European market might specify that customers shipping to Europe can purchase anything except the electronics without CE certification, but that with a few exceptions, they have to pay 10% higher prices.

In this guide, you’ll learn how to configure a market’s catalog with a price list and publication to control prices and restrict product availability for a specific market.

Note

If you're using the new Markets API, which is currently in developer preview, then refer to Create a catalog for a specific market instead.

Anchor to RequirementsRequirements

Anchor to Step 1: Query the market catalogStep 1: Query the market catalog

Each market has a catalog that’s automatically created and associated with the market. The catalog determines the products that are published to customers in that market. You can use the catalogs query to retrieve the market catalogs on a store:

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

GraphQL query

query Catalogs {
catalogs(first: 1, type: MARKET) {
nodes {
id
status
priceList { id }
publication { id }
... on MarketCatalog {
markets(first: 1) {
nodes {
id
name
}
}
}
}
}
}

JSON response

{
"data": {
"catalogs": {
"nodes": [
{
"id": "gid://shopify/MarketCatalog/CATALOG-ID",
"status": "ACTIVE",
"priceList": null,
"publication": {
"id": "gid://shopify/Publication/PUBLICATION-ID"
},
"markets": {
"nodes": [
{
"id": "gid://shopify/Market/1",
"name": "Europe"
}
]
}
}
]
}
}
}
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 price list with the catalogStep 2: Associate a price list with the catalog

After you query 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 that 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.

Caution

The market currency and price list currency must match. For example, you can’t create a price list that’s mapped to a Canadian market catalog with currency CAD and then set the price list currency to USD.

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 3: Set fixed prices for specific product variantsStep 3: 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 4: Unpublish specific products to restrict them from saleStep 4: 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

Market catalogs are just one part of the product publication story. Sales channels have their own publications that influence 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 uses the 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 query

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

JSON response

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

Anchor to Step 5 (Optional): Delete a price listStep 5 (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: deletedId
userErrors {
field
message
}
}
}

Variables

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

JSON response

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

Anchor to Step 6: Check the final resultsStep 6: Check the final results

Catalogs are the building blocks to control pricing and product availability around the world. Once you’ve configured a catalog, you can check what a real customer will see by passing a specific country to the publishedInContext and contextualPricing fields.

This ability to query from a specific buyer’s perspective is especially useful when customizing pricing for multi-country markets. Even when you set a fixed price in a market’s default currency, the final price a customer sees might have been converted into their local currency. Learn more about international pricing.

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

GraphQL query

query ProductDetails($id: ID!) {
product(id: $id) {
publishedInDE: publishedInContext(context: { country: DE })
publishedInDK: publishedInContext(context: { country: DK })
variants(first: 1) {
nodes {
pricingInDE: contextualPricing(context: { country: DE }) {
price { amount currencyCode }
}
pricingInDK: contextualPricing(context: { country: DK }) {
price { amount currencyCode }
}
}
}
}
}

Variables

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

JSON response

{
"data": {
"product": {
"publishedInDE": true,
"publishedInDK": true,
"variants": {
"nodes": [
{
"pricingInDE": {
"price": { "amount": "10.0", "currencyCode": "EUR" }
},
"pricingInDK": {
"price": { "amount": "74.49", "currencyCode": "DKK" }
}
}
]
}
}
}
}

Anchor to Next stepsNext steps

Was this page helpful?