Support different pricing models
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 guide shows you how you can use price lists to control prices by using percentage adjustments, or by specifying a fixed price for each product variant.
RequirementsAnchor link to section titled "Requirements"
- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
write_productsaccess scope. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
- You've learned about the requirements for stores to set product prices by country.
- You've created products and product variants in your store.
How it worksAnchor link to section titled "How it works"
PriceListParent can be used to control prices using percentage adjustments. You can use the
PriceListPrice object 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: 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 the price list. The origin type of a price list price reflects whether it is fixed or relative.
- Fixed 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 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.
- Relative price list: If there's no fixed price list price for a variant, then 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.
Product variant: The variant associated with a price list.
Price list parent: Specifies 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 prioritizationAnchor link to section titled "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:
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 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 rulesAnchor link to section titled "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.
Selling plan pricing policiesAnchor link to section titled "Selling plan pricing policies"
Selling plan pricing policies work in conjunction with price lists:
- If a selling plan has a
SellingPlanPricingPolicyAdjustmentTypewith a value of either
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.
Step 1: Create a new price listAnchor link to section titled "Step 1: Create a new price list"
You can use the
priceListCreate mutation to create a new price list for a market. 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 market ID.
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.
Step 2: Query price lists and pricesAnchor link to section titled "Step 2: Query price lists and prices"
To see how a price list is configured, you can use the
priceList query to retrieve a single price list and its prices. In the following example, the response body returns the available prices, including the value of the percentage-based adjustment.
You can use the priceLists query to retrieve all prices list 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.
Step 3: Update an existing price listAnchor link to section titled "Step 3: Update an existing price list"
You can use the
priceListUpdate mutation to update an existing price list for a market. This lets you change product pricing on a per market basis. As part of the mutation, you can change the name, percentage-based adjustment, currency, and market ID.
Step 4: Update a partial set of prices on a price listAnchor link to section titled "Step 4: 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 market basis. You need to set fixed prices on each product variant, and you need to specify the
variantId as part of the mutation.
If a price for a given variant already exists on the price list, then it is replaced.
Step 5: Delete a partial set of prices on a price list (optional)Anchor link to section titled "Step 5: Delete a partial set of prices on a price list (optional)"
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 market. 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.
Step 6: Delete a price list (optional)Anchor link to section titled "Step 6: Delete a price list (optional)"
You can use the
priceListDelete mutation to delete a price list, so that it no longer applies for products in that market. To delete a price list, you need to specify the price list ID. When deleting a
priceList, all of the
priceListPrices are also deleted.
Step 7: Troubleshoot errors (optional)Anchor link to section titled "Step 7: Troubleshoot errors (optional)"
The following example shows a mis-match between the market and currency on a price list:
The following examples show two different price lists with the same market mapping:
- Learn about automatic and manual exchange rate conversion.