--- title: About catalogs in the feature preview 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/new-markets/catalogs' md: 'https://shopify.dev/docs/apps/build/markets/new-markets/catalogs.md' --- ExpandOn this page * [How it works](https://shopify.dev/docs/apps/build/markets/new-markets/catalogs.md#how-it-works) * [Considerations](https://shopify.dev/docs/apps/build/markets/new-markets/catalogs.md#considerations) * [Developer tools and resources](https://shopify.dev/docs/apps/build/markets/new-markets/catalogs.md#developer-tools-and-resources) # About catalogs in the feature preview 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](https://shopify.dev/docs/apps/build/markets/new-markets/merchant-eligibility) before you can use the new [`marketCreate`](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/marketCreate) and [`marketUpdate`](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/marketUpdate) mutations. 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 to use catalogs to help merchants sell in different contexts, and some considerations for using catalogs to publish and price products. *** ## 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/latest/interfaces/Catalog) has a [`Publication`](https://shopify.dev/docs/api/admin-graphql/latest/objects/publication) field that determines which products are visible to the customer when they visit the online store and checkout. Each `Catalog` interface also has a [`priceList`](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Catalog#field-pricelist) field that determines any price adjustments for its eligible contexts, such as a [`Market`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Market) or a [`CompanyLocation`](https://shopify.dev/docs/api/admin-graphql/latest/objects/CompanyLocation) for business-to-business (B2B) customers. ### Price lists For each [`PriceList`](https://shopify.dev/docs/api/admin-graphql/latest/objects/PriceList), a [`PriceListParent`](https://shopify.dev/docs/api/admin-graphql/latest/objects/PriceListParent) can be used to control prices using percentage adjustments. You can use the [`PriceListPrice`](https://shopify.dev/docs/api/admin-graphql/latest/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). ### Pricing-only catalogs A pricing-only catalog is a catalog without an associated publication. You can create one by calling the [`createCatalog`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/catalogcreate) mutation and omitting the publication field. Pricing-only catalogs are simpler than regular catalogs and are often the better choice if you do not need to manage publications. They are more efficient and easier to maintain for most pricing use cases. Read the [following section](#api-objects-and-relationships) to understand how pricing-only catalogs behave by default. ### 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, markets, and price list objects](https://shopify.dev/assets/assets/images/api/markets/new-markets-catalog-objects-p-FFowBG.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, company locations or retail locations to target sales. By creating a market, you can configure distinct, localized shopping experiences for customers. For example, you can configure currency, domains and languages, prices, published products, and theme customizations. | | `MarketConditions` | An attribute that qualifies a buyer for a market. For example, the region a buyer is located in, the company location they are purchasing on behalf of, or the retail location. | | `CompanyLocation` | A specified location or branch for a [B2B company](https://shopify.dev/docs/api/admin-graphql/latest/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 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/latest/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 you're [eligible to use the new Markets API](https://shopify.dev/docs/apps/build/markets/new-markets/merchant-eligibility), then you can manage multiple market conditions associated with a single buyer. For example, a buyer can be a Canadian customer and a B2B customer, and there can be multiple markets that meet both conditions in different ways. When resolving a price for a product in a given buyer context, we first need to determine which catalogs are applicable to the buyer's context, this is done by first prioritizing the markets that a buyer is in: * Catalogs that are directly connected to the buyer's company location * Company Location Markets * A Company Location Market Catalog that matches specific company locations * A Company Location Market Catalog that matches all company locations * Region Markets * A Market Catalog that matches specific regions * A Market Catalog that matches all regions * App Catalogs (e.g. The Online Store) For more information about how markets are prioritized, refer to [Market inheritance](https://shopify.dev/docs/apps/build/markets/new-markets/market-inheritance). After you've assessed which catalogs are applicable to the buyer's context, you can identify the catalogs that apply. * Only catalogs of the highest precedence are considered in catalog resolution. For example, if a buyer is logged into a B2B customer account, then only applicable B2B catalogs are considered. * If no catalogs are assigned to the highest precedence of the buyer, then Shopify defaults to the next most specific precedence. In this case, if a buyer is logged into a B2B customer account, but there are no company location catalogs defined, then Shopify falls back to region markets. In the case of a tie the lowest price is used. For example, you might have the following same markets - both with the same level of specificity - with two products. | Market name | Price list ID | Product A price | Product B price | | - | - | - | - | | Canada and United States | 1 | $20 | $10 | | Canada and Mexico | 2 | $15 | $12 | A buyer in Canada receives the price for Product A from Canada and Mexico, and the price for Product B from Canada and United Stated because they have the lowest price. 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 the 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/latest/objects/pricelistprice) isn't defined, then an adjusted relative price is calculated using the [`PriceListParent`](https://shopify.dev/docs/api/admin-graphql/latest/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 market has multiple catalogs, the user receives 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/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. *** ## Considerations * Multiple catalogs can be assigned to multiple markets. * Catalogs can be assigned to either a market or to a company location directly. * Market types have different levels of priority, with more specific markets having higher priority for pricing. * If a buyer's context matches multiple markets of the same priority, then the price is determined by the lowest price within the market's catalogs. * If a buyer's context matches a single market with multiple catalogs, then the price is determined by the lowest price within the market's catalogs. * Price adjustments are only applied to products that are included in the catalog's publication. *** ## Developer tools and resources Explore the following developer tools and resources to learn more about building with catalogs: [Catalog interface\ \ ](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Catalog) [Consult the GraphQL Admin API reference to learn more about the `Catalog` interface.](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Catalog) [PriceList object\ \ ](https://shopify.dev/docs/api/admin-graphql/latest/objects/PriceList) [Consult the GraphQL Admin API reference to learn more about the `PriceList` object.](https://shopify.dev/docs/api/admin-graphql/latest/objects/PriceList) [Shopify Markets preview\ \ ](https://shopify.dev/docs/apps/build/markets/new-markets/feature-preview) [Learn how to use the new Markets API to create and manage markets.](https://shopify.dev/docs/apps/build/markets/new-markets/feature-preview) *** * [How it works](https://shopify.dev/docs/apps/build/markets/new-markets/catalogs.md#how-it-works) * [Considerations](https://shopify.dev/docs/apps/build/markets/new-markets/catalogs.md#considerations) * [Developer tools and resources](https://shopify.dev/docs/apps/build/markets/new-markets/catalogs.md#developer-tools-and-resources)