Support different pricing models using the price list API

A price list is a set of rules that changes product pricing based on certain conditions. For example, you can make a price list that determines the prices for products based on the location of the customer. Over time, price lists could power other use cases.

The prices defined using price lists are automatically applied in the online store and during checkout. These prices are also applied to product variants, and they can have discounts applied to them using discount codes, automatic discounts, or checkout scripts.

This tutorial shows you how you can use price lists to control prices by using percentage adjustments, or by specifying a fixed price per product variant.

Requirements

Scopes

To use the GraphQL mutations, your app needs to request the following access scopes for a Shopify store:

  • write_products: Allows an app to write products.

Price lists

For each PriceList, a PriceListParent can be used to control prices using percentage adjustments. You can use PriceListPrice objects to represent a final, fixed price for a single product variant. A context rule defines the facts about a customer that must be true for a price list to be applicable.

Price list objects diagram

API object Description
Price list A list of prices for different products displayed to the customer based on context. A customer could see a single price list or be eligible for multiple price lists.
Price list price The price for a single product variant associated with this price list. 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 there is no fixed price list price for a variant, a relative price list price is calculated based on pricing adjustments 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. The origin type of a price list price reflects whether it is fixed or relative. If a fixed price list price has been configured for a product variant, then it takes precedence over any other adjustments defined at the price list level.
Product variant Represents the variant associated with a price list.
Price list parent An object used to specify adjustments to a store's initial prices, such as percentage-based price changes.
Price list adjustment A change applied to a store's initial prices, such as a percentage-based adjustment. Adjustments work in conjunction with price rounding, and exchange rate settings.
Price list context rule A set of facts about a customer used to determine the customer's eligibility for the price list.

Pricing prioritization

Price lists are displayed to customers through the online store and checkout, based on context rules. Context rules represent certain criteria about the customer that must be true for a price list to apply. After the price list is applied, pricing is determined by priority as described in the diagram below:

Price list flow diagram

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

  • 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.
  • If a price list price isn't defined, then an adjusted relative price can be specified using PriceListParent that applies a percentage-based change. 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 neither a price list price nor an adjusted price is specified, then the initial price (the product variant price) is applied using the selected currency rules. The example uses a foreign exchange rate of 1.3.

Foreign exchange and rounding rules

If the customer's country doesn't match the store currency and no price list rules have been configured, then foreign exchange and rounding is applied to the initial price using either automatic or manual multi-currency rules.

However, if there is no match, and an adjusted relative price has been applied using a price rule, then foreign exchange and rounding is applied along with the adjustment. If a fixed price list is applicable, then foreign exchange and rounding isn't applied, because the prices are already in the desired currency.

The following table illustrates when foreign exchange and rounding is applicable:

Pricing type Foreign exchange and rounding
Product variant Checkmark icon
Adjusted relative price Checkmark icon
Fixed price list price

Understanding selling plan pricing policies

Selling plan pricing policies work in conjunction with price lists.

If a selling plan has a 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 example scenario depicted in the diagram, the pricing request includes a selling plan that reduces the price. A 15% PERCENTAGE adjustment type is applied to the PriceListPrice of $35.00. The final price is $29.40.

Pricing engine diagram

Query a single price list and its prices

To see how a price list is configured, you can query priceList. In the following example, the response body returns the available prices, including the value of the percentage-based adjustment.

When querying a priceList, the following fields are of interest:

  • id: A globally unique identifier for the price list.
  • name: The unique name of the price list, used as a human-readable identifier.
  • currency: The three letter currency code for fixed prices that's associated with this price list.
  • parent: The value and type of percentage adjustments applied to initial prices via the price list.
  • countries: The country code for the price list.
  • prices: A list of prices associated with the price list.

Request

POST /admin/api/2021-04/graphql.json

View response

JSON response:

Paginate through all price lists and prices

The originType on each price indicates whether the price is fixed, or relative to the initial price. Relative prices are returned in the store currency.

Request

POST /admin/api/2021-04/graphql.json

View response

JSON response:

Create a new price list

You can use the priceListCreate mutation to create a new price list for a country. This lets you sell your products with international pricing. As part of the mutation, you can set the name, a percentage-based adjustment, currency, and country.

Adjustments can either reduce the initial prices with PERCENTAGE_DECREASE, or raise the initial prices with PERCENTAGE_INCREASE. The adjustment value is either a positive decimal number or zero.

Request

POST /admin/api/2021-04/graphql.json

Variables:

View response

JSON response:

Update an existing price list

You can use the priceListUpdate mutation to update an existing price list for a country. This lets you change product pricing on a per country basis. As part of the mutation, you can change the name, percentage-based adjustment, currency, and country.

Request

POST /admin/api/2021-04/graphql.json

Variables:

View response

JSON response:

Update a partial set of prices on a price list

You can use the priceListFixedPricesAdd mutation to set a fixed price for specific product variants. This lets you change product pricing on a per country basis. You need to set fixed prices on each product variant, and you need to specify the price, compareAtPrice, and variantId as part of the mutation.

If a price for a given variant already exists on the price list, then it is replaced.

Request

POST /admin/api/2021-04/graphql.json

Variables:

View response

JSON response:

The response includes the variants with updated prices.

Delete a partial set of prices on a price list

You can use the priceListFixedPricesDelete mutation to delete a partial set of prices on a price list. After it's deleted, the prices no longer apply for products in the country. To delete prices, you need to specify the variant ID. The maximum amount of variant IDs that can be specified in the array is 250.

Request

POST /admin/api/2021-04/graphql.json

Variables:

View response

JSON response:

The response includes the IDs of the updated prices.

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 country. To delete a price list, you need to specify the price list ID. When deleting a priceList, all of the priceListPrices are also deleted.

Request

POST /admin/api/2021-04/graphql.json

Variables:

View response

JSON response:

The response includes the IDs of the updated prices.

Errors

Mis-match between the country and currency on a price list

Request

POST /admin/api/2021-04/graphql.json

Variables:

View response

JSON response:

The response includes the IDs of the updated prices.

Two different price lists with the same country mapping

Request

POST /admin/api/2021-04/graphql.json

Variables:

View response

JSON response:

The response includes the IDs of the updated prices.

Request

POST /admin/api/2021-04/graphql.json

Variables:

View response

JSON response:

The response includes the IDs of the updated prices.

Price list with multiple country mappings

Request

POST /admin/api/2021-04/graphql.json

Variables:

View response

JSON response:

The response includes the IDs of the updated prices.

Current limitations

  • There are no webhook events associated with changes to price lists.

Next steps