Skip to content

Commit ce8e15a

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

8 files changed

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