diff --git a/_data/toc/graphql.yml b/_data/toc/graphql.yml index 54c013972ff..4b19941a6b2 100644 --- a/_data/toc/graphql.yml +++ b/_data/toc/graphql.yml @@ -227,6 +227,9 @@ pages: - label: Product interface implementations url: /graphql/product/product-interface-implementations.html + - label: ProductInterface + url: /graphql/product/product-interface.html + - label: CustomizableOptionInterface url: /graphql/product/customizable-option-interface.html diff --git a/guides/v2.3/graphql/product/product-interface.md b/guides/v2.3/graphql/product/product-interface.md index 4c4957ed25a..8b8266b337e 100644 --- a/guides/v2.3/graphql/product/product-interface.md +++ b/guides/v2.3/graphql/product/product-interface.md @@ -42,7 +42,9 @@ Attribute | Data type | Description `new_to_date` | String | The end date for new product listings `only_x_left_in_stock` | Float | The "Only X left Threshold" assigned to the product. This attribute is defined in the `InventoryGraphQl` module. `options_container` | String | If the product has multiple options, determines where they appear on the product page -`price` | ProductPrices | The price of an item. A `ProductPrice` object is returned. See [ProductPrices](#ProductPrices) for more information. +`price` | ProductPrices | Deprecated. Use `price_range` instead.
The price of an item. A `ProductPrice` object is returned +`price_range` | [PriceRange!](#PriceRange) | A `PriceRange` object, indicating the range of prices for the product +`price_tiers` | [TierPrice] | An array of `TierPrice` objects `product_links` | [ProductLinksInterface] | An array of [ProductLinks](#ProductLinks) objects `related_products` | [ProductInterface] | An array of related products `short_description` | ComplexTextValue | An object that contains a short description of the product. Its use depends on the store's theme. The object can include simple HTML tags @@ -55,8 +57,8 @@ Attribute | Data type | Description `swatch_image` | String | The file name of a swatch image. This attribute is defined in the `SwatchesGraphQl` module. `tax_class_id` | Int | An ID assigned to a tax class. This attribute is defined in the `TaxGraphQl` module. `thumbnail` | [ProductImage](#ProductImage) | An object that contains the URL and label for the product's thumbnail image -`tier_price` | Float | The price when tier pricing is in effect and the items purchased threshold has been reached -`tier_prices` | [ProductTierPrices] | An array of [ProductTierPrices](#ProductTier) objects +`tier_price` | Float | Deprecated. Use `price_tiers` instead. The price when tier pricing is in effect and the items purchased threshold has been reached +`tier_prices` | [ProductTierPrices] | Deprecated. Use `price_tiers` instead. An array of [ProductTierPrices](#ProductTier) objects `type_id` | String | One of `simple`, `virtual`, `bundle`, `downloadable`,`grouped`, `configurable` `updated_at` | String | The timestamp indicating when the product was last updated `upsell_products` | [ProductInterface] | An array of up-sell products @@ -68,15 +70,46 @@ Attribute | Data type | Description ### ProductPrices object {#ProductPrices} +{:.bs-callout-info} +The `ProductPrices` object has been deprecated. Use the `PriceRange` object instead. + The `ProductPrices` object contains the regular price of an item, as well as its minimum and maximum prices. Only composite products, which include bundle, configurable, and grouped products, can contain a minimum and maximum price. Attribute | Data Type | Description --- | --- | --- -`maximalPrice` | Price | Used for composite (bundle, configurable, grouped) products. This is the highest possible final price for all the options defined within a composite product. If you're specifying a price range, this would be the "to" value. -`minimalPrice` | Price | Used for composite (bundle, configurable, grouped) products. This is the lowest possible final price for all the options defined within a composite product. If you're specifying a price range, this would be the "from" value. -`regularPrice` | Price | The base price of a product. +`maximalPrice` | Price | Deprecated. Use `PriceRange.maximum_price` instead. Used for composite (bundle, configurable, grouped) products. This is the highest possible final price for all the options defined within a composite product. If you're specifying a price range, this would be the "to" value +`minimalPrice` | Price | Deprecated. Use `PriceRange.minimum_price` instead. Used for composite (bundle, configurable, grouped) products. This is the lowest possible final price for all the options defined within a composite product. If you're specifying a price range, this would be the "from" value +`regularPrice` | Price | Deprecated. Use `PriceRange.maximum_price` or `PriceRange.minimum_price` instead. The base price of a product + +### PriceRange object {#PriceRange} + +The `PriceRange` object defines the price range for a product. If a product only has a single price, the minimum and maximum price will be the same. + +Attribute | Data Type | Description +--- | --- | --- +`maximum_price` | ProductPrice | The highest possible final price for a product +`minimum_price` | ProductPrice | The lowest possible final price for a product + +### ProductPrice object {#ProductPrice} + +The `ProductPrice` object includes the regular price, final price, and the difference between those two prices. + +Attribute | Data Type | Description +--- | --- | --- +`discount` | ProductDiscount | The amount of the discount applied to the product. It represents the difference between the `final_price` and `regular_price` +`final_price`| Money! | The price of the product after applying discounts +`regular_price` | Money! | The regular price of the product, without any applied discounts -#### Price object {#Price} +### ProductDiscount object {#ProductDiscount} + +The `ProductDiscount` object expresses the discount applied to a product as a fixed amount, such as $5, and as a percentage, such as 10%. The discount originates from special pricing or a catalog price rule. + +Attribute | Data Type | Description +--- | --- | --- +`amount_off` | Float | The actual value of the discount +`percent_off` | Float | The discount expressed as a percentage + +### Price object {#Price} The `Price` object defines the price of a product as well as any tax-related adjustments. @@ -178,15 +211,28 @@ Attribute | Type | Description ### ProductTierPrices object {#ProductTier} +{:.bs-callout-info} +The `ProductTierPrices` object and all of its attributes have been deprecated. Use `TierPrice` instead. + The `ProductTierPrices` object defines a tier price, which is a quantity discount offered to a specific customer group. Attribute | Type | Description --- | --- | --- -`customer_group_id` | Int | The ID of the customer group -`percentage_value` | Float | The percentage discount of the item -`qty` | Float | The number of items that must be purchased to qualify for tier pricing -`value` | Float | The price of the fixed price item -`website_id` | Int | The ID assigned to the website +`customer_group_id` | Int | Deprecated. There is no replacement because this value is not relevant for the storefront. The ID of the customer group +`percentage_value` | Float | Deprecated. Use `TierPrice.discount` instead. The percentage discount of the item +`qty` | Float | Deprecated. Use `TierPrice.quantity` instead. The number of items that must be purchased to qualify for tier pricing +`value` | Float | Deprecated. Use `TierPrice.final_price` instead. The price of the fixed price item +`website_id` | Int | Deprecated. There is no replacement because this value is not relevant for the storefront. The ID assigned to the website + +### TierPrice object {#TierPrice} + +The `TierPrice` object defines a tier price, which is a price based on the quantity purchased. + +Attribute | Type | Description +--- | --- | --- +`discount` | ProductDiscount | The price discount applied to this tier +`final_price`| Money! | The price of the product at this tier +`quantity` | Float | The minimum number of items that must be purchased to qualify for this price tier ### Website object {#websiteObject} diff --git a/guides/v2.3/graphql/queries/cart.md b/guides/v2.3/graphql/queries/cart.md index 9f37da83317..0e95f7e2926 100644 --- a/guides/v2.3/graphql/queries/cart.md +++ b/guides/v2.3/graphql/queries/cart.md @@ -523,6 +523,183 @@ The `3T1free` rule is applied first, and Magento returns the price of a single s } ``` +### Tier price example + +In the following example, tier prices has been established for product `24-UG01` and `24-UG05`, as shown in the following table: + +Product | Quantity | Fixed/Discount | Amount +--- | --- | --- | --- | +24-UG01 | 5 | Discount | 5% +24-UG01 | 10 | Discount | 10% +24-UG01 | 15 | Discount | 15% +24-UG05 | 5 | Fixed | $16 +24-UG05 | 10 | Fixed | $11 + +The cart in the example contains 12 units of `24-UG05` and 8 units of `24-UG-01`, so the price of `24-UG05` is $11, and the price of `24-UG01` is $18.05 (5% off). + +**Request** + +```graphql +query { + cart(cart_id: "v7jYJUjvPeHbdMJRcOfZIeQhs2Xc2ZKT"){ + items { + id + quantity + product{ + name + sku + price_tiers { + quantity + final_price { + value + } + discount { + amount_off + percent_off + } + } + } + prices{ + price{ + value + } + } + } + prices { + discounts { + label + amount { + value + } + } + subtotal_excluding_tax { + value + } + applied_taxes { + label + amount { + value + } + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "cart": { + "items": [ + { + "id": "65", + "quantity": 12, + "product": { + "name": "Go-Get'r Pushup Grips", + "sku": "24-UG05", + "price_tiers": [ + { + "quantity": 5, + "final_price": { + "value": 16 + }, + "discount": { + "amount_off": 3, + "percent_off": 15.79 + } + }, + { + "quantity": 10, + "final_price": { + "value": 11 + }, + "discount": { + "amount_off": 8, + "percent_off": 42.11 + } + } + ] + }, + "prices": { + "price": { + "value": 11 + } + } + }, + { + "id": "66", + "quantity": 8, + "product": { + "name": "Quest Lumaflex™ Band", + "sku": "24-UG01", + "price_tiers": [ + { + "quantity": 5, + "final_price": { + "value": 18.05 + }, + "discount": { + "amount_off": 0.95, + "percent_off": 5 + } + }, + { + "quantity": 10, + "final_price": { + "value": 17.1 + }, + "discount": { + "amount_off": 1.9, + "percent_off": 10 + } + }, + { + "quantity": 15, + "final_price": { + "value": 16.15 + }, + "discount": { + "amount_off": 2.85, + "percent_off": 15 + } + } + ] + }, + "prices": { + "price": { + "value": 18.05 + } + } + } + ], + "prices": { + "discounts": [ + { + "label": "200", + "amount": { + "value": 55.28 + } + } + ], + "subtotal_excluding_tax": { + "value": 276.4 + }, + "applied_taxes": [ + { + "label": "US-MI-*-Rate 1", + "amount": { + "value": 18.24 + } + } + ] + } + } + } +} +``` + ## Input attributes Attribute | Data Type | Description diff --git a/guides/v2.3/graphql/queries/category.md b/guides/v2.3/graphql/queries/category.md index ea8fd1a5194..3ae4feae53f 100644 --- a/guides/v2.3/graphql/queries/category.md +++ b/guides/v2.3/graphql/queries/category.md @@ -7,89 +7,23 @@ redirect_from: The `category` query allows you to search for a single category definition or the entire category tree. To return multiple category levels in a single call, define the response so that it contains up to ten nested `children` options. You cannot return the entire category tree if it contains more than 10 sublevels unless the `queryDepth` parameter in the GraphQL `di.xml` file has been reconfigured. -## Query structure +## Syntax -``` text +```graphql category ( id: int ): CategoryTree ``` -### Input attributes +## Example usage -Attribute | Data type | Description ---- | --- | --- -`id` | Int | The category ID to use as the starting point of your category search. - -### Output attributes {#Categories} - -The query returns a `CategoryTree` object, which implements `CategoryInterface`. It can contain the following top-level attributes: - -Attribute | Data type | Description ---- | --- | --- -`breadcrumbs` | `Breadcrumb` | A `Breadcrumb` object contains information the categories that comprise the breadcrumb trail for the specified category -`children` | `CategoryTree` | A `CategoryTree` object that contains information about a child category. You can specify up to 10 levels of child categories. -`created_at`| String | Timestamp indicating when the category was created -`default_sort_by`| String | The attribute to use for sorting -`description`| String | An optional description of the category -`id` | Int | An ID that uniquely identifies the category -`level` | Int | Indicates the depth of the category within the tree -`name`| String | The display name of the category -`path_in_store`| String | Category path in the store -`path`| String | The path to the category, as a string of category IDs, separated by slashes (/). For example, `1/2/20` -`position`| Int | The position of the category relative to other categories at the same level in tree -`product_count`| Int | The number of products in the category -`products()` | `CategoryProducts` | The list of products assigned to the category -`updated_at`| String | Timestamp indicating when the category was updated -`url_key`| String | The url key assigned to the category -`url_path`| String | The url path assigned to the category -`url_suffix` | String | The part of the URL that is appended to the `url_key`, such as `.html`. This attribute is defined in the `CatalogUrlRewriteGraphQl` module - -#### CategoryProducts object - -The `products` attribute can contain the following attributes: - -Attribute | Data type | Description ---- | --- | --- -`currentPage` | Int | Specifies which page of results to return. The default value is 1. -`pageSize` | Int | Specifies the maximum number of results to return at once. This attribute is optional. The default value is 20. -`sort` | `ProductSortInput` | Specifies which attribute to sort on, and whether to return the results in ascending or descending order. [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) describes sort orders. +### Return the category tree of a top-level category -The `CategoryProducts` object contains the following attributes: - -Attribute | Data type | Description ---- | --- | --- -`items` | [ProductInterface] | An array of products that are assigned to the category. See [ProductInterface]({{ page.baseurl }}/graphql/queries/products.html#ProductInterface) for more information. -`page_info` | `SearchResultPageInfo` | An object that includes the `page_info` and `currentPage` values specified in the query -`total_count` | Int | The number of products returned - -#### Breadcrumb object - -A breadcrumb trail is a set of links that shows customers where they are in relation to other pages in the -store. - -Attribute | Data type | Description ---- | --- | --- -`category_id` | Int | An ID that uniquely identifies the category -`category_level` | Int | Indicates the depth of the category within the tree -`category_name` | String | The display name of the category -`category_url_key` | String | The url key assigned to the category - -#### CategoryTree object - -This `CategoryTree` object contains information about the next level of subcategories of the category specified in the original query. - -Attribute | Data type | Description ---- | --- | --- -`children` | [CategoryTree] | An array containing the next level of subcategories - -## Sample Queries - -The following query returns information about category ID `20` and four levels of subcategories. In the sample data, category ID `20` is assigned to the "Women" category. +The following query returns information about category ID `20` and four levels of subcategories. In the sample data, category ID `20` is assigned to the `Women` category. **Request** -``` text +```graphql { category(id: 20) { products { @@ -206,11 +140,13 @@ The following query returns information about category ID `20` and four levels o } ``` -The following query returns breadcrumb information about the women's tops category (`id` = 25). +### Return breadcrumb information + +The following query returns breadcrumb information about the women's `Tops` category (`id` = 25). **Request** -``` text +```graphql { category ( id: 25 @@ -242,16 +178,87 @@ The following query returns breadcrumb information about the women's tops catego "category_id": 20, "category_name": "Women", "category_level": 2, - "category_url_key": "women" + "category_url_key": "women", + "category_url_path": "women" }, { "category_id": 21, "category_name": "Tops", "category_level": 3, - "category_url_key": "tops-women" + "category_url_key": "tops-women", + "category_url_path": "women/tops-women" } ] } } } ``` + +## Input attributes + +Attribute | Data type | Description +--- | --- | --- +`id` | Int | The category ID to use as the starting point of your category search. + +## Output attributes {#Categories} + +The query returns a `CategoryTree` object, which implements `CategoryInterface`. It can contain the following top-level attributes: + +Attribute | Data type | Description +--- | --- | --- +`breadcrumbs` | `Breadcrumb` | A `Breadcrumb` object contains information about the categories that comprise the breadcrumb trail for the specified category +`children` | `CategoryTree` | A `CategoryTree` object that contains information about a child category. You can specify up to 10 levels of child categories +`created_at`| String | Timestamp indicating when the category was created +`default_sort_by`| String | The attribute to use for sorting +`description`| String | An optional description of the category +`id` | Int | An ID that uniquely identifies the category +`level` | Int | Indicates the depth of the category within the tree +`name`| String | The display name of the category +`path_in_store`| String | The category path in the store +`path`| String | The path to the category, as a string of category IDs, separated by slashes (/). For example, `1/2/20` +`position`| Int | The position of the category relative to other categories at the same level in tree +`product_count`| Int | The number of products in the category +`products()` | `CategoryProducts` | The list of products assigned to the category +`updated_at`| String | Timestamp indicating when the category was updated +`url_key`| String | The URL key assigned to the category +`url_path`| String | The URL path assigned to the category +`url_suffix` | String | The part of the URL that is appended to the `url_key`, such as `.html`. This attribute is defined in the `CatalogUrlRewriteGraphQl` module + +### CategoryProducts object + +The `products` attribute can contain the following attributes: + +Attribute | Data type | Description +--- | --- | --- +`currentPage` | Int | Specifies which page of results to return. The default value is 1 +`pageSize` | Int | Specifies the maximum number of results to return at once. This attribute is optional. The default value is 20 +`sort` | `ProductSortInput` | Specifies which attribute to sort on, and whether to return the results in ascending or descending order. [Searches and pagination in GraphQL]({{ page.baseurl }}/graphql/search-pagination.html) describes sort orders + +The `CategoryProducts` object contains the following attributes: + +Attribute | Data type | Description +--- | --- | --- +`items` | [[ProductInterface]]({{ page.baseurl }}/graphql/product/product-interface.html) | An array of products that are assigned to the category +`page_info` | `SearchResultPageInfo` | An object that includes the `page_info` and `currentPage` values specified in the query +`total_count` | Int | The number of products returned + +### Breadcrumb object + +A breadcrumb trail is a set of links that shows customers where they are in relation to other pages in the +store. + +Attribute | Data type | Description +--- | --- | --- +`category_id` | Int | An ID that uniquely identifies the category +`category_level` | Int | Indicates the depth of the category within the tree +`category_name` | String | The display name of the category +`category_url_key` | String | The url key assigned to the category +`category_url_path` | String | The URL path of the category + +### CategoryTree object + +This `CategoryTree` object contains information about the next level of subcategories of the category specified in the original query. + +Attribute | Data type | Description +--- | --- | --- +`children` | [CategoryTree] | An array containing the next level of subcategories diff --git a/guides/v2.3/graphql/queries/products.md b/guides/v2.3/graphql/queries/products.md index 1d0bb04318e..71af313d7fa 100644 --- a/guides/v2.3/graphql/queries/products.md +++ b/guides/v2.3/graphql/queries/products.md @@ -513,6 +513,100 @@ query { } ``` +### Return minimum and maximum prices and discount information + +In the following example, a catalog price rule that provides a 10% discount on all fitness equipment is in effect. The product queried, `24-WG080`, is the Sprite Yoga Companion Kit bundle product. This product has two user-selected options that cause the price to vary. If you choose to query a product that is not a composite (bundle, group, or configurable) product, the minimum and maximum prices are the same. + +**Request** + +```graphql +{ + products(filter: {sku: {eq: "24-WG080"}}, sort: {name: ASC}) { + items { + name + sku + price_range { + minimum_price { + regular_price { + value + currency + } + final_price { + value + currency + } + discount { + amount_off + percent_off + } + } + maximum_price { + regular_price { + value + currency + } + final_price { + value + currency + } + discount { + amount_off + percent_off + } + } + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "products": { + "items": [ + { + "name": "Sprite Yoga Companion Kit", + "sku": "24-WG080", + "price_range": { + "minimum_price": { + "regular_price": { + "value": 61, + "currency": "USD" + }, + "final_price": { + "value": 61, + "currency": "USD" + }, + "discount": { + "amount_off": 0, + "percent_off": 0 + } + }, + "maximum_price": { + "regular_price": { + "value": 77, + "currency": "USD" + }, + "final_price": { + "value": 77, + "currency": "USD" + }, + "discount": { + "amount_off": 0, + "percent_off": 0 + } + } + } + } + ] + } + } +} +``` + ### Include website information with `products` query results {#inclWebsiteInfoExample} The [ProductInterface]({{ page.baseurl }}/graphql/queries/products.html#ProductInterface) can include information about the `Website` object.