Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Commit 5e2d15d

Browse files
andrewbessAndrii Beziazychnyi
andrewbess
authored and
Andrii Beziazychnyi
committed
#7367: Added the article "addProductsToCart mutation"
1 parent bbf8917 commit 5e2d15d

8 files changed

+347
-0
lines changed

‎src/_data/toc/graphql.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,10 @@ pages:
132132
- label: Using mutations
133133
url: /graphql/mutations/index.html
134134

135+
- label: addProductsToCart mutation
136+
url: /graphql/mutations/add-products-to-cart.html
137+
exclude_versions: ["2.3"]
138+
135139
- label: addBundleProductsToCart mutation
136140
url: /graphql/mutations/add-bundle-products.html
137141

‎src/_includes/graphql/entered-option-input.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Attribute | Data Type | Description
2+
--- | --- | ---
3+
`uid` | ID! | An encoded ID
4+
`value` | String! | Text the customer entered

‎src/guides/v2.4/graphql/mutations/add-bundle-products.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ contributor_name: Atwix
55
contributor_link: https://www.atwix.com/
66
---
77

8+
{:.bs-callout-warning}
9+
The `addBundleProductsToCart` mutation has been deprecated. Use the [addProductsToCart]({{page.baseurl}}/graphql/mutations/add-products-to-cart.html) mutation instead.
10+
811
Use the `addBundleProductsToCart` mutation to add bundle products to a specific cart.
912

1013
## Syntax

‎src/guides/v2.4/graphql/mutations/add-configurable-products.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@ group: graphql
33
title: addConfigurableProductsToCart mutation
44
---
55

6+
{:.bs-callout-warning}
7+
The `addConfigurableProductsToCart` mutation has been deprecated. Use the [addProductsToCart]({{page.baseurl}}/graphql/mutations/add-products-to-cart.html) mutation instead.
8+
69
Use the `addConfigurableProductsToCart` mutation to add configurable products to a specific cart.
710

811
## Syntax

‎src/guides/v2.4/graphql/mutations/add-downloadable-products.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ contributor_name: Atwix
55
contributor_link: https://www.atwix.com/
66
---
77

8+
{:.bs-callout-warning}
9+
The `addDownloadableProductsToCart` mutation has been deprecated. Use the [addProductsToCart]({{page.baseurl}}/graphql/mutations/add-products-to-cart.html) mutation instead.
10+
811
A downloadable product can be anything that you can deliver as a file, such as an eBook, music, video, software application, or an update. To add a downloadable product to a cart, you must provide the cart ID, the SKU, and the quantity. In some cases, you must include the IDs for downloadable product links. You can also optionally specify customizable options.
912

1013
## Syntax

‎src/guides/v2.4/graphql/mutations/add-products-to-cart.md

Lines changed: 324 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,324 @@
1+
---
2+
group: graphql
3+
title: addProductsToCart mutation
4+
redirect from:
5+
- /guides/v2.4/graphql/mutations/add-bundle-products.html
6+
- /guides/v2.4/graphql/mutations/add-configurable-products.html
7+
- /guides/v2.4/graphql/mutations/add-downloadable-products.html
8+
- /guides/v2.4/graphql/mutations/add-simple-products.html
9+
- /guides/v2.4/graphql/mutations/add-virtual-products.html
10+
---
11+
12+
In order to simplify the flow of adding different types of products to a cart, it is proposed to use a single mutation for all product types.
13+
14+
We implemented the single mutation "AddProductsToCart" from Magento 2.4.1.
15+
16+
The `addProductsToCart` mutation allows you to add any number of products to the cart at the same time.
17+
18+
To add products to a cart, you must provide the cart ID, the SKUs, and the quantities. You can also optionally provide customizable options.
19+
20+
## Syntax
21+
22+
```graphql
23+
mutation {
24+
addProductsToCart(
25+
cartId: String
26+
cartItems: [CartItemInput]
27+
) {
28+
AddProductsToCartOutput
29+
}
30+
}
31+
```
32+
33+
## Example usage
34+
35+
These examples show the minimal payload and a payload that includes customizable options.
36+
37+
### Add a product to a cart
38+
39+
The following example adds a product to a cart. The response contains the minimal payload contents of the customer's cart.
40+
41+
**Request:**
42+
43+
```graphql
44+
mutation {
45+
addProductsToCart(
46+
cartId: "HbpLADRmSo5h2dCdF85O5wCaVnrworKL"
47+
cartItems: [
48+
{
49+
quantity: 1
50+
sku: "24-MB04"
51+
}
52+
]
53+
) {
54+
cart {
55+
items {
56+
id
57+
product {
58+
name
59+
sku
60+
}
61+
quantity
62+
}
63+
}
64+
}
65+
}
66+
```
67+
68+
**Response:**
69+
70+
```json
71+
{
72+
"data": {
73+
"addProductsToCart": {
74+
"cart": {
75+
"items": [
76+
{
77+
"id": "346",
78+
"product": {
79+
"name": "Strive Shoulder Pack",
80+
"sku": "24-MB04"
81+
},
82+
"quantity": 1
83+
}
84+
]
85+
}
86+
}
87+
}
88+
}
89+
```
90+
91+
### Options
92+
93+
Each product may have options. An option can be of 2 types.
94+
95+
`selected_options` - predefined and selected by customer option. E.g. it can be customizable option: color: green, size: 28 or bundle option: Memory: 24M, Warranty: 1y, etc.
96+
97+
Add a product with selected options to a cart
98+
99+
**Request:**
100+
101+
```graphql
102+
mutation {
103+
addProductsToCart(
104+
cartId: "HbpLADRmSo5h2dCdF85O5wCaVnrworKL"
105+
cartItems: [
106+
{
107+
quantity: 1
108+
sku: "WSH12"
109+
selected_options: ["Y29uZmlndXJhYmxlLzkzLzExNA==","Y29uZmlndXJhYmxlLzE5OS8yMzI="]
110+
}
111+
]
112+
) {
113+
cart {
114+
items {
115+
id
116+
product {
117+
name
118+
sku
119+
}
120+
... on ConfigurableCartItem {
121+
configurable_options {
122+
id
123+
option_label
124+
value_id
125+
value_label
126+
}
127+
}
128+
quantity
129+
}
130+
}
131+
}
132+
}
133+
```
134+
135+
**Response:**
136+
137+
```json
138+
{
139+
"data": {
140+
"addProductsToCart": {
141+
"cart": {
142+
"items": [
143+
{
144+
"id": "348",
145+
"product": {
146+
"name": "Erika Running Short",
147+
"sku": "WSH12"
148+
},
149+
"configurable_options": [
150+
{
151+
"id": 93,
152+
"option_label": "Color",
153+
"value_id": 114,
154+
"value_label": "Green"
155+
},
156+
{
157+
"id": 199,
158+
"option_label": "Size",
159+
"value_id": 232,
160+
"value_label": "28"
161+
}
162+
],
163+
"quantity": 1
164+
}
165+
]
166+
}
167+
}
168+
}
169+
}
170+
```
171+
172+
`entered_options` - option entered by customer like: text field, image, etc.
173+
174+
Add a product with entered options to a cart
175+
176+
**Request:**
177+
178+
```graphql
179+
mutation {
180+
addProductsToCart(
181+
cartId: "HbpLADRmSo5h2dCdF85O5wCaVnrworKL"
182+
cartItems: [
183+
{
184+
quantity: 1
185+
sku: "24-WG03"
186+
entered_options: [{
187+
uid: "Y3VzdG9tLW9wdGlvbi81Mg=="
188+
value: "Test Engraving"
189+
}]
190+
}
191+
]
192+
) {
193+
cart {
194+
items {
195+
id
196+
product {
197+
name
198+
sku
199+
}
200+
... on SimpleCartItem {
201+
customizable_options {
202+
id
203+
label
204+
values {
205+
id
206+
value
207+
}
208+
}
209+
}
210+
quantity
211+
}
212+
}
213+
}
214+
}
215+
```
216+
217+
**Response:**
218+
219+
```json
220+
{
221+
"data": {
222+
"addProductsToCart": {
223+
"cart": {
224+
"items": [
225+
{
226+
"id": "350",
227+
"product": {
228+
"name": "Clamber Watch",
229+
"sku": "24-WG03"
230+
},
231+
"customizable_options": [
232+
{
233+
"id": 52,
234+
"label": "Engraving",
235+
"values": [
236+
{
237+
"id": 1184,
238+
"value": "Test Engraving"
239+
}
240+
]
241+
}
242+
],
243+
"quantity": 1
244+
}
245+
]
246+
}
247+
}
248+
}
249+
}
250+
```
251+
252+
We can consider `selected_option` and `entered_option` as a unique identifier. They meet the criteria:
253+
254+
- `selected_option` represents option value, while `entered_option` represents an option
255+
256+
- Uid is unique across different options
257+
258+
- Uid must be returned from the server
259+
260+
- Used by the client as is (opaque)
261+
262+
Selected options can be used for:
263+
264+
- Customizable options such a dropdown, radiobutton, checkbox, etc.
265+
266+
- Configurable product
267+
268+
- Bundle Product
269+
270+
- Downloadable product
271+
272+
- Grouped product
273+
274+
- Gift Card (amount)
275+
276+
Entered options:
277+
278+
- Customizable options such as text field, file, etc.
279+
280+
- Gift Card (custom amount, sender fields, recipient fields, message)
281+
282+
## Input attributes
283+
284+
The `AddProductsToCart` mutation must contain the following attributes:
285+
286+
Attribute | Data Type | Description
287+
--- | --- | ---
288+
`cartId` | String! | The unique ID that identifies the customer's cart
289+
`cartItems` | [[CartItemInput!]!](#CartItemInput) | Contains the cart item IDs and quantity of each item
290+
291+
### CartItemInput object {#CartItemInput}
292+
293+
The `CartItemInput` object must contain the following attributes:
294+
295+
{% include graphql/cart-item-input.md %}
296+
297+
### EnteredOptionInput object {#EnteredOptionInput}
298+
299+
The `EnteredOptionInput` object must contain the following attributes:
300+
301+
{% include graphql/entered-option-input.md %}
302+
303+
## Output attributes
304+
305+
The `AddProductsToCartOutput` object contains the `Cart` object.
306+
307+
Attribute | Data Type | Description
308+
--- | --- | ---
309+
`cart` |[Cart!](#CartObject) | Describes the contents of the specified shopping cart
310+
311+
### Cart object {#CartObject}
312+
313+
{% include graphql/cart-object.md %}
314+
315+
[Cart query output]({{page.baseurl}}/graphql/queries/cart.html#cart-output) provides more information about the `Cart` object.
316+
317+
## Errors
318+
319+
Code | Error | Description
320+
--- | --- | ---
321+
`PRODUCT_NOT_FOUND` | `Could not find a product with SKU "XXX"` | A product with the SKU specified in the argument `data`.`sku` does not exist.
322+
`NOT_SALABLE` | `Product that you are trying to add is not available.` | A requested product is not available
323+
`INSUFFICIENT_STOCK` | `This product is out of stock` | A requested product is out of stock
324+
`UNDEFINED` | `UNDEFINED` | If an error message no matched with any code

‎src/guides/v2.4/graphql/mutations/add-simple-products.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ redirect from:
55
- /guides/v2.3/graphql/reference/quote-add-simple-products.html
66
---
77

8+
{:.bs-callout-warning}
9+
The `addSimpleProductsToCart` mutation has been deprecated. Use the [addProductsToCart]({{page.baseurl}}/graphql/mutations/add-products-to-cart.html) mutation instead.
10+
811
The `addSimpleProductsToCart` mutation allows you to add any number of simple and group products to the cart at the same time.
912

1013
Simple products are physical products that do not have variations, such as color, size, or price. Group products are a set of simple standalone products that are assigned a unique SKU and are presented as a group. Each product in the group is purchased as a separate item.

‎src/guides/v2.4/graphql/mutations/add-virtual-products.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ redirect from:
55
- /guides/v2.3/graphql/reference/quote-add-virtual-products.html
66
---
77

8+
{:.bs-callout-warning}
9+
The `addVirtualProductsToCart` mutation has been deprecated. Use the [addProductsToCart]({{page.baseurl}}/graphql/mutations/add-products-to-cart.html) mutation instead.
10+
811
A virtual product represents a saleable item that is not physical, such as a membership, service, warranty, or subscription. Virtual products do not need to be shipped or downloaded, nor do they require stock management.
912

1013
The `addVirtualProductsToCart` mutation allows you to add multiple virtual products to the cart at the same time, but you cannot add other product types with this mutation. To add a virtual product to a cart, you must provide the cart ID, the SKU, and the quantity. You can also optionally provide customizable options.

0 commit comments

Comments
 (0)