Skip to main content

Manage B2B catalogs

Caution

Starting in API version 2023-04, the PriceList.contextRule field will be deprecated. If you have an existing app that uses the contextRule field, then you should migrate to catalogs.

Catalogs are used to determine the products that are published to customers in different contexts. For example, a business-to-business (B2B) catalog might specify that customers ordering for a specific B2B company location can purchase only the t-shirt products in the store at a 30% discount.

In this guide, you'll learn how to build price lists and publications, and associate them with catalogs to control prices and publishing for a specific B2B company location.

Note

If you're using the new Markets API, currently in developer preview, then consider managing your B2B catalogs with markets instead of linking them directly to the company location. For more information, refer to the About Shopify Markets developer preview.

Anchor to RequirementsRequirements

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

You can associate a price list with the catalog to determine the prices that are shown to customers ordering for that B2B company location. If a price list isn't associated with the catalog, then customers ordering for this B2B company location 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 2: Associate a publicationStep 2: Associate a publication

Caution

If a publication isn't associated with a B2B catalog, then customers logged into their B2B accounts won't see any products for that location.

The publication determines which products are published to customers that are eligible for the catalog.

If you have an existing publication, then you can use the catalogUpdate mutation to associate a publication or make other changes to a catalog.

To create and associate a new publication, use the publicationCreate mutation:

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

GraphQL mutation

mutation publicationCreate {
publicationCreate(input: {
catalogId: "gid://shopify/CompanyLocationCatalog/CATALOG-ID"
defaultState: ALL_PRODUCTS
}) {
publication {
id
catalog { id title }
}
userErrors {
code
field
message
}
}
}

JSON response

{
"data": {
"publicationCreate": {
"publication": {
"id": "gid://shopify/Publication/123",
"catalog": {
"id": "gid://shopify/CompanyLocationCatalog/1",
"title": "Catalog for Company's European location"
}
},
"userErrors": []
}
}
}

Anchor to Add products to the publicationAdd products to the publication

After you create a publication, you can add products to the publication with the publicationUpdate mutation:

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

GraphQL mutation

mutation publicationUpdate {
publicationUpdate(
id: "gid://shopify/Publication/1",
input: {
publishablesToAdd: ["gid://shopify/Product/1"],
publishablesToRemove: ["gid://shopify/Product/2"]
}) {
publication {
products(first: 10) {
edges {
node {
id
}
}
}
}
userErrors {
field
code
message
}
}
}

JSON response

{
"data": {
"publicationUpdate": {
"publication": {
"products": {
"edges": [
{
"node": {
"id": "gid://shopify/Product/1"
}
}
]
}
},
"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 Next stepsNext steps

Was this page helpful?