Commerce pricing queries

Author: AugustMiller

docs/commerce/5.x/system/pricing-rules.md

@@ -6,9 +6,9 @@ Pricing rules are sets of [conditions](#conditions) and [actions](#actions) that
 The catalog pricing system replaces [sales](sales.md) from earlier versions of Commerce. If you upgraded your store from 4.x to 5.x and had already configured one or more sales, you will retain access to them—but we strongly recommend migrating your sales into pricing rules.
 :::
 
-Catalog pricing is computed and stored in the database when its underlying data changes. Prices can also be manually refreshed at any time (or on a schedule) with the `commerce/pricing-catalog/generate` console command.
+Catalog pricing is computed and stored in the database when the underlying data changes. Prices can also be manually refreshed at any time (or on a schedule) with the `commerce/pricing-catalog/generate` console command. The resulting pricing information is joined in with normal variant queries and available transparently on the returned elements—even when rules produce customer-specific pricing!
 
-The resulting pricing information is joined in with normal variant queries and available transparently on the returned elements—even when rules produce customer-specific pricing!
+This also means that you can accurately [sort and filter](#pricing-queries) based on effective prices in variant queries.
 
 To create a pricing rule, visit <Journey path="Commerce, Store Management, Pricing Rules" />, and click **New catalog pricing rule**.
 
@@ -98,3 +98,47 @@ A guest would pay <del>{{ myVariant.price|commerceCurrency }}</del> {{ myVariant
 The pricing catalog and discounts both operate on preestablished criteria and actions. In situations where a price needs to be dynamically calculated (say, from customer input in the form of [custom fields](orders-carts.md#field-layout) or [line item options](../development/cart.md#line-item-options-and-notes)), Commerce gives you complete control over pricing and cart contents via its [events system](../extend/events.md).
 
 Read about [dynamically changing line item prices](kb:dynamically-customizing-line-item-prices) in the Knowledge Base.
+
+## Querying Prices
+
+Price data is always returned when executing [variant queries](products-variants.md#querying-variants). You can order any query by price, like this:
+
+```twig{6}
+{# Fetch variants featured in a given article: #}
+{% set variants = craft.variants()
+  .relatedTo({
+    sourceElement: entry,
+  })
+  .orderBy('price DESC')
+  .all() %}
+```
+
+Substitute `promotionalPrice` or `salePrice` to explicitly order by those resolved values.
+
+::: warning
+In general, `salePrice` will produce the most reliable and useful sorting. When using `promotionalPrice`, variants with no base promotional price defined will sort based on your database’s handling of `null` values, and may require an additional criteria like `['promotionalPrice IS NOT NULL', 'promotionalPrice DESC']` or `promotionalPrice DESC NULLS LAST` to ensure they appear at the end (or beginning) of the results.
+:::
+
+Variants can also be filtered by price, using values compatible with <craft5:craft\helpers\Db::parseNumericParam()>:
+
+```twig
+{% set dollarOrLess = craft.variants()
+  .price('<= 1')
+  .all() %}
+```
+
+To return variants with effective promotional pricing (a promotional price less than its base price), use the `.onPromotion()` query param:
+
+```twig
+{% set saleItems = craft.variants()
+  .onPromotion(true)
+  .all() %}
+```
+
+::: tip
+See our [Listing Products On Sale](kb:listing-products-on-sale) article for some examples of advanced price-based queries.
+:::
+
+This behavior approximates variants’ `.getOnPromotion()` method, but performs the comparisons directly in the database (rather than loading every variant and comparing them in memory)!
+
+It is currently only possible to directly sort and filter _products_ by their default variant’s price—but you can always use the [`hasVariant` param](products-variants.md#product-hasvariant) to build more sophisticated variant-based criteria.