---
title: About catalogs for different markets
description: "Learn how catalogs can be used to assign lists of products to specific contexts based on certain conditions. "
source_url:
  html: https://shopify.dev/docs/apps/build/markets/catalogs-different-markets
  md: https://shopify.dev/docs/apps/build/markets/catalogs-different-markets.md
---

# About catalogs for different markets

**Caution:**

Starting in API version 2023-04, the [`PriceList.contextRule`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/PriceList#field-pricelist-contextrule) field will be deprecated. If you have an existing app that uses the `contextRule` field, then you should [migrate to catalogs](https://shopify.dev/docs/apps/build/markets/migrate-to-catalogs).

A catalog is a set of products that's published and priced for certain customers based on specified conditions. For example, you can make a catalog of products for customers who are browsing the online store from Canada and the United States.

In this guide, you'll learn how catalogs work, and some considerations for using catalogs to publish and price products, and to sell in different contexts.

**Note:**

If you're using the new Markets API, which is currently in feature preview, then refer to [About catalogs in the feature preview](https://shopify.dev/docs/apps/build/markets/new-markets/catalogs) instead.

***

## Requirements

* Your app can make [authenticated requests](https://shopify.dev/docs/api/admin-graphql#authentication) to the GraphQL Admin API.
* Your app has the `write_products` [access scope](https://shopify.dev/docs/api/usage/access-scopes). Learn how to [configure your access scopes using Shopify CLI](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration).
* You've created [products](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productcreate) and [product variants](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productvariantcreate) in your store.

***

## How it works

A catalog represents a list of products to be published in a specified context, such as for international customers, certain business-to-business (B2B) customers, or customers on certain sales channels.

A [`Catalog`](https://shopify.dev/docs/api/admin-graphql/unstable/interfaces/Catalog) has a [`Publication`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/publication) field that determines which products are visible to the customer when they visit the online store and checkout.

Each `Catalog` object also has a [`PriceList`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/PriceList) field that determines any price adjustments for its eligible contexts, such as a [`Market`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Market) for international customers, a [`CompanyLocation`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/CompanyLocation) for business-to-business (B2B) customers, or an [`App`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/app) for customers on certain sales channels.

### Price lists

For each [`PriceList`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/PriceList), a [`PriceListParent`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/PriceListParent) can be used to control prices using percentage adjustments. You can use the [`PriceListPrice`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/PriceListPrice) object to represent a final, fixed price for a single product variant.

If you use the `PriceListPrice` field to configure a fixed price for a product variant, then the fixed price takes precedence over any other adjustments that are defined at the price list level. For more information about how prices are determined, refer to [Pricing prioritization](#pricing-prioritization).

### Specialized catalog patterns

Catalogs support flexible configuration patterns that allow you to separate pricing and publication concerns. This flexibility can dramatically reduce the number of catalogs needed for complex scenarios.

#### Pricing-only catalogs

A pricing-only catalog is a catalog without an associated publication. You can create one by calling the [`catalogCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/catalogcreate) mutation and omitting the `publicationId` field.

Pricing-only catalogs are simpler than regular catalogs and are often the better choice if you don't need to manage publications. They are more efficient and easier to maintain for most pricing use cases.

When a pricing-only catalog is assigned to a market or company location, product availability is determined by the sales channel publication (such as products published to the Online Store channel). The catalog only controls pricing through its price list.

#### Publication-only catalogs

A publication-only catalog is a catalog without an associated price list. You can create one by calling the [`catalogCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/catalogcreate) mutation and omitting the `priceListId` field.

Publication-only catalogs are useful when you want to manage which products are visible to customers without applying custom pricing. When a publication-only catalog is assigned to a market, customers see:

* **Products**: Only products published in the catalog's publication.
* **Prices**: Store default prices converted to the market's currency using [multi-currency rules](https://help.shopify.com/en/manual/payments/shopify-payments/multi-currency/conversions).

Publication-only catalogs are ideal when:

* You have fewer product assortments than price variations.
* You want to control product availability independently from pricing.
* You're implementing the [two-catalog pattern](#two-catalog-pattern-for-scale) described below.

#### Full catalogs

A full catalog has both a price list and a publication. This is the traditional approach where a single catalog controls both pricing and product availability for a specific context.

### Two-catalog pattern for scale

When merchants have many price lists and many product assortments, you can assign multiple catalogs to the same market or company location. For example, a merchant might update pricing nightly while product assortments change monthly.

#### The efficiency problem

Without the two-catalog pattern:

* **Scenario**: 700 different price lists × 30 different product offers.
* **Catalogs needed**: 21,000 full catalogs (one for each combination).
* **Management overhead**: Extremely high.

With the two-catalog pattern:

* **Catalogs needed**: 730 catalogs total.

  * 700 pricing-only catalogs (one per price list).
  * 30 publication-only catalogs (one per product assortment).

* **Efficiency gain**: 97% reduction in catalog count.

#### How it works

1. **Create pricing-only catalogs**: One for each unique price list, all assigned to the same market context.
2. **Create publication-only catalogs**: One for each unique product assortment, all assigned to the same market context.
3. **Shopify resolves pricing**: Customers receive the lowest price from applicable pricing catalogs.
4. **Shopify resolves products**: Products must be published in at least one applicable publication catalog to be visible.

**Example in practice:**

When a customer in the European market browses your store:

* **Market has**: 1 pricing-only catalog ("EU Premium Pricing +10%") + 1 publication-only catalog ("EU Electronics Products").
* **Result**: Customer sees products from the "EU Electronics Products" publication at prices from the "EU Premium Pricing +10%" price list.
* **If multiple catalogs**: Customer sees products from any applicable publication catalog, priced at the lowest price from any applicable pricing catalog.

This allows you to mix and match: the same pricing catalog can work with different publication catalogs, and the same publication catalog can work with different pricing catalogs.

#### Code example

```graphql
# Step 1: Create a pricing-only catalog
mutation createPricingCatalog {
  catalogCreate(input: {
    title: "EU Premium Pricing - 10% increase"
    status: ACTIVE
    context: { marketIds: ["gid://shopify/Market/123"] }
    priceListId: "gid://shopify/PriceList/456"
  }) {
    catalog { id title }
    userErrors { field message }
  }
}


# Step 2: Create a publication-only catalog for the SAME market
mutation createPublicationCatalog {
  catalogCreate(input: {
    title: "EU Electronics Products"
    status: ACTIVE
    context: { marketIds: ["gid://shopify/Market/123"] }
    publicationId: "gid://shopify/Publication/789"
  }) {
    catalog { id title }
    userErrors { field message }
  }
}


# Step 3: Query to verify both catalogs are assigned to the market
query verifyMarketCatalogs {
  market(id: "gid://shopify/Market/123") {
     catalogs(first: 10) {
      edges {
        node {
          id
          title
          priceList { id }
          publication { id }
        }
      }
    }
  }
}
```

#### Customer experience

When a customer in this market shops:

1. **Product visibility**: They see products published in the "EU Electronics Products" publication.
2. **Pricing**: They receive prices from the "EU Premium Pricing" price list (10% increase).
3. **Multiple pricing catalogs**: If multiple pricing catalogs apply, then they receive the lowest price.
4. **Multiple publication catalogs**: Products must be in at least one publication to be visible.

#### When to use this pattern

**Use the two-catalog pattern when:**

* You have many distinct price lists but fewer product assortments, or fewer price lists but many product assortments.
* You need to manage pricing and product availability independently.
* You want to reduce catalog management overhead.

**Don't use this pattern when:**

* You have a small number of catalogs (fewer than 50).
* Pricing and product availability are tightly coupled.
* You need strict combinations (for example, "Price List A only applies to Product Set X").

For more examples, see the [`catalogCreate` mutation documentation](https://shopify.dev/docs/api/admin-graphql/latest/mutations/catalogCreate).

### API objects and relationships

Before you start implementing catalogs, we recommend familiarizing yourself with the following API objects and their relationships:

![A diagram showing the relationships between catalogs and price list objects](https://shopify.dev/assets/assets/images/apps/internationalization/catalog-api-objects-C4QYrcyG.png)

| API object | Description |
| - | - |
| `Catalog` | A set of products and prices that's published to a specified context, such as a market or B2B company location. |
| `Market` | A group of one or more regions that can be targeted with a configured catalog of products and prices. |
| `CompanyLocation` | A specified location or branch for a [B2B company](https://shopify.dev/docs/api/admin-graphql/unstable/objects/company) that can be targeted with a configured catalog of products and prices.[B2B APIs and features](https://shopify.dev/docs/apps/build/b2b) are available only to merchants on the [Shopify Plus](https://shopify.com/plus) plan. |
| `Publication` | A group of products that's published to a catalog.When a publication is associated with a catalog, customers that belong to the associated market or company location have access to view and purchase only the products and collections within the publication. Prices and adjustments from the price list apply to the associated published products.When a publication isn't associated with a catalog, and the catalog is associated with a market or company location, then the published products are determined by the sales channel. For example, if a customer uses the online store and their catalog doesn't have an associated publication, then their product selection is all products that are published to the online store sales channel. |
| `PriceList` | A list of prices for different products that are displayed to the customer if they belong to an eligible context.If a customer is eligible for multiple price lists, then the displayed price list follows the [pricing prioritization](#pricing-prioritization) rules. |
| `PriceListParent` | The price adjustment rule, such as a percentage increase or decrease, that's applied to the product's or product variant's initial price.Adjustments can either reduce the initial prices with the `PERCENTAGE_DECREASE` type, or raise the initial prices with the `PERCENTAGE_INCREASE` type. The adjustment value is either a positive decimal number or zero.You can also use the `settings.compareAtMode` field to determine whether a price list with relative prices adjusts the `compareAtPrice` for the variant:- If the `compareAtMode` is `ADJUSTED`, then the price list returns an adjusted `compareAtPrice`. For example, if the default `compareAtPrice` is $10 and the price list applies a 10% price increase, then the `compareAtPrice` is adjusted to $11. This is the default setting.
- If the `compareAtMode` is `NULLIFY`, then the price list returns `null` for the `compareAtPrice`. |
| `PriceListPrice` | The price of one product variant that's associated with the price list.The [origin type](https://shopify.dev/docs/api/admin-graphql/unstable/enums/pricelistpriceorigintype) of a price list price indicates whether the price list price is `FIXED` (defined on the price list) or `RELATIVE` (calculated using the price list adjustment on the parent):- **Fixed price list prices**: Price lists can include fixed price list prices for some, all, or none of the products. Fixed price list prices are defined in the price list currency. If a fixed price list price has been configured for a product variant, then it takes precedence over any other adjustments that are defined at the price list level.
- **Relative price list prices**: If a fixed price list price hasn't been configured for a product variant, then a relative price list price is calculated based on the pricing adjustment that's specified in the price list parent. Relative price list prices are returned in the store currency from the APIs and don't have rounding rules and foreign exchange rates applied. Rounding rules and foreign exchange rates are applied in the online store and checkout. |
| `ProductVariant` | The variant that's associated with a price list and belongs to a publication. |

### Pricing prioritization

Price lists are displayed to customers through the online store and checkout based on their eligible catalogs. A catalog represents certain criteria about the customer that must be true for a price list to apply.

If a customer is [logged into a B2B customer account](https://help.shopify.com/manual/b2b/checkout), then any catalogs that are associated with their selected company location are prioritized over catalogs that are associated with their eligible markets or other contexts.

After the price list is applied, pricing is determined by priority as described in the following diagram:

![A diagram showing how pricing is determined by priority order](https://shopify.dev/assets/assets/images/apps/internationalization/pricing-prioritization-flow-BbpL_5wX.png)

In the example scenario depicted in the diagram, a US-based merchant configures a price list for a Canadian market with currency CAD that applies different pricing for Canadian customers:

* If the customer doesn't match a catalog's context, then the given price is the initial price (the product variant price) in the original currency.
* If a price list isn't associated with the catalog, then the initial price is applied using the selected currency rules. The example uses a foreign exchange rate of 1.3.
* If a [`PriceListPrice`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/pricelistprice) isn't defined, then an adjusted relative price is calculated using the [`PriceListParent`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/pricelistparent) object. Adjusted prices work in conjunction with exchange rules and rounding. In the example, the merchant sets a rounding rule to 0.99 for all currencies. A price adjustment of 20% applies in addition to the foreign exchange rate of 1.3. The price is calculated as $20 \* 1.3 \* 1.2 = $31.99.
* If a `PriceListPrice` is defined, then a specific fixed price is applied for the product. This price applies irrespective of foreign exchange rules or rounding.

**Note:**

When the customer is eligible for multiple catalogs, they receive the lowest price that's associated with those catalogs, whether it's a fixed or adjusted relative price.

#### Foreign exchange and rounding rules

If the customer's market doesn't match the store currency and a price list isn't associated with their catalog, then foreign exchange and rounding are applied to the initial price using either [automatic or manual multi-currency rules](https://help.shopify.com/en/manual/payments/shopify-payments/multi-currency/conversions).

However, if the customer's market doesn't match the store currency, and an adjusted relative price has been applied through the price list parent, then foreign exchange and rounding are applied along with the adjustment. If a fixed price list price is applicable, then foreign exchange and rounding aren't applied because the prices are already in the desired currency.

**Note:**

Foreign exchange and rounding are applicable to product variants and the adjusted relative price. Foreign exchange and rounding aren't applicable to fixed price list prices.

#### Selling plan pricing policies

Selling plan pricing policies work in conjunction with price lists:

* If a selling plan has a [`SellingPlanPricingPolicyAdjustmentType`](https://shopify.dev/docs/api/admin-graphql/latest/enums/sellingplanpricingpolicyadjustmenttype) with a value of either `FIXED_AMOUNT` or `PERCENTAGE`, then the selling plan adjustment applies to the price list, both for fixed prices and relative adjustments.
* If the value is `PRICE`, then the selling plan value overrides the price list settings.

In the following diagram, the pricing request includes a selling plan that reduces the price. A 15% `PERCENTAGE` adjustment type is applied to the [`PriceListPrice`](https://shopify.dev/docs/api/admin-graphql/latest/objects/pricelistprice) of $35.00. The final price is $29.40.

![A diagram that illustrates the pricing engine](https://shopify.dev/assets/assets/images/api/pricing-engine-relationships-a1ChpCVM.png)

***

## Considerations

* Multiple catalogs can be assigned to the same market. This enables the [two-catalog pattern](#two-catalog-pattern-for-scale) where you separate pricing and publication concerns.
* Multiple catalogs can be assigned to the same B2B company location. If a customer is logged into a B2B customer account that's eligible for multiple catalogs that contain the same product, then they receive the lowest listed price within those catalogs.
* When multiple catalogs apply to a market, pricing follows the lowest price rule. Products must be published in at least one applicable publication catalog to be visible to customers.
* 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 set the price list currency to USD.
* There are no webhooks that are associated with changes to catalogs or price lists.

***

## Developer tools and resources

Explore the following developer tools and resources to learn more about building with catalogs:

[Catalog object\
\
](https://shopify.dev/docs/api/admin-graphql/unstable/interfaces/Catalog)

[Consult the GraphQL Admin API reference to learn more about the `Catalog` object.](https://shopify.dev/docs/api/admin-graphql/unstable/interfaces/Catalog)

[PriceList object\
\
](https://shopify.dev/docs/api/admin-graphql/unstable/objects/PriceList)

[Consult the GraphQL Admin API reference to learn more about the `PriceList` object.](https://shopify.dev/docs/api/admin-graphql/unstable/objects/PriceList)

***

## Next steps

* Learn how to [sell different products for different prices around the world](https://shopify.dev/docs/apps/build/markets/build-catalog) by configuring the price list and publication of a market's catalog.
* Learn how to [create a B2B catalog](https://shopify.dev/docs/apps/build/b2b/start-building#step-2-create-a-b2b-catalog) to determine the published products and prices for customers ordering for a specific B2B company location.

***