docs(#549): accompanying prices in GQL

FgForrest · Jun 3, 2024 · efc4795 · efc4795
1 parent 0f02512
commit efc4795
Show file tree

Hide file tree

Showing 10 changed files with 266 additions and 27 deletions.
diff --git a/.../en/query/requirements/examples/fetching/allPricesForSaleFieldWithReferencePrices.graphql b/.../en/query/requirements/examples/fetching/allPricesForSaleFieldWithReferencePrices.graphql
@@ -0,0 +1,33 @@
+{
+  queryProduct(
+    filterBy: {
+      entityPrimaryKeyInSet: [
+        103911
+      ],
+      priceInCurrency: EUR,
+      priceInPriceLists: [
+        "employee-basic-price",
+        "basic"
+      ]
+    }
+  ) {
+    recordPage {
+      data {
+        primaryKey
+        attributes {
+          code
+        }
+        allPricesForSale {
+          priceWithoutTax
+          priceWithTax
+          taxRate
+          referencePrice: accompanyingPrice(priceLists: "basic") {
+            priceWithoutTax
+            priceWithTax
+            taxRate
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/...ents/examples/fetching/allPricesForSaleFieldWithReferencePrices.graphql.json.md b/...ents/examples/fetching/allPricesForSaleFieldWithReferencePrices.graphql.json.md
@@ -0,0 +1,174 @@
+```json
+{
+  "data": [
+    {
+      "primaryKey": 103911,
+      "attributes": {
+        "code": "apple-ipad-10-2-10th-generation-2022"
+      },
+      "allPricesForSale": [
+        {
+          "priceWithoutTax": "395.87",
+          "priceWithTax": "479.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "412.4",
+            "priceWithTax": "499.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "395.87",
+          "priceWithTax": "479.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "412.4",
+            "priceWithTax": "499.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "395.87",
+          "priceWithTax": "479.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "412.4",
+            "priceWithTax": "499.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "395.87",
+          "priceWithTax": "479.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "412.4",
+            "priceWithTax": "499.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "412.4",
+          "priceWithTax": "499.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "429.75",
+            "priceWithTax": "520.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "412.4",
+          "priceWithTax": "499.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "429.75",
+            "priceWithTax": "520.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "412.4",
+          "priceWithTax": "499.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "429.75",
+            "priceWithTax": "520.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "412.4",
+          "priceWithTax": "499.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "429.75",
+            "priceWithTax": "520.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "412.4",
+          "priceWithTax": "499.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "429.75",
+            "priceWithTax": "520.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "412.4",
+          "priceWithTax": "499.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "429.75",
+            "priceWithTax": "520.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "412.4",
+          "priceWithTax": "499.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "429.75",
+            "priceWithTax": "520.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "412.4",
+          "priceWithTax": "499.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "429.75",
+            "priceWithTax": "520.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "436.36",
+          "priceWithTax": "528.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "454.55",
+            "priceWithTax": "550.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "436.36",
+          "priceWithTax": "528.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "454.55",
+            "priceWithTax": "550.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "436.36",
+          "priceWithTax": "528.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "454.55",
+            "priceWithTax": "550.0",
+            "taxRate": "21.0"
+          }
+        },
+        {
+          "priceWithoutTax": "436.36",
+          "priceWithTax": "528.0",
+          "taxRate": "21.0",
+          "referencePrice": {
+            "priceWithoutTax": "454.55",
+            "priceWithTax": "550.0",
+            "taxRate": "21.0"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
diff --git a/...ion/user/en/query/requirements/examples/fetching/attributeContentAll.evitaql.md b/...ion/user/en/query/requirements/examples/fetching/attributeContentAll.evitaql.md
@@ -1,5 +1,5 @@
 | entityPrimaryKey | code      | visibility | published                     | changed                   | status   | order |
 | ---------------- | --------- | ---------- | ----------------------------- | ------------------------- | -------- | ----- |
-| 64703            | 'samsung' | 'VISIBLE'  | 2024-04-15T17:41:24.074+02:00 | 2024-02-25T14:35:38+01:00 | 'ACTIVE' | ⎆     |
+| 64703            | 'samsung' | 'VISIBLE'  | 2024-04-12T11:46:10.137+02:00 | 2024-02-25T14:35:38+01:00 | 'ACTIVE' | ⎆     |
 
 ###### **Page** 1/1 **(Total number of results: 1)**
diff --git a/documentation/user/en/query/requirements/examples/fetching/attributeContentAll.graphql b/documentation/user/en/query/requirements/examples/fetching/attributeContentAll.graphql
@@ -15,8 +15,8 @@
           visibility
           published
           validity
-          status
           changed
+          status
           order
         }
       }

diff --git a/...n/user/en/query/requirements/examples/fetching/attributeContentAll.rest.json.md b/...n/user/en/query/requirements/examples/fetching/attributeContentAll.rest.json.md
@@ -14,7 +14,7 @@
           "changed": "2024-02-25T14:35:38+01:00",
           "code": "samsung",
           "order": -1,
-          "published": "2024-04-15T17:41:24.074+02:00",
+          "published": "2024-04-12T11:46:10.137+02:00",
           "status": "ACTIVE",
           "visibility": "VISIBLE"
         }

diff --git a/documentation/user/en/query/requirements/examples/fetching/dataInLocalesWithFilter.graphql b/documentation/user/en/query/requirements/examples/fetching/dataInLocalesWithFilter.graphql
@@ -13,10 +13,10 @@
         attributesGlobal: attributes {
           code
         }
-        attributesEn: attributes(locale: en) {
+        attributesCs: attributes(locale: cs) {
           name
         }
-        attributesCs: attributes(locale: cs) {
+        attributesEn: attributes(locale: en) {
           name
         }
       }

diff --git a/...ntation/user/en/query/requirements/examples/fetching/priceContentRespectingFilter.graphql b/...ntation/user/en/query/requirements/examples/fetching/priceContentRespectingFilter.graphql
@@ -22,6 +22,11 @@
           priceWithTax
           taxRate
         }
+        reference: price(priceList: "reference") {
+          priceWithoutTax
+          priceWithTax
+          taxRate
+        }
       }
     }
   }

diff --git a/...ents/examples/fetching/priceField.graphql → ...iceForSaleFieldWithReferencePrice.graphql b/...ents/examples/fetching/priceField.graphql → ...iceForSaleFieldWithReferencePrice.graphql
@@ -21,11 +21,11 @@
           priceWithoutTax
           priceWithTax
           taxRate
-        }
-        referencePrice: price(priceList: "basic") {
-          priceWithoutTax
-          priceWithTax
-          taxRate
+          referencePrice: accompanyingPrice(priceLists: "basic") {
+            priceWithoutTax
+            priceWithTax
+            taxRate
+          }
         }
       }
     }

diff --git a/...mples/fetching/priceField.graphql.json.md → ...leFieldWithReferencePrice.graphql.json.md b/...mples/fetching/priceField.graphql.json.md → ...leFieldWithReferencePrice.graphql.json.md
@@ -9,12 +9,12 @@
       "priceForSale": {
         "priceWithoutTax": "88.43",
         "priceWithTax": "107.0",
-        "taxRate": "21.0"
-      },
-      "referencePrice": {
-        "priceWithoutTax": "92.56",
-        "priceWithTax": "112.0",
-        "taxRate": "21.0"
+        "taxRate": "21.0",
+        "referencePrice": {
+          "priceWithoutTax": "92.56",
+          "priceWithTax": "112.0",
+          "taxRate": "21.0"
+        }
       }
     }
   ]

diff --git a/documentation/user/en/query/requirements/fetching.md b/documentation/user/en/query/requirements/fetching.md
@@ -1194,21 +1194,25 @@ flag indicating that there are multiple prices for sale available.
 
 </Note>
 
-### Price
+### Accompanying prices
 
-The `price` field returns a single specific price (even non-sellable one) based on the arguments passed: `priceList` and `currency`.
-This is useful, for example, if you want to fetch a reference non-sellable price to display next to the entity's main price for sale.
-If more than one price is found for the specified price list and currency, the first valid one is returned
-(the validity is compared either to the current date time or against the `priceValidIn` filter constraint, if present).
+There may be times when you need not only the concrete [price for sale](#prices-for-sale), but also it's accompanying prices, e.g.
+reference price (usually not sellable, but displayed for comparison because it's usually higher than the price for sale). 
+This calculation becomes quite complex when we need to handle prices with different inner record handling 
+([LOWEST_PRICE, SUM](https://evitadb.io/documentation/query/filtering/price#price-for-sale-selection-in-a-nutshell)).
+In such cases, the accompanying prices must correctly reflect the prices for sale for each inner record.
 
-The `currency` field can be omitted if there is a `priceInCurrency` constraint in the filter, but the `priceList` argument is
-required. The idea behind this is that you probably would want to use the same currency for all prices in the result, but you probably
-don't want the reference price to be in the same price list as the main price for sale price, because that would most likely
-return the same price.
+You can easily calculate these prices with the `accompanyingPrice` field within the `priceForSale` or `allPricesForSale` fields.
+This way the requested accompanying price will always refer to the parent price for sale (even a custom one). The only 
+possible argument is `priceLists`, which defines for which price lists the accompanying price should be calculated 
+(the order of the price lists defines a priority in the same way as for the `priceForSale` and `allPricesForSale` fields).
+Other parameters will be inherited from the parent price for sale request.
+
+The following query requests calculation of price for sale as well as a reference price for the calculated price for sale:
 
 <SourceCodeTabs langSpecificTabOnly>
 
-[Getting entity with price for sale as well as reference price](/documentation/user/en/query/requirements/examples/fetching/priceField.graphql)
+[Getting entity with price for sale as well as reference price](/documentation/user/en/query/requirements/examples/fetching/priceForSaleFieldWithReferencePrice.graphql)
 </SourceCodeTabs>
 
 <Note type="info">
@@ -1220,12 +1224,35 @@ return the same price.
 
 The query returns the following price for sale and reference price of the `Product` entity:
 
-<MDInclude sourceVariable="data.queryProduct.recordPage">[The result of an entity fetched with its price for sale and reference price](/documentation/user/en/query/requirements/examples/fetching/priceField.graphql.json.md)</MDInclude>
+<MDInclude sourceVariable="data.queryProduct.recordPage">[The result of an entity fetched with its price for sale and reference price](/documentation/user/en/query/requirements/examples/fetching/priceForSaleFieldWithReferencePrice.graphql.json.md)</MDInclude>
 
 As you can see, the price for sale as well as custom reference price are returned.
 
 </Note>
 
+The next query is almost identical to the previous one, except that it calculates all the prices for sale and their reference prices for
+inner records:
+
+<SourceCodeTabs langSpecificTabOnly>
+
+[Getting entity with all prices for sale as well as reference prices](/documentation/user/en/query/requirements/examples/fetching/allPricesForSaleFieldWithReferencePrices.graphql)
+</SourceCodeTabs>
+
+<Note type="info">
+
+<NoteTitle toggles="true">
+
+##### The result of an entity fetched with its prices for sale and reference prices
+</NoteTitle>
+
+The query returns the following all prices for sale and references price of the `Product` entity:
+
+<MDInclude sourceVariable="data.queryProduct.recordPage">[The result of an entity fetched with its prices for sale and reference prices](/documentation/user/en/query/requirements/examples/fetching/allPricesForSaleFieldWithReferencePrices.graphql.json.md)</MDInclude>
+
+As you can see, the prices for sale as well as custom reference prices are returned.
+
+</Note>
+
 ### Prices
 
 The `prices` field returns all prices of the entity. Both sellable and non-sellable.