diff --git a/src/_data/toc/graphql.yml b/src/_data/toc/graphql.yml index dd978ca377f..5beffba005e 100644 --- a/src/_data/toc/graphql.yml +++ b/src/_data/toc/graphql.yml @@ -111,6 +111,10 @@ pages: - label: isEmailAvailable query url: /graphql/queries/is-email-available.html + - label: productReviewRatingsMetadata query + url: /graphql/queries/product-review-ratings-metadata.html + exclude_versions: ["2.3"] + - label: products query url: /graphql/queries/products.html @@ -192,6 +196,10 @@ pages: - label: createPayPalExpressToken mutation url: /graphql/mutations/create-paypal-express-token.html + - label: createProductReview mutation + url: /graphql/mutations/create-product-review.html + exclude_versions: ["2.3"] + - label: deleteCustomerAddress mutation url: /graphql/mutations/delete-customer-address.html diff --git a/src/_includes/graphql/customer-output-24.md b/src/_includes/graphql/customer-output-24.md index 185b8786e96..65377603b01 100644 --- a/src/_includes/graphql/customer-output-24.md +++ b/src/_includes/graphql/customer-output-24.md @@ -26,6 +26,7 @@ Attribute | Data Type | Description `middlename` |String | The customer's middle name `orders()` | {{ customeroutput_text }} | A list of the customer's placed orders{{ crossref_text }} `prefix` | String | An honorific, such as Dr., Mr., or Mrs. +`reviews(pageSize: Int = 20 currentPage: Int = 1)` | ProductReviews! | The list of reviews of the product `reward_points` | RewardPoints | Details about the customer's reward points `suffix` | String | A value such as Sr., Jr., or III `taxvat` | String | The customer's Tax/VAT number (for corporate customers) diff --git a/src/_includes/graphql/product-review.md b/src/_includes/graphql/product-review.md new file mode 100644 index 00000000000..5123474cd05 --- /dev/null +++ b/src/_includes/graphql/product-review.md @@ -0,0 +1,20 @@ +The `ProductReview` object contains details about a product review. It contains the following attributes. + +Attribute | Data Type | Description +--- | --- | --- +`average_rating` | Float! | The average rating for product review +`created_at` | String! | Date indicating when the review was created +`nickname` | String! | The customer's nickname. Defaults to the customer name, if logged in +`product` | ProductInterface! | Contains details about the reviewed product +`ratings_breakdown` | [ProductReviewRating!]! | An array of ratings by rating category, such as quality, price, and value +`summary` | String! | The summary (title) of the review +`text` | String! | The review text + +### ProductReviewRating attributes {#ProductReviewRating} + +The `ProductReviewRating` object contains the following attributes. + +Attribute | Data Type | Description +--- | --- | --- +`name` | String! | The label assigned to an aspect of a product that is being rated, such as quality or price +`value` | String! | The rating value given by customer. By default, possible values range from 1 to 5 diff --git a/src/guides/v2.4/graphql/mutations/create-product-review.md b/src/guides/v2.4/graphql/mutations/create-product-review.md new file mode 100644 index 00000000000..f5170f5a39e --- /dev/null +++ b/src/guides/v2.4/graphql/mutations/create-product-review.md @@ -0,0 +1,120 @@ +--- +group: graphql +title: createProductReview mutation +--- + +The `createProductReview` mutation adds a review for the specified product. Use the [`productReviewRatingsMetadata` query]({{page.baseurl}}/graphql/queries/product-review-ratings-metadata.html) to return a list of rating categories and possible values. + +## Syntax + +`createProductReview(input: CreateProductReviewInput!): CreateProductReviewOutput!` + +## Example usage + +In the following example, Roni gives product `WH08` four stars overall, three stars for value, and four stars for quality. + +**Request:** + +```graphql +mutation { + createProductReview( + input: { + sku: "WH08", + nickname: "Roni", + summary: "Great looking sweatshirt", + text: "This sweatshirt looks and feels great. The zipper sometimes sticks a bit.", + ratings: [ + { + id: "NA==", + value_id: "MTk=" + }, { + id: "MQ==", + value_id: "NA==" + }, { + id: "Mg==", + value_id: "OA==" + } + ] + } +) { + review { + nickname + summary + text + average_rating + ratings_breakdown { + name + value + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "createProductReview": { + "review": { + "nickname": "Roni", + "summary": "Great looking sweatshirt", + "text": "This sweatshirt looks and feels great. The zipper sometimes sticks a bit.", + "average_rating": 73.33, + "ratings_breakdown": [ + { + "name": "Quality", + "value": "4" + }, + { + "name": "Value", + "value": "3" + }, + { + "name": "Overall", + "value": "4" + } + ] + } + } + } +} +``` + +## Input attributes + +The `CreateProductReviewInput` input object defines the product review. + +### CreateProductReviewInput attributes {#CreateProductReviewInput} + +The `CreateProductReviewInput` object contains the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`nickname` | String! | The customer's nickname. Defaults to the customer name, if logged in +`ratings` | [ProductReviewRatingInput!]! | Ratings details by category. e.g price: 5, quality: 4 etc +`sku` | String! | The SKU of the reviewed product +`summary` | String! | The summary (title) of the review +`text` | String! | The review text. + +### ProductReviewRatingInput attributes {#ProductReviewRatingInput} + +The `ProductReviewRatingInput` object contains the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`id` | String! | An encoded rating ID +`value_id` | String! | An encoded rating value ID + +## Output attributes + +The `CreateProductReviewOutput` output object contains the following attribute: + +Attribute | Data Type | Description +--- | --- | --- +`review` | ProductReview! | Contains the completed product review + +### ProductReview attributes {#ProductReview} + +{% include graphql/product-review.md %} diff --git a/src/guides/v2.4/graphql/product/product-interface.md b/src/guides/v2.4/graphql/product/product-interface.md index 2343ad3dd6a..83c3f2d8f81 100644 --- a/src/guides/v2.4/graphql/product/product-interface.md +++ b/src/guides/v2.4/graphql/product/product-interface.md @@ -46,7 +46,10 @@ Attribute | Data type | Description `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 +`rating_summary` | Float! | The average of all the ratings given to the product `related_products` | [ProductInterface] | An array of related products +`review_count` | Int! | The total count of all the reviews given to the product +`reviews(pageSize: Int = 20 currentPage: Int = 1)` | [ProductReviews!](#ProductReviews) | The list of reviews of the product `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 `sku` | String | A number or code assigned to a product to identify the product, options, price, and manufacturer `small_image` | [ProductImage](#ProductImage) | An object that contains the URL and label for the small image used on catalog pages @@ -153,6 +156,19 @@ Attribute | Data Type | Description `code` | PriceAdjustmentCodesEnum | One of `tax`, `weee`, or `weee_tax`. `description` | PriceAdjustmentDescriptionEnum | Indicates whether the entity described by the code attribute is included or excluded from the adjustment. +#### ProductReviews object {#ProductReviews} + +`ProductReviews` contains an array of reviews written about the product. + +Attribute | Data Type | Description +--- | --- | --- +`items` | [ProductReview]! | An array of product reviews +`page_info` | [SearchResultPageInfo!]({{page.baseurl}}/graphql/queries/products.html#SearchResultPageInfo) | Metadata for pagination rendering + +#### ProductReview object {#ProductReview} + +{% include graphql/product-review.md %} + #### ProductLinks object {#ProductLinks} `ProductLinks` contains information about linked products, including the link type and product type of each item. diff --git a/src/guides/v2.4/graphql/queries/customer.md b/src/guides/v2.4/graphql/queries/customer.md index 8f75a5f657d..7a657ce1e9e 100644 --- a/src/guides/v2.4/graphql/queries/customer.md +++ b/src/guides/v2.4/graphql/queries/customer.md @@ -501,6 +501,39 @@ Attribute | Data Type | Description {% include graphql/customer-orders-output.md %} +#### ProductReviews object {#ProductReviews} + +`ProductReviews` contains an array of reviews written about the product. + +Attribute | Data Type | Description +--- | --- | --- +`items` | [ProductReview]! | An array of product reviews +`page_info` | [SearchResultPageInfo!]({{page.baseurl}}/graphql/queries/products.html#SearchResultPageInfo) | Metadata for pagination rendering + +#### ProductReview object {#ProductReview} + +{% include graphql/product-review.md %} + +### Wishlist attributes {#Wishlist} + +Attribute | Data type | Description +--- | --- | --- +`items` | [[WishlistItem](#wishlistitem)] | An array of items in the customer's wish list +`items_count` | Int | The number of items in the wish list +`id` | ID | The unique identifier of the wish list +`sharing_code` | String | An encrypted code that Magento uses to link to the wish list +`updated_at` | String | The time of the last modification to the wish list + +#### WishlistItem attributes {#wishlistitem} + +Attribute | Data type | Description +--- | --- | --- +`added_at` | String | The time when the customer added the item to the wish list +`description` | String | The customer's comment about this item +`id` | Int | The wish list item ID +`product` | [ProductInterface]({{ page.baseurl }}/graphql/product/product-interface.html) | The ProductInterface contains attributes that are common to all types of products. Note that descriptions may not be available for custom and EAV attributes +`qty` | Float | The quantity of this wish list item + ### Store credit attributes In {{site.data.var.ee}}, the merchant can assign store credit to customers. Magento maintains the history of all changes to the balance of store credit available to the customer. The customer must be logged in to access the store credit history and balance. diff --git a/src/guides/v2.4/graphql/queries/product-review-ratings-metadata.md b/src/guides/v2.4/graphql/queries/product-review-ratings-metadata.md new file mode 100644 index 00000000000..8baf082bc39 --- /dev/null +++ b/src/guides/v2.4/graphql/queries/product-review-ratings-metadata.md @@ -0,0 +1,155 @@ +--- +group: graphql +title: productReviewRatingsMetadata query +--- + +The `productReviewRatingsMetadata` query returns the active ratings attributes and the values each rating can have. In Luma, these values are one star through five stars. + +Use the [`createProductReview` mutation]({{page.baseurl}}/graphql/mutations/create-product-review.html) to add a product review. + +## Syntax + +`productReviewRatingsMetadata: ProductReviewRatingsMetadata!` + +## Example usage + +The following query returns the metadata for all active ratings attributes. In this example, the default `Rating` attribute has been renamed to `Overall`, and the `Quality` and `Value` attributes have been enabled. + +**Request:** + +```graphql +query { + productReviewRatingsMetadata { + items { + id + name + values { + value_id + value + } + } + } +} +``` + +**Response:** + +```json +{ + "data": { + "productReviewRatingsMetadata": { + "items": [ + { + "id": "NA==", + "name": "Overall", + "values": [ + { + "value_id": "MTY=", + "value": "1" + }, + { + "value_id": "MTc=", + "value": "2" + }, + { + "value_id": "MTg=", + "value": "3" + }, + { + "value_id": "MTk=", + "value": "4" + }, + { + "value_id": "MjA=", + "value": "5" + } + ] + }, + { + "id": "MQ==", + "name": "Quality", + "values": [ + { + "value_id": "MQ==", + "value": "1" + }, + { + "value_id": "Mg==", + "value": "2" + }, + { + "value_id": "Mw==", + "value": "3" + }, + { + "value_id": "NA==", + "value": "4" + }, + { + "value_id": "NQ==", + "value": "5" + } + ] + }, + { + "id": "Mg==", + "name": "Value", + "values": [ + { + "value_id": "Ng==", + "value": "1" + }, + { + "value_id": "Nw==", + "value": "2" + }, + { + "value_id": "OA==", + "value": "3" + }, + { + "value_id": "OQ==", + "value": "4" + }, + { + "value_id": "MTA=", + "value": "5" + } + ] + } + ] + } + } +} +``` + +## Input attributes + +Not applicable + +## Output attributes {#Categories} + +The `ProductReviewRatingsMetadata` output object contains the `items` object. + +Attribute | Data type | Description +--- | --- | --- +`items` | [ProductReviewRatingMetadata!]! | A list of product reviews, sorted by position + +### ProductReviewRatingMetadata attributes {#ProductReviewRatingMetadata} + +The `ProductReviewRatingMetadata` object contains the following attributes. + +Attribute | Data type | Description +--- | --- | --- +`id` | String! | | An encoded rating ID +`name` | String! | The label assigned to an aspect of a product that is being rated, such as quality or price +`values` | [ProductReviewRatingValueMetadata!]! | A list of product review ratings, sorted by position + +### ProductReviewRatingValueMetadata attributes {#ProductReviewRatingValueMetadata} + +The `ProductReviewRatingValueMetadata` object contains the following attributes. + +Attribute | Data type | Description +--- | --- | --- +value | String! | A ratings scale, such as the number of stars awarded +value_id | String! | An encoded rating value ID diff --git a/src/guides/v2.4/graphql/queries/store-config.md b/src/guides/v2.4/graphql/queries/store-config.md index bd7f218d128..4c444a8a567 100644 --- a/src/guides/v2.4/graphql/queries/store-config.md +++ b/src/guides/v2.4/graphql/queries/store-config.md @@ -242,9 +242,10 @@ The `StoreConfig` object can contain the following attributes. Attribute | Data Type | Description | Default or example value --- | --- | --- | --- `absolute_footer` | String | Contains scripts that must be included in the HTML before the closing `` tag | null -`allow_gift_wrapping_on_order` | String | Indicates if a gift wrapping can be added for the entire order. Possible values: 1 (Yes) and 0 (No) | 1 -`allow_gift_wrapping_on_order_items` | String | Indicates if a gift wrapping can be added for individual order items. Possible values: 1 (Yes) and 0 (No) | 1 +`allow_gift_wrapping_on_order` | String | Indicates whether gift wrapping can be added for the entire order. Possible values: 1 (Yes) and 0 (No) | 1 +`allow_gift_wrapping_on_order_items` | String | Indicates whether gift wrapping can be added for individual order items. Possible values: 1 (Yes) and 0 (No) | 1 `allow_gift_receipt` | String | Indicates if the gift sender has the option to send a gift receipt. Possible values: 1 (Yes) and 0 (No) | 1 +`allow_guests_to_write_product_reviews` | String | Indicates whether guest users can write product reviews. Possible values: 1 (Yes) and 0 (No) | 1 `allow_items` | String | Allows gift messages for order items. Possible values: 1 (Yes) and 0 (No).
Configuration path: sales/gift_options/allow_items | 0 `allow_order` | String | Allows gift messages at the order level. Possible values: 1 (Yes) and 0 (No).
Configuration path: sales/gift_options/allow_order | 0 `allow_printed_card` | String | Indicates if a printed card can accompany an order. Possible values: 1 (Yes) and 0 (No) | 1 @@ -302,6 +303,7 @@ Attribute | Data Type | Description | Default or example value `payment_payflowpro_cc_vault_active` | String | Payflow Pro vault status | `0` (inactive) or `1` (active) `printed_card_price` | String | The default price of a printed card that accompanies an order | 10 `product_fixed_product_tax_display_setting` | [FixedProductTaxDisplaySettings](#FixedProductTaxDisplaySettings) | Corresponds to the **Display Prices On Product View Page** field. It indicates how Fixed Product Taxes information is displayed on product pages | FPT_DISABLED +`product_reviews_enabled` | String | Indicates whether product reviews are enabled. Possible values: 1 (Yes) and 0 (No) | 1 `product_url_suffix` | String | The suffix applied to product pages, such as `.htm` or `.html` | `.html` `required_character_classes_number` | String | The number of different character classes required in a password (lowercase, uppercase, digits, special characters).
Configuration path: customer/password/required_character_classes_number | 2 `root_category_id` | Int | The ID of the root category | 2