Support different pricing models

• Your app can make authenticated requests to the GraphQL Admin API.
• Your app has the write_products access 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.

For each PriceList, a 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.

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.

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 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.

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.

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.

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.

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 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.

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.

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.

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.