diff --git a/_data/toc/graphql.yml b/_data/toc/graphql.yml index dff22fbbb42..55a5f970293 100644 --- a/_data/toc/graphql.yml +++ b/_data/toc/graphql.yml @@ -86,8 +86,48 @@ pages: - label: GroupedProduct endpoint url: /graphql/reference/grouped-product.html - - label: Quote endpoint + - label: Quote endpoint (cart query) url: /graphql/reference/quote.html + children: + + - label: addSimpleProductsToCart mutation + url: /graphql/reference/quote-add-simple-products.html + + - label: addVirtualProductsToCart mutation + url: /graphql/reference/quote-add-virtual-products.html + + - label: applyCouponToCart mutation + url: /graphql/reference/quote-apply-coupon.html + + - label: createEmptyCart mutation + url: /graphql/reference/quote-create-cart.html + + - label: placeOrder mutation + url: /graphql/reference/quote-place-order.html + + - label: removeCouponFromCart mutation + url: /graphql/reference/quote-remove-coupon.html + + - label: removeItemFromCart mutation + url: /graphql/reference/quote-remove-item.html + + - label: setBillingAddressesOnCart mutation + url: /graphql/reference/quote-set-billing-address.html + + - label: setGuestEmailOnCart mutation + url: /graphql/reference/quote-set-guest-email.html + + - label: setPaymentMethodOnCart mutation + url: /graphql/reference/quote-payment-method.html + + - label: setShippingAddressesOnCart mutation + url: /graphql/reference/quote-set-shipping-address.html + + - label: setShippingMethodsOnCart mutation + url: /graphql/reference/quote-shipping-method.html + + - label: updateCartItems mutation + url: /graphql/reference/quote-update-cart-items.html - label: Sales endpoint url: /graphql/reference/sales.html diff --git a/_includes/graphql/cart-address-input.md b/_includes/graphql/cart-address-input.md new file mode 100644 index 00000000000..dc182767944 --- /dev/null +++ b/_includes/graphql/cart-address-input.md @@ -0,0 +1,12 @@ +Attribute | Data Type | Description +--- | --- | --- +`city` | String! | The city specified for the billing or shipping address +`company` | String | The company specified for the billing or shipping address +`country_code` | String! | The country code and label for the billing or shipping address +`firstname` | String! | The customer's first name +`lastname` | String! | The customer's last name +`postcode` | String | The postal code for the billing or shipping address +`region` | String | The region code and label for the billing or shipping address +`save_in_address_book` | Boolean! | Specifies whether to save the address (`True`/`False`) +`street` | [String]! | An array containing the street for the billing or shipping address +`telephone` | String | The telephone number for the billing or shipping address \ No newline at end of file diff --git a/_includes/graphql/cart-item-input.md b/_includes/graphql/cart-item-input.md new file mode 100644 index 00000000000..ff44c8f8d1d --- /dev/null +++ b/_includes/graphql/cart-item-input.md @@ -0,0 +1,4 @@ +Attribute | Data Type | Description +--- | --- | --- +`quantity` | Float! | The quantity of the item to add to the cart +`sku` | String! | The sku of the product to be added to the cart \ No newline at end of file diff --git a/_includes/graphql/cart-object.md b/_includes/graphql/cart-object.md new file mode 100644 index 00000000000..73ad0a7fa30 --- /dev/null +++ b/_includes/graphql/cart-object.md @@ -0,0 +1,18 @@ +Attribute | Data Type | Description +--- | --- | --- +`applied_coupon` | [`AppliedCoupon`][AppliedCoupon] | The `AppliedCoupon` object contains the `code` text attribute, which specifies the coupon code +`available_payment_methods` | [AvailablePaymentMethod][AvailablePaymentMethod] | Available payment methods +`billing_address` | [BillingCartAddress][BillingCartAddress] | Contains the billing address specified in the customer's cart +`email` | String | The customer's email address +`items` | [CartItemInterface][CartItemInterface] | Contains the items in the customer's cart +`prices` | [CartPrices][CartPrices] | Contains subtotals and totals +`selected_payment_method` | [SelectedPaymentMethod][SelectedPaymentMethod] | Selected payment method +`shipping_addresses` | [ShippingCartAddress][ShippingCartAddress] | Contains one or more shipping addresses + +[AppliedCoupon]: {{page.baseurl}}/graphql/reference/quote.html#AppliedCoupon +[AvailablePaymentMethod]: {{page.baseurl}}/graphql/reference/quote.html#AvailablePaymentMethod +[BillingCartAddress]: {{page.baseurl}}/graphql/reference/quote.html#BillingCartAddress +[CartItemInterface]: {{page.baseurl}}/graphql/reference/quote.html#CartItemInterface +[CartPrices]: {{page.baseurl}}/graphql/reference/quote.html#CartPrices +[SelectedPaymentMethod]: {{page.baseurl}}/graphql/reference/quote.html#SelectedPaymentMethod +[ShippingCartAddress]: {{page.baseurl}}/graphql/reference/quote.html#ShippingCartAddress diff --git a/_includes/graphql/customizable-option-input.md b/_includes/graphql/customizable-option-input.md new file mode 100644 index 00000000000..4ec894093cb --- /dev/null +++ b/_includes/graphql/customizable-option-input.md @@ -0,0 +1,4 @@ +Attribute | Data Type | Description +--- | --- | --- +`id` | Int! | A unique ID assigned to the customizable option +`value_string` | String! | A value assigned to the the customizable option \ No newline at end of file diff --git a/guides/v2.3/graphql/reference/configurable-product.md b/guides/v2.3/graphql/reference/configurable-product.md index 62a5dffab53..ad1f2f9961b 100644 --- a/guides/v2.3/graphql/reference/configurable-product.md +++ b/guides/v2.3/graphql/reference/configurable-product.md @@ -720,7 +720,7 @@ Attribute | Type | Description ### Example usage -The following example adds two black Teton Pullover Hoodies size extra-small to the specified shopping cart. The `cart_id` used in this example was [generated]({{ page.baseurl }}/graphql/reference/quote.html#createEmptyCart) by creating an empty cart. +The following example adds two black Teton Pullover Hoodies size extra-small to the specified shopping cart. The `cart_id` used in this example was [generated]({{ page.baseurl }}/graphql/reference/quote-create-cart.html) by creating an empty cart. **Request** diff --git a/guides/v2.3/graphql/reference/quote-add-simple-products.md b/guides/v2.3/graphql/reference/quote-add-simple-products.md new file mode 100644 index 00000000000..21f26a9d10f --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-add-simple-products.md @@ -0,0 +1,195 @@ +--- +group: graphql +title: addSimpleProductsToCart mutation +--- + +Simple products are physical products that do not have variations, such as color, size, or price. The `addSimpleProductsToCart` mutation allows you to add multiple simple products to the cart at the same time, but you cannot add other product types with this mutation. To add a simple product to a cart, you must provide the cart ID, the SKU, and the quantity. You can also optionally provide customizable options. + +{:.bs-callout .bs-callout-info} +The mutation for [adding configurable products]({{page.baseurl}}/graphql/reference/configurable-product.html) is defined in the `ConfigurableProductGraphQl` module. + +## Syntax + +`mutation: {addSimpleProductsToCart(input: AddSimpleProductsToCartInput): {AddSimpleProductsToCartOutput}}` + +## Example usage + +These examples show the minimal payload and a payload that includes customizable options. + +### Add a simple product to a cart + +The following example adds a simple product to a cart. The response contains the entire contents of the customer's cart. + +**Request** + +```text +mutation { + addSimpleProductsToCart( + input: { + cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG", + cart_items: [ + { + data: { + quantity: 1 + sku: "24-MB04" + } + } + ] + } + ) { + cart { + items { + id + product { + name + sku + } + quantity + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "addSimpleProductsToCart": { + "cart": { + "items": [ + { + "id": "13", + "product": { + "name": "Strive Shoulder Pack", + "sku": "24-MB04" + }, + "quantity": 1 + } + ] + } + } + } +} +``` + +### Add a simple product with customizable options to a cart + +If a product has a customizable option, you can specify the option's value in the `addSimpleProductsToCart` request. + +**Request** + +``` text +mutation { + addSimpleProductsToCart (input: { + cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG", + cart_items: { + data: { + sku: "simple" + quantity: 1 + }, + customizable_options: [ + { + id: 121 + value_string: "field value" + } + ] + } + }) { + cart { + items { + product { + name + } + quantity + ... on SimpleCartItem { + customizable_options { + label + values { + value + } + } + } + } + } + } +} +``` + +**Response** + +```text +{ + "data": { + "addSimpleProductsToCart": { + "cart": { + "items": [ + { + "product": { + "name": "simple" + }, + "quantity": 1, + "customizable_options": [ + { + "label": "Field Option", + "values": [ + { + "value": "field value" + } + ] + } + ] + } + ] + } + } + } +} +``` + +## Input attributes + +The top-level `AddSimpleProductsToCartInput` object is listed first. All child objects are listed in alphabetical order. + +### AddSimpleProductsToCartInput object {#AddSimpleProductsToCartInput} + +The `AddSimpleProductsToCartInput` object must contain the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer's cart +`cart_items` | [SimpleProductCartItemInput!](#SimpleProductCartItemInput) | Contains the cart item IDs and quantity of each item + +### CartItemInput object {#CartItemInputSimple} + +The `CartItemInput` object must contain the following attributes: + +{% include graphql/customizable-option-input.md %} + +### CustomizableOptionInput object {#CustomizableOptionInputSimple} + +The `CustomizableOptionInput` object must contain the following attributes: + +{% include graphql/customizable-option-input.md %} + +### SimpleProductCartItemInput object {#SimpleProductCartItemInput} + +The `SimpleProductCartItemInput` object must contain the following attributes: + +`customizable_options` |[[CustomizableOptionInputSimple]](#CustomizableOptionInputSimple) | An array that defines customizable options for the product +`data` | [CartItemInput!](#CartItemInputSimple) | An object containing the `sku` and `quantity` of the product. + +## Output attributes + +The `AddSimpleProductsToCartOutput` object contains the `Cart` object. + +Attribute | Data Type | Description +--- | --- | --- +`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart + +### Cart object {#CartObject} + +{% include graphql/cart-object.md %} + +[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object. diff --git a/guides/v2.3/graphql/reference/quote-add-virtual-products.md b/guides/v2.3/graphql/reference/quote-add-virtual-products.md new file mode 100644 index 00000000000..9bbbeeba0df --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-add-virtual-products.md @@ -0,0 +1,130 @@ +--- +group: graphql +title: addVirtualProductsToCart mutation +--- + +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. + +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. + +{:.bs-callout .bs-callout-info} +The mutation for [adding configurable products]({{page.baseurl}}/graphql/reference/configurable-product.html) is defined in the `ConfigurableProductGraphQl` module. + +## Syntax + +`mutation: {addVirtualProductsToCart(input: AddVirtualProductsToCartInput): {AddVirtualProductsToCartOutput}}` + +## Example usage + +The Luma sample data does not include any virtual products. The following example requires that you create a virtual product with the `sku` value of `Membership-Gold` with a price of $49.99. + +**Request** + +```text + +mutation { + addVirtualProductsToCart( + input: { + cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG", + cart_items: [ + { + data: { + quantity: 1 + sku: "Membership-Gold" + } + } + ] + } + ) { + cart { + items { + product { + name + } + quantity + } + prices { + grand_total { + value + currency + } + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "addVirtualProductsToCart": { + "cart": { + "items": [ + { + "product": { + "name": "Gold Membership" + }, + "quantity": 1 + } + ], + "prices": { + "grand_total": { + "value": 49.99, + "currency": "USD" + } + } + } + } + } +} +``` + +## Input attributes + +The top-level `AddVirtualProductsToCartInput` object is listed first. All child objects are listed in alphabetical order. + +### AddVirtualProductsToCartInput object {#AddVirtualProductsToCartInput} + +The `AddVirtualProductsToCartInput` object must contain the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer's cart +`cart_items` | [VirtualProductCartItemInput!](#VirtualProductCartItemInput) | Contains the cart item IDs and quantity of each item + +### CartItemInput object {#CartItemInputVirtual} + +The `CartItemInput` object must contain the following attributes: + +{% include graphql/cart-item-input.md %} + +### CustomizableOptionInput object {#CustomizableOptionInputVirtual} + +The `CustomizableOptionInput` object must contain the following attributes: + +{% include graphql/customizable-option-input.md %} + +### VirtualProductCartItemInput object {#VirtualProductCartItemInput} + +The `VirtualProductCartItemInput` object must contain the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`customizable_options` |[[CustomizableOptionInput]](#CustomizableOptionInputVirtual) | An array that defines customizable options for the product +`data` | [CartItemInput!](#CartItemInputVirtual) | An object containing the `sku` and `quantity` of the product + +## Output attributes + +The `AddVirtualProductsToCartOutput` object contains the `Cart` object. + +Attribute | Data Type | Description +--- | --- | --- +`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart + +### Cart object {#CartObject} + +{% include graphql/cart-object.md %} + +[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object. diff --git a/guides/v2.3/graphql/reference/quote-apply-coupon.md b/guides/v2.3/graphql/reference/quote-apply-coupon.md new file mode 100644 index 00000000000..57f93510bb3 --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-apply-coupon.md @@ -0,0 +1,115 @@ +--- +group: graphql +title: applyCouponToCart mutation +--- + +The `applyCouponToCart` mutation applies a pre-defined coupon code to the specified cart. Valid coupon codes are defined in cart price rules. + +## Syntax + +`mutation: {applyCouponToCart(input: ApplyCouponToCartInput) {ApplyCouponToCartOutput}}` + +## Example usage + +The following example applies the coupon code `H2O` to the cart. For this coupon to be valid, the Affirm Water Bottle (`sku`: 24-UG06) must be in the cart. + +**Request** + +``` text +mutation { + applyCouponToCart( + input: { + cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG", + coupon_code: "H20" + } + ) { + cart { + items { + product { + name + } + quantity + } + applied_coupon { + code + } + prices { + grand_total{ + value + currency + } + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "applyCouponToCart": { + "cart": { + "items": [ + { + "product": { + "name": "Gold Membership" + }, + "quantity": 2 + }, + { + "product": { + "name": "Strive Shoulder Pack" + }, + "quantity": 1 + }, + { + "product": { + "name": "Affirm Water Bottle " + }, + "quantity": 1 + } + ], + "applied_coupon": { + "code": "H20" + }, + "prices": { + "grand_total": { + "value": 134.08, + "currency": "USD" + } + } + } + } + } +} +``` + +## Input attributes + +The `applyCouponToCart` mutation requires the `cart_id` and `coupon_code`. + +### ApplyCouponToCartInput object {#ApplyCouponToCartInput} + +The `ApplyCouponToCartInput` object must contain the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer's cart +`coupon_code` | String! | A valid coupon code + + +## Output attributes + +The `ApplyCouponToCartOutput` object contains the `Cart` object. + +Attribute | Data Type | Description +--- | --- | --- +`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart + +### Cart object {#CartObject} + +{% include graphql/cart-object.md %} + +[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object. diff --git a/guides/v2.3/graphql/reference/quote-create-cart.md b/guides/v2.3/graphql/reference/quote-create-cart.md new file mode 100644 index 00000000000..51a89a7f981 --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-create-cart.md @@ -0,0 +1,72 @@ +--- +group: graphql +title: createEmptyCart mutation +--- + +The `createEmptyCart` mutation creates an empty shopping cart for a guest or logged in customer. You can allow the system to generate a cart ID, or assign a specific ID. + +If you are creating a cart for a logged in customer, you must include the customer's authorization token in the header of the request. + + +## Syntax + +`mutation: {createEmptyCart}: String` + +## Example usage + +### Create a cart with a randomly-generated cart ID + +**Request** + +```text +mutation { + createEmptyCart +} +``` + +**Response** + +The response is the cart ID, which is sometimes called the quote ID. The remaining examples in this topic will use this cart ID. + +```json +{ + "data": { + "createEmptyCart": "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C"} + } +} +``` + +### Create an empty cart with an assigned cart ID + +You can also create an empty cart with a specified `cart_id`. + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String | A 32-character string + +### Syntax + +`mutation: {input: createEmptyCart: createEmptyCartInput}: String` + +### Example usage + +**Request** + +``` text +mutation { + createEmptyCart(input: + { cart_id: "x2345678901234567890123456789012"}) +} +``` + +**Response** + +The mutation returns the same `cart_id`. + +```json +{ + "data": { + "createEmptyCart": "x2345678901234567890123456789012" + } +} +``` \ No newline at end of file diff --git a/guides/v2.3/graphql/reference/quote-payment-method.md b/guides/v2.3/graphql/reference/quote-payment-method.md new file mode 100644 index 00000000000..ecf37c1d2b2 --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-payment-method.md @@ -0,0 +1,97 @@ +--- +group: graphql +title: setPaymentMethodOnCart mutation +--- + +The `setPaymentMethodOnCart` mutation defines which payment method to apply to the cart. Magento GraphQL supports the following payment methods: + +Title | Code +--- | --- +Bank Transfer Payment | `banktransfer` +Cash on Delivery | `cashondelivery` +Check / Money order | `checkmo` +No Payment Information Required | `free` +Purchase Order | `purchaseorder` + +Apply the `setPaymentMethodOnCart` mutation after setting the shipping address, shipping method, and after applying any discounts to the cart. + +## Syntax + +`mutation: {setPaymentMethodOnCart(input: SetPaymentMethodOnCartInput): SetPaymentMethodOnCartOutput}}` + +## Example usage + +The following example assigns the `banktransfer` payment method to the specified cart. + +**Request** + +```text +mutation { + setPaymentMethodOnCart(input: { + cart_id: "rMQdWEecBZr4SVWZwj2AF6y0dNCKQ8uH" + payment_method: { + code: "banktransfer" + } + }) { + cart { + selected_payment_method { + code + title + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "setPaymentMethodOnCart": { + "cart": { + "selected_payment_method": { + "code": "banktransfer", + "title": "Bank Transfer Payment" + } + } + } + } +} +``` + +## Input attributes + +The top-level `SetPaymentMethodOnCartInput` object is listed first. All child objects are listed in alphabetical order. + +### SetPaymentMethodOnCartInput attributes {#SetPaymentMethodOnCartInput} + +The `SetPaymentMethodOnCartInput` object must contain the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer’s cart +`payment_method` | [PaymentMethodInput!](#PaymentMethodInput) | An object containing the payment method code + +### PaymentMethodInput attributes {#PaymentMethodInput} + +The `PaymentMethodInput` object can contain the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`code` | String! | The internal name for the payment method +`purchase_order_number` | String | The purchase order number. Optional for most payment methods + +## Output attributes + +The `SetPaymentMethodOnCartOutput` object contains the `Cart` object. + +Attribute | Data Type | Description +--- | --- | --- +`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart + +### Cart object {#CartObject} + +{% include graphql/cart-object.md %} + +[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object. diff --git a/guides/v2.3/graphql/reference/quote-place-order.md b/guides/v2.3/graphql/reference/quote-place-order.md new file mode 100644 index 00000000000..f4f55f3fa2d --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-place-order.md @@ -0,0 +1,70 @@ +--- +group: graphql +title: placeOrder mutation +--- + +The `placeOrder` mutation converts the cart into an order and returns an order ID. You cannot manage orders with GraphQL, because orders are part of the backend. You can use REST or SOAP calls to manage orders to their completion. + +Perform the following actions before using the `placeOrder` mutation: + +* Create an empty cart +* Add one or more products to the cart +* Set the billing address +* Set the shipping address +* Set the shipping method +* Set the payment method +* For guest customers, assign an email to the cart + +## Syntax + +`mutation: {placeOrder(input: PlaceOrderInput): {PlaceOrderOutput}}` + +## Example usage + +**Request** + +``` text +mutation { + placeOrder( + input: { + cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG" + } + ) { + order { + order_id + } + } +} +``` + +**Response** + + +```json +{ + "data": { + "placeOrder": { + "order": { + "order_id": "000000006" + } + } + } +} +``` + +## Input attributes + +The `placeOrderInput` object must contain the following attribute: + + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer’s cart + +## Output attributes + +The `placeOrderOutput` object contains the `order` object, which contains the following attribute: + +Attribute | Data Type | Description +--- | --- | --- +`order_id` | String! | The unique ID that identifies the order diff --git a/guides/v2.3/graphql/reference/quote-remove-coupon.md b/guides/v2.3/graphql/reference/quote-remove-coupon.md new file mode 100644 index 00000000000..5875be5b2f2 --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-remove-coupon.md @@ -0,0 +1,103 @@ +--- +group: graphql +title: removeCouponFromCart mutation +--- + +The `removeCouponFromCart` mutation removes a previously-applied coupon from the cart. + +## Syntax + +`mutation: {removeCouponFromCart(input: RemoveCouponFromCartInput) {RemoveCouponFromCartOutput}}` + +## Example usage + +The following example removes a coupon from the cart. + +**Request** + +``` text +mutation { + removeCouponFromCart( + input: + { cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG" } + ) { + cart { + items { + product { + name + } + quantity + } + applied_coupon { + code + } + prices { + grand_total{ + value + currency + } + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "removeCouponFromCart": { + "cart": { + "items": [ + { + "product": { + "name": "Strive Shoulder Pack" + }, + "quantity": 1 + }, + { + "product": { + "name": "Affirm Water Bottle " + }, + "quantity": 1 + } + ], + "applied_coupon": null, + "prices": { + "grand_total": { + "value": 39, + "currency": "USD" + } + } + } + } + } +} +``` + +## Input attributes + +The `removeCouponFromCart` mutation requires the `cart_id` attribute. + +### removeCouponFromCart object {#removeCouponFromCart} + +The `removeCouponFromCart` object must contain the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer's cart + +## Output attributes + +The `removeCouponFromCart` object contains the `Cart` object. + +Attribute | Data Type | Description +--- | --- | --- +`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart + +### Cart object {#CartObject} + +{% include graphql/cart-object.md %} + +[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object. diff --git a/guides/v2.3/graphql/reference/quote-remove-item.md b/guides/v2.3/graphql/reference/quote-remove-item.md new file mode 100644 index 00000000000..df3a25fb384 --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-remove-item.md @@ -0,0 +1,95 @@ +--- +group: graphql +title: removeItemFromCart mutation +--- + +The `removeItemFromCart` mutation deletes the entire quantity of a specified item from the cart. If you remove all items from the cart, the cart continues to exist. + +## Syntax + +`mutation: {removeItemFromCart(input: RemoveItemFromCartInput): {RemoveItemFromCartOutput}}` + +## Example usage + +The following example removes cart item 14 from the cart. + +**Request** + +```text +mutation { + removeItemFromCart( + input: { + cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG", + cart_item_id: 14 + } + ){ + cart { + items { + id + product { + name + } + quantity + } + prices { + grand_total{ + value + currency + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "removeItemFromCart": { + "cart": { + "items": [ + { + "id": "13", + "product": { + "name": "Strive Shoulder Pack" + }, + "quantity": 3 + } + ], + "prices": { + "grand_total": { + "value": 96, + "currency": "USD" + } + } + } + } + } +} +``` + +## Input attributes + +### RemoveItemFromCartInput object {#RemoveItemFromCartInput} + +The `RemoveItemFromCartInput` object must contain the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer's cart +`cart_item_id` | Int! | The unique ID assigned when a customer places an item in the cart + +## Output attributes + +The `RemoveItemFromCartOutput` object contains the `Cart` object. + +Attribute | Data Type | Description +--- | --- | --- +`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart + +### Cart object {#CartObject} + +{% include graphql/cart-object.md %} + +[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object. \ No newline at end of file diff --git a/guides/v2.3/graphql/reference/quote-set-billing-address.md b/guides/v2.3/graphql/reference/quote-set-billing-address.md new file mode 100644 index 00000000000..c92893c8ff6 --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-set-billing-address.md @@ -0,0 +1,115 @@ +--- +group: graphql +title: setBillingAddressOnCart mutation +--- + +The `setBillingAddressOnCart` mutation sets the billing address for a specific cart. If you set the `use_for_shipping` attribute to `true`, Magento assigns the same address as the shipping address. + +## Syntax + +`mutation: {setBillingAddressOnCart(input: SetBillingAddressOnCartInput) {SetBillingAddressOnCartOutput}}` + +## Example usage + +The following example creates a new billing address for a specific cart. + +**Request** + +``` text +mutation { + setBillingAddressOnCart( + input: { + cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C" + billing_address: { + address: { + firstname: "Bob" + lastname: "Roll" + company: "Magento" + street: ["Magento Pkwy", "Main Street"] + city: "Austin" + region: "TX" + postcode: "78758" + country_code: "US" + telephone: "8675309" + save_in_address_book: true + } + use_for_shipping: false + } + } + ) { + cart { + billing_address { + firstname + lastname + company + street + city + postcode + telephone + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "setBillingAddressOnCart": { + "cart": { + "billing_address": { + "firstname": "Bob", + "lastname": "Roll", + "company": "Magento", + "street": [ + "Magento Pkwy", + "Main Street" + ], + "city": "Austin", + "postcode": "78758", + "telephone": "8675309" + } + } + } + } +} +``` + +## Input attributes + +The top-level `SetBillingAddressOnCartInput` object is listed first. All child objects are listed in alphabetical order. + +### SetBillingAddressOnCartInput object {#SetBillingAddressOnCartInput} + +Attribute | Data Type | Description +--- | --- | --- +`billing_address` | [BillingAddressInput!](#BillingAddressInput) | The billing address for a specific cart +`cart_id` | String! | The unique ID that identifies the customer's cart + +### BillingAddressInput object {#BillingAddressInput} + +Attribute | Data Type | Description +--- | --- | --- +`address` | [CartAddressInput](#CartAddressInput) | The billing address for the cart +`customer_address_id` | Int | The unique ID that identifies the customer's address +`use_for_shipping` | Boolean | Specifies whether to use the billing address for the shipping address (`True`/`False`) + +### CartAddressInput object {#CartAddressInput} + +{% include graphql/cart-address-input.md %} + +## Output attributes + +The `SetBillingAddressOnCartOutput` object contains the `Cart` object. + +Attribute | Data Type | Description +--- | --- | --- +`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart + +### Cart object {#CartObject} + +{% include graphql/cart-object.md %} + +[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object. diff --git a/guides/v2.3/graphql/reference/quote-set-guest-email.md b/guides/v2.3/graphql/reference/quote-set-guest-email.md new file mode 100644 index 00000000000..1fafac3bd41 --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-set-guest-email.md @@ -0,0 +1,68 @@ +--- +group: graphql +title: setGuestEmailOnCart mutation +--- + +For guest customers, you must assign an email to the cart before you place the order. + +A logged-in customer specifies an email address when they create an account. Therefore, you can place the order without explicitly setting the email. + +## Syntax + +`mutation: {setGuestEmailOnCart(input: SetGuestEmailOnCartInput): {SetGuestEmailOnCartOutput}}` + +## Example usage + +**Request** + +``` text +mutation { + setGuestEmailOnCart( + input: { + cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C" + email: "jdoe@example.com" + } + ) { + cart { + email + } + } +} +``` + +**Response** + +```json +{ + "data": { + "setGuestEmailOnCart": { + "cart": { + "email": "jdoe@example.com" + } + } + } +} +``` + +## Input attributes + +The `SetGuestEmailOnCartInput` object must contain the following attributes. + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer’s cart +`email` | String! | The guest user's email + +## Output attributes + +The `SetGuestEmailOnCartOutput` object contains the `Cart` object. + +Attribute | Data Type | Description +--- | --- | --- +`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart + +### Cart object {#CartObject} + +{% include graphql/cart-object.md %} + +[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object. diff --git a/guides/v2.3/graphql/reference/quote-set-shipping-address.md b/guides/v2.3/graphql/reference/quote-set-shipping-address.md new file mode 100644 index 00000000000..aa46f4801f3 --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-set-shipping-address.md @@ -0,0 +1,119 @@ +--- +group: graphql +title: setShippingAddressesOnCart mutation +--- + +The `setShippingAddressesOnCart` mutation sets one or more shipping addresses on a specific cart. The shipping address does not need to be specified in the following circumstances: + +* The cart contains only virtual items +* When you defined the billing address, you set the `use_for_shipping` attribute to `true`. Magento assigns the same address as the shipping address. + +## Syntax + +`mutation: {setShippingAddressesOnCart(input: SetShippingAddressesOnCartInput) {SetShippingAddressesOnCartOutput}}` + +## Example usage + +**Request** + +``` text +mutation { + setShippingAddressesOnCart( + input: { + cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C" + shipping_addresses: [ + { + address: { + firstname: "Bob" + lastname: "Roll" + company: "Magento" + street: ["Magento Pkwy", "Main Street"] + city: "Austin" + region: "TX" + postcode: "78758" + country_code: "US" + telephone: "8675309" + save_in_address_book: false + } + } + ] + } + ) { + cart { + shipping_addresses { + firstname + lastname + company + street + city + postcode + telephone + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "setShippingAddressesOnCart": { + "cart": { + "shipping_addresses": [ + { + "firstname": "Bob", + "lastname": "Roll", + "company": "Magento", + "street": [ + "Magento Pkwy", + "Main Street" + ], + "city": "Austin", + "postcode": "78758", + "telephone": "8675309" + } + ] + } + } + } +} +``` + +## Input attributes + +The top-level `SetShippingAddressesOnCartInput` object is listed first. All child objects are listed in alphabetical order. + +### SetShippingAddressesOnCartInput object {#SetShippingAddressesOnCartInput} + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer's cart +`billing_address` | [ShippingAddressInput!](#ShippingAddressInput) | The billing address for a specific cart + +### CartAddressInput object {#CartAddressInputShip} + +{% include graphql/cart-address-input.md %} + +### ShippingAddressInput object {#ShippingAddressInput} + +Attribute | Data Type | Description +--- | --- | --- +`address` | [CartAddressInput](#CartAddressInputShip) | The shipping address for the cart +`customer_address_id` | Int | The unique ID that identifies the customer's address + + +## Output attributes + +The `SetShippingAddressOnCartOutput` object contains the `Cart` object. + +Attribute | Data Type | Description +--- | --- | --- +`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart + +### Cart object {#CartObject} + +{% include graphql/cart-object.md %} + +[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object. diff --git a/guides/v2.3/graphql/reference/quote-shipping-method.md b/guides/v2.3/graphql/reference/quote-shipping-method.md new file mode 100644 index 00000000000..df48a4f3b0a --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-shipping-method.md @@ -0,0 +1,116 @@ +--- +group: graphql +title: setShippingMethodsOnCart mutation +--- + +The `setShippingMethodsOnCart` mutation sets one or more shipping methods on a cart. By default, Magento GraphQL supports the following shipping methods: + +Label | Carrier code | Method code +--- | --- | --- +DHL | dhl | Varies +Federal Express | fedex | Varies +Flat Rate | flatrate | flatrate +Free Shipping | freeshipping | freeshipping +Best Way | tablerate | bestway +United Parcel Service | ups | Varies +United States Postal Service | usps | Varies + +## Syntax + +`mutation: {setShippingMethodsOnCart(input: setShippingMethodsOnCartInput) {setShippingMethodsOnCartOutput}}` + +## Example usage + +The following example sets the shipping method to Best Way. + +**Request** + +``` text +mutation { + setShippingMethodsOnCart( + input: { + cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG", + shipping_methods: [ + { + carrier_code: "tablerate" + method_code: "bestway" + } + ] + } + ) { + cart { + shipping_addresses { + selected_shipping_method { + carrier_code + carrier_title + method_code + method_title + amount { + value + currency + } + } + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "setShippingMethodsOnCart": { + "cart": { + "shipping_addresses": [ + { + "selected_shipping_method": { + "carrier_code": "tablerate", + "carrier_title": "Best Way", + "method_code": "bestway", + "method_title": "Table Rate", + "amount": { + "value": 0, + "currency": "USD" + } + } + } + ] + } + } + } +} +``` + +## Input attributes + +The top-level `setShippingMethodsOnCartInput` object is listed first. All child objects are listed in alphabetical order. + +### setShippingMethodsOnCartInput object {#setShippingMethodsOnCartInput} + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer's cart +`shipping_methods` | [ShippingMethodInput!](#ShippingMethodInput) | The shipping address for a specific cart + +### ShippingMethodInput object {#ShippingMethodInput} + +Attribute | Data Type | Description +--- | --- | --- +`carrier_code` | String! | A string that identifies a commercial carrier or an offline shipping method +`method_code` | String! | A string that indicates which service a commercial carrier will use to ship items. For offline shipping methods, this value is similar to the label displayed on the checkout page + +## Output attributes + +The `ShippingMethodOutput` object contains the `Cart` object. + +Attribute | Data Type | Description +--- | --- | --- +`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart + +### Cart object {#CartObject} + +{% include graphql/cart-object.md %} + +[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object. diff --git a/guides/v2.3/graphql/reference/quote-update-cart-items.md b/guides/v2.3/graphql/reference/quote-update-cart-items.md new file mode 100644 index 00000000000..f02631ba85c --- /dev/null +++ b/guides/v2.3/graphql/reference/quote-update-cart-items.md @@ -0,0 +1,121 @@ +--- +group: graphql +title: updateCartItems mutation +--- + +The `updateCartItems` mutation allows you to replace the current quantity of one or more cart items with the specified quantities. It does not perform calculations to determine the quantity of cart items. + +{:.bs-callout .bs-callout-info} +Setting the quantity to `0` removes an item from the cart. + +## Syntax + +`mutation: {updateCartItems(input: UpdateCartItemsInput): {UpdateCartItemsOutput}}` + +## Example usage + +The following example changes the quantity of cart item `13` to `3`. + +**Request** + +```text +mutation { + updateCartItems( + input: { + cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG", + cart_items: [ + { + cart_item_id: 13 + quantity: 3 + } + ] + } + ){ + cart { + items { + id + product { + name + } + quantity + } + prices { + grand_total{ + value + currency + } + } + } +} +``` + +**Response** + +```json +{ + "data": { + "updateCartItems": { + "cart": { + "items": [ + { + "id": "13", + "product": { + "name": "Strive Shoulder Pack" + }, + "quantity": 3 + }, + { + "id": "14", + "product": { + "name": "Affirm Water Bottle " + }, + "quantity": 1 + } + ], + "prices": { + "grand_total": { + "value": 103, + "currency": "USD" + } + } + } + } + } +} +``` + +## Input attributes + +The `UpdateCartItemsInput` object is listed first. All child objects are listed in alphabetical order. + +### UpdateCartItemsInput object {#UpdateCartItemsInput} + +The `UpdateCartItemsInput` object must contain the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String! | The unique ID that identifies the customer's cart +`cart_items` | [CartItemUpdateInput!](#CartItemUpdateInput) | Contains the cart item IDs and quantity of each item + +### CartItemUpdateInput object {#CartItemUpdateInput} + +The `CartItemUpdateInput` object must contain the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`cart_item_id` | Int! | The unique ID assigned when a customer places an item in the cart +`quantity` | Float! | The new quantity of the item. A value of `0` removes the item from the cart + +## Output attributes + +The `UpdateCartItemsOutput` object contains the `Cart` object. + +Attribute | Data Type | Description +--- | --- | --- +`cart` |[ Cart!](#CartObject) | Describes the contents of the specified shopping cart + +### Cart object {#CartObject} + +{% include graphql/cart-object.md %} + +[Cart query output]({{page.baseurl}}/graphql/reference/quote.html#cart-output) provides more information about the `Cart` object. \ No newline at end of file diff --git a/guides/v2.3/graphql/reference/quote.md b/guides/v2.3/graphql/reference/quote.md index 75406078363..f5fb14beb64 100644 --- a/guides/v2.3/graphql/reference/quote.md +++ b/guides/v2.3/graphql/reference/quote.md @@ -9,210 +9,121 @@ A Quote represents the contents of a customer's shopping cart. It is responsible * Determining estimated shipping costs * Calculating subtotals, computing additional costs, applying coupons, and determining the payment method -{:.bs-callout .bs-callout-tip} -Except for `createEmptyCart`, the mutations defined in this topic are available in the 2.3-develop branch of the [graphql-ce repository](https://github.com/magento/graphql-ce). +## cart Query {#cart} -## Query -Use the `Cart` query to retrieve information about a particular cart. +Use the `cart` query to retrieve information about a particular cart. ### Syntax `{cart(cart_id: String!) {Cart}}` -### Cart attributes -The `Cart` object can contain the following attributes: - -Attribute | Data Type | Description ---- | --- | --- -`applied_coupon` | AppliedCoupon | The `AppliedCoupon` object contains the code text attribute, which provides the coupon code -`available_payment_methods` | AvailablePaymentMethod | Available payment methods -`billing_address` | [CartAddress](#cartAddressAttributes) | Contains the billing address specified in the customer's cart -`email` | String | The customer's email address -`items` | [CartItemInterface](#cartItemsInterface) | Contains the items in the customer's cart -`selected_payment_method` | SelectedPaymentMethod | Selected payment method -`shipping_addresses` | [CartAddress](#cartAddressAttributes) | Contains one or more shipping addresses - -### Available Payment Method attributes - -the `AvailablePaymentMethod` object must contain the following attributes: - -Attribute | Data Type | Description ---- | --- | --- -`code` | String | The payment method code -`title` | String | The payment method title - -### Cart address attributes {#cartAddressAttributes} -The `CartAddress` object can contain the following attributes: - -Attribute | Data Type | Description ---- | --- | --- -`address_type` | AddressTypeEnum | Specifies if the type of address is SHIPPING or BILLING -`cart_items` | CartItemQuantity | Contains the cart item IDs and quantity of each item -`city` | String | The city specified for the shipping or billing address -`company` | String | The company specified for the shipping or billing address -`country` | [CartAddressCountry] | The country code and label for the shipping or billing address -`customer_notes` | String | Comments made to the customer that accompanies the order -`firstname` | String | The customer's first name -`items_weight` | Float | The total weight of the items in the cart -`lastname` | String | The customer's last name -`postcode` | String | The postal code for the shipping or billing address -`region` | CartAddressRegion | An object containing the region name, region code, and region ID -`street` | [String] | The street for the shipping or billing address -`telephone` | String | The telephone number for the shipping or billing address - -### Cart item interface attributes {#cartItemsInterface} -The `CartItemInterface` object can contain the following attributes: - -Attribute | Data Type | Description ---- | --- | --- -`id` | String | ID of the item -`product` | [ProductInterface]({{ page.baseurl }}/graphql/reference/product-interface-implementations.html) | Contains attributes that are common to all types of products -`qty` | Float | The number of items in the cart - -## Selected Payment Method attributes - -the `SelectedPaymentMethod` object can contain the following attributes: - -Attribute | Data Type | Description ---- | --- | --- -`code` | String | The payment method code -`purchase_order_number` | String | The purchase order number -`title` | String | The payment method title - ### Example usage -The following returns information about a cart given a `cart_id`. Note that the `cart_id` specified is for demonstration purposes only. You will need to [generate](#createEmptyCart) your own `cart_id` for this example to work. +The following query shows the status of a cart that is ready to be converted into an order. **Request** -``` text -{ - cart(cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C") { +```text +query { + cart(cart_id: "IeTUiU0oCXjm0uRqGCOuhQ2AuQatogjG") + { + email billing_address { + city + country { + code + label + } + firstname lastname - firstname postcode - } - items { - id - qty + region { + code + label + } + street + telephone } shipping_addresses { - company - postcode - lastname firstname - } - } -} -``` -**Response** - -```json -{ - "data": { - "cart": { - "items": [ - { - "id": "22", - "qty": 1 + lastname + street + city + region { + code + label + } + country { + code + label + } + telephone + available_shipping_methods { + amount { + currency + value } - ], - "billing_address": - { - "lastname": "Roll", - "firstname": "Bob", - "postcode": "78759" - }, - "shipping_addresses": [ - { - "company": "Magento", - "postcode": "78759", - "lastname": "Roll", - "firstname": "Bob" + available + base_amount { + value + currency } - ] - } - } -} -``` - -## Mutations - -### Create an empty cart {#createEmptyCart} - -The `createEmptyCart` mutation creates an empty shopping cart for a guest or logged in customer. If you are creating a cart for a logged in customer, you must include the customer's authorization token in the header of the request. - -#### Syntax - -`mutation: {createEmptyCart: String}` - -**Request** - -``` text -mutation { - createEmptyCart -} -``` - -**Response** - -The response is the quote ID, which is sometimes called the cart ID. The remaining examples in this topic will use this cart ID. - -```json -{ - "data": { - "createEmptyCart": "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C"} - } -} -``` - -### Adding simple products to a cart - -Adds simple items to a specific cart. - -### Add simple products to cart attributes -The `addSimpleProductsToCart` object can contain the following attributes: - -Attribute | Data Type | Description ---- | --- | --- -`cartItems` | SimpleProductCartItemInput | The list of items to add to the cart -`cart_id` | String | The unique ID that identifies the customer's cart - -#### Syntax - -`mutation: {addSimpleProductsToCart(input: AddSimpleProductsToCartInput) {AddSimpleProductsToCartOutput}}` - -#### Example usage - -The following example adds two Joust Duffle Bags to the cart. - -**Request** - -``` text -mutation { - addSimpleProductsToCart( - input: { - cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C", - cartItems: [ - { - data: { - qty: 2 - sku: "24-MB01" - } + carrier_code + carrier_title + error_message + method_code + method_title + price_excl_tax { + value + currency } - ] + price_incl_tax { + value + currency + } + } + selected_shipping_method { + amount { + value + currency + } + base_amount { + value + currency + } + carrier_code + carrier_title + method_code + method_title + } + } - ) { - cart { - items { + items { + id product { name + sku } - qty + quantity } + available_payment_methods { + code + title } - } + selected_payment_method { + code + title + } + applied_coupon { + code + } + prices { + grand_total{ + value + currency + } + } + } } ``` @@ -221,59 +132,268 @@ mutation { ```json { "data": { - "addSimpleProductsToCart": { - "cart": { - "items": [ - { - "product": { - "name": "Joust Duffle Bag" + "cart": { + "email": "mshaw@example.com", + "billing_address": { + "city": "Calder", + "country": { + "code": "US", + "label": "US" + }, + "firstname": "Bob", + "lastname": "Roll", + "postcode": "49628", + "region": { + "code": "MI", + "label": "Michigan" + }, + "street": [ + "Magento Pkwy", + "Main Street" + ], + "telephone": "8675309" + }, + "shipping_addresses": [ + { + "firstname": "Bob", + "lastname": "Roll", + "street": [ + "Magento Pkwy", + "Main Street" + ], + "city": "Austin", + "region": { + "code": "TX", + "label": "Texas" + }, + "country": { + "code": "US", + "label": "US" + }, + "telephone": "8675309", + "available_shipping_methods": [ + { + "amount": { + "currency": "USD", + "value": 20 + }, + "available": true, + "base_amount": { + "value": 20, + "currency": "USD" + }, + "carrier_code": "flatrate", + "carrier_title": "Flat Rate", + "error_message": "", + "method_code": "flatrate", + "method_title": "Fixed", + "price_excl_tax": { + "value": 20, + "currency": "USD" + }, + "price_incl_tax": { + "value": 20, + "currency": "USD" + } + }, + { + "amount": { + "currency": "USD", + "value": 5 + }, + "available": true, + "base_amount": { + "value": 5, + "currency": "USD" + }, + "carrier_code": "tablerate", + "carrier_title": "Best Way", + "error_message": "", + "method_code": "bestway", + "method_title": "Table Rate", + "price_excl_tax": { + "value": 5, + "currency": "USD" + }, + "price_incl_tax": { + "value": 5, + "currency": "USD" + } + }, + { + "amount": { + "currency": "USD", + "value": 11.41 + }, + "available": true, + "base_amount": { + "value": 11.41, + "currency": "USD" + }, + "carrier_code": "ups", + "carrier_title": "United Parcel Service", + "error_message": "", + "method_code": "03", + "method_title": "UPS Ground", + "price_excl_tax": { + "value": 11.41, + "currency": "USD" + }, + "price_incl_tax": { + "value": 11.41, + "currency": "USD" + } + }, + { + "amount": { + "currency": "USD", + "value": 26.81 + }, + "available": true, + "base_amount": { + "value": 26.81, + "currency": "USD" + }, + "carrier_code": "ups", + "carrier_title": "United Parcel Service", + "error_message": "", + "method_code": "12", + "method_title": "UPS Three-Day Select", + "price_excl_tax": { + "value": 26.81, + "currency": "USD" + }, + "price_incl_tax": { + "value": 26.81, + "currency": "USD" + } + }, + { + "amount": { + "currency": "USD", + "value": 34.27 + }, + "available": true, + "base_amount": { + "value": 34.27, + "currency": "USD" + }, + "carrier_code": "ups", + "carrier_title": "United Parcel Service", + "error_message": "", + "method_code": "02", + "method_title": "UPS Second Day Air", + "price_excl_tax": { + "value": 34.27, + "currency": "USD" + }, + "price_incl_tax": { + "value": 34.27, + "currency": "USD" + } }, - "qty": 2 + { + "amount": { + "currency": "USD", + "value": 76.12 + }, + "available": true, + "base_amount": { + "value": 76.12, + "currency": "USD" + }, + "carrier_code": "ups", + "carrier_title": "United Parcel Service", + "error_message": "", + "method_code": "01", + "method_title": "UPS Next Day Air", + "price_excl_tax": { + "value": 76.12, + "currency": "USD" + }, + "price_incl_tax": { + "value": 76.12, + "currency": "USD" + } + }, + { + "amount": { + "currency": "USD", + "value": 108.52 + }, + "available": true, + "base_amount": { + "value": 108.52, + "currency": "USD" + }, + "carrier_code": "ups", + "carrier_title": "United Parcel Service", + "error_message": "", + "method_code": "14", + "method_title": "UPS Next Day Air Early A.M.", + "price_excl_tax": { + "value": 108.52, + "currency": "USD" + }, + "price_incl_tax": { + "value": 108.52, + "currency": "USD" + } + } + ], + "selected_shipping_method": { + "amount": { + "value": 5, + "currency": "USD" + }, + "base_amount": { + "value": 5, + "currency": "USD" + }, + "carrier_code": "tablerate", + "carrier_title": "Best Way", + "method_code": "bestway", + "method_title": "Table Rate" } - ] - } - } - } -} -``` - -### Adding simple product with customizable options to a cart - -If a product has a customizable option, the option's value can be specified in the add to cart request. - -**Request** - -``` text -mutation { - addSimpleProductsToCart (input: { - cart_id: "nu31JXR9DaqbdVqFDGnqjrMJmUnT3mzB" - cartItems: { - data: { - sku:"simple" - qty:1 - }, - customizable_options: [ + } + ], + "items": [ { - id: 121 - value: "field value" + "id": "13", + "product": { + "name": "Strive Shoulder Pack", + "sku": "24-MB04" + }, + "quantity": 4 } - ] - } - }) { - cart { - items { - product { - name + ], + "available_payment_methods": [ + { + "code": "cashondelivery", + "title": "Cash On Delivery" + }, + { + "code": "banktransfer", + "title": "Bank Transfer Payment" + }, + { + "code": "purchaseorder", + "title": "Purchase Order" + }, + { + "code": "checkmo", + "title": "Check / Money order" } - qty - - ... on SimpleCartItem { - customizable_options { - label - values { - value - } - } + ], + "selected_payment_method": { + "code": "banktransfer", + "title": "Bank Transfer Payment" + }, + "applied_coupon": null, + "prices": { + "grand_total": { + "value": 133, + "currency": "USD" } } } @@ -281,329 +401,177 @@ mutation { } ``` -**Response** +### Input attributes -```text -{ - "data": { - "addSimpleProductsToCart": { - "cart": { - "items": [ - { - "product": { - "name": "simple" - }, - "qty": 2, - "customizable_options": [ - { - "label": "Field Option", - "values": [ - { - "value": "field value" - } - ] - } - ] - } - ] - } - } - } -} -``` +Attribute | Data Type | Description +--- | --- | --- +`cart_id` | String | A 32-character string that is created when you [create a cart]({{page.baseurl}}/graphql/reference/quote-create-cart.html) + +### Output attributes {#cart-output} +The top-level `Cart` object is listed first. All child objects are listed in alphabetical order. -### Updating billing and shipping information -{:.no_toc} +#### Cart object + +The `Cart` object can contain the following attributes: -You can set the billing and shipping addresses on a cart. +{% include graphql/cart-object.md %} -### Set the billing address on cart attributes -The `setBillingAddressOnCart` object can contain the following attributes: + +#### AppliedCoupon object {#AppliedCoupon} + +The `AppliedCoupon` object must contain the following attributes: Attribute | Data Type | Description --- | --- | --- -`billing_address` | [BillingAddressInput](#billingAddressInput) | The billing address for a specific cart -`cart_id` | String | The unique ID that identifies the customer's cart +`code` | String! | The coupon code applied to the order + +#### AvailablePaymentMethod object {#AvailablePaymentMethod} -### Set the billing address input attributes {#billingAddressInput} -The `BillingAddressInput` object can contain the following attributes: +The `AvailablePaymentMethod` object must contain the following attributes: Attribute | Data Type | Description --- | --- | --- -`address` | [CartAddressInput](#cartAddressInput) | The billing address for the cart -`customer_address_id` | Int | The unique ID that identifies the customer's address -`use_for_shipping` | Boolean | Specifies whether to use the billing address for the shipping address (`True`/`False`) +`code` | String! | The payment method code +`title` | String! | The payment method title + +#### AvailableShippingMethod object {#AvailableShippingMethod} + +The `AvailableShippingMethod` object can contain the following attributes: + +Attribute | Data Type | Description +--- | --- | --- +`amount` | Money! | The cost of shipping using this shipping method +`available` | Boolean! | Indicates whether this shipping method can be applied to the cart +`base_amount` | Money | The base shipping cost, not including taxes or other cost adjustment. Could be null if method is not available +`carrier_code` | String! | A string that identifies a commercial carrier or an offline shipping method +`carrier_title` | String! | The label for the carrier code +`error_message` | String | Describes an error condition +`method_code` | String | A shipping method code associated with a carrier. Could be null if method is not available +`method_title` | String | The label for the method code. Could be null if method is not available +`price_excl_tax` | Money! | The cost of shipping using this shipping method, excluding tax +`price_incl_tax` | Money! | The cost of shipping using this shipping method, excluding tax + +#### BillingCartAddress object {#BillingCartAddress} -### Cart address input attributes {#cartAddressInput} -The `CartAddressInput` object can contain the following attributes: +The `BillingCartAddress` object can contain the following attributes: Attribute | Data Type | Description --- | --- | --- `city` | String | The city specified for the billing address `company` | String | The company specified for the billing address -`country_code` | String | The country code and label for the billing address +`country` | [CartAddressCountry](#CartAddressCountry) | The country code and label for the billing address +`customer_notes` | String | Comments made to the customer that accompanies the order `firstname` | String | The customer's first name `lastname` | String | The customer's last name `postcode` | String | The postal code for the billing address -`region` | String | The region code and label for the billing address -`save_in_address_book` | Boolean | Specifies whether to save the address (`True`/`False`) +`region` | [CartAddressRegion](#CartAddressRegion) | An object containing the region label and code `street` | [String] | The street for the billing address `telephone` | String | The telephone number for the billing address -### Set the billing address on a cart - -Use the `setBillingAddressOnCart` mutation to set a new billing address for a specific cart. - -#### Syntax - -`mutation: {setBillingAddressOnCart(input: SetBillingAddressOnCartInput) {SetBillingAddressOnCartOutput}}` - -#### Example usage - -The following example creates a new billing address for a specific cart. - -**Request** - -``` text -mutation { - setBillingAddressOnCart( - input: { - cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C" - billing_address: { - address: { - firstname: "Bob" - lastname: "Roll" - company: "Magento" - street: ["Magento Pkwy", "Main Street"] - city: "Austin" - region: "TX" - postcode: "78758" - country_code: "US" - telephone: "8675309" - save_in_address_book: false - } - } - } - ) { - cart { - billing_address { - firstname - lastname - company - street - city - postcode - telephone - } - } - } -} -``` - -**Response** - -```json -{ - "data": { - "setBillingAddressOnCart": { - "cart": { - "billing_address": { - "firstname": "Bob", - "lastname": "Roll", - "company": "Magento", - "street": [ - "Magento Pkwy", - "Main Street" - ], - "city": "Austin", - "postcode": "78758", - "telephone": "8675309" - } - } - } - } -} -``` - -### Set the shipping address on a cart - -Use the `setShippingAddressesOnCart` mutation to set a new shipping address for a specific cart. - -#### Syntax +#### CartAddressCountry object {#CartAddressCountry} -`mutation: {setShippingAddressesOnCart(input: SetShippingAddressesOnCartInput) {SetShippingAddressesOnCartOutput}}` +The `CartAddressCountry` object can contain the following attributes: -#### Example usage +Attribute | Data Type | Description +--- | --- | --- +`code` | String | The country code +`label` | String | The display label for the country -The following example creates a new shipping address for a specific cart. +#### CartAddressRegion object {#CartAddressRegion} -**Request** +The `CartAddressRegion` object can contain the following attributes: -``` text -mutation { - setShippingAddressesOnCart( - input: { - cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C" - shipping_addresses: [ - { - address: { - firstname: "Bob" - lastname: "Roll" - company: "Magento" - street: ["Magento Pkwy", "Main Street"] - city: "Austin" - region: "TX" - postcode: "78758" - country_code: "US" - telephone: "8675309" - save_in_address_book: false - } - } - ] - } - ) { - cart { - shipping_addresses { - firstname - lastname - company - street - city - postcode - telephone - } - } - } -} -``` +Attribute | Data Type | Description +--- | --- | --- +`code` | String | The state or province code +`label` | String | The display label for the region -**Response** +#### CartItemInterface object {#CartItemInterface} -```json -{ - "data": { - "setShippingAddressesOnCart": { - "cart": { - "shipping_addresses": [ - { - "firstname": "Bob", - "lastname": "Roll", - "company": "Magento", - "street": [ - "Magento Pkwy", - "Main Street" - ], - "city": "Austin", - "postcode": "78758", - "telephone": "8675309" - } - ] - } - } - } -} -``` +The `CartItemInterface` object can contain the following attributes: -### Add and remove coupons from a cart -{:.no_toc} +Attribute | Data Type | Description +--- | --- | --- +`id` | String | ID of the item +`product` | [ProductInterface]({{ page.baseurl }}/graphql/reference/product-interface-implementations.html) | Contains attributes that are common to all types of products +`quantity` | Float | The number of items in the cart -You can use mutations to add or remove coupons from a specified cart. +#### CartItemQuantity object {#CartItemQuantity} -### Coupon attributes -{:.no_toc} -The add and remove coupon from cart objects can contain the following attributes: +The `CartItemQuantity` object must contain the following attributes: Attribute | Data Type | Description --- | --- | --- -`cart_id` | String | The unique ID that identifies the customer's cart -`coupon_code` | String | The coupon code - -### Apply coupon to cart +`cart_item_id` | Int! | The unique ID assigned when a customer places an item in the cart +`quantity` | Float! | The quantity of this item selected -Adds a coupon code to a cart. +#### CartPrices object {#CartPrices} -#### Syntax +The `CartPrices` object can contain the following attributes: -`mutation: {applyCouponToCart(input: ApplyCouponToCartInput) {ApplyCouponToCartOutput}}` +Attribute | Data Type | Description +--- | --- | --- +`applied_taxes` | [[CartTaxItem]](#CartTaxItem) | An array containing the names and amounts of taxes applied to the item +`grand_total` | Money | The total, including discounts, taxes, shipping, and other fees +`subtotal_excluding_tax` | Money | Subtotal without taxes +`subtotal_including_tax` | Money | Subtotal with taxes +`subtotal_with_discount_excluding_tax` | Money | Subtotal with any discounts applied, but not taxes -#### Example usage +#### CartTaxItem object {#CartTaxItem} -The following call adds a coupon code called `test2019` to a cart. +The `CartTaxItem` object must contain the following attributes: -**Request** - -``` text -mutation { - applyCouponToCart( - input: { - cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C" - coupon_code: "test2019" - } - ) { - cart { - applied_coupon { - code - } - } - } -} -``` +Attribute | Data Type | Description +--- | --- | --- +`amount` | Money! | The amount of tax applied to the item +`label` | String! | The description of the tax -**Response** +#### SelectedPaymentMethod object {#SelectedPaymentMethod} -```json -{ - "data": { - "applyCouponToCart": { - "cart": { - "applied_coupon": { - "code": "test2019" - } - } - } - } -} -``` +The `SelectedPaymentMethod` object can contain the following attributes: -### Remove coupon from cart +Attribute | Data Type | Description +--- | --- | --- +`code` | String! | The payment method code +`purchase_order_number` | String | The purchase order number +`title` | String! | The payment method title -Removes a coupon from the specified cart. +#### SelectedShippingMethod object {#SelectedShippingMethod} -#### Syntax +The `SelectedShippingMethod` object can contain the following attributes: -`mutation: {removeCouponFromCart(input: RemoveCouponFromCartInput){ RemoveCouponFromCartOutput}}` +Attribute | Data Type | Description +--- | --- | --- +`amount` | Money | The cost of shipping using this shipping method +`base_amount` | Money | The base shipping cost, not including taxes or other cost adjustment +`carrier_code` | String | A string that identifies a commercial carrier or an offline shipping method +`carrier_title` | String | The label for the carrier code +`method_code` | String | A shipping method code associated with a carrier +`method_title` | String | The label for the method code -#### Example usage +#### ShippingCartAddress object {#ShippingCartAddress} -The following example removes a coupon from the cart. +The `ShippingCartAddress` object can contain the following attributes: -**Request** +Attribute | Data Type | Description +--- | --- | --- +`available_shipping_methods` | [[AvailableShippingMethod]](#AvailableShippingMethod) | An array that lists the shipping methods that can be applied to the cart +`cart_items` | [[CartItemQuantity]](#CartItemQuantity) | An array that lists the items in the cart +`city` | String | The city specified for the shipping address +`company` | String | The company specified for the shipping address +`country` | [CartAddressCountry](#CartAddressCountry) | The country code and label for the shipping address +`customer_notes` | String | Comments made to the customer that will accompany the order +`firstname` | String | The recipient's first name +`items_weight` | Float | The weight of all items in the cart +`lastname` | String | The recipient's last name +`postcode` | String | The postal code for the shipping address +`region` | [CartAddressRegion](#CartAddressRegion) | An object containing the region label and code +`selected_shipping_method` | [SelectedShippingMethod](#SelectedShippingMethod) | An object that describes the selected shipping method +`street` | [String] | The street for the shipping address +`telephone` | String | The telephone number for the shipping address -``` text -mutation { - removeCouponFromCart(input: { cart_id: "4JQaNVJokOpFxrykGVvYrjhiNv9qt31C" }) { - cart { - applied_coupon { - code - } - } - } -} -``` -**Response** +## Mutations -```json -{ - "data": { - "removeCouponFromCart": { - "cart": { - "applied_coupon": { - "code": "test2019" - } - } - } - } -} -``` +Refer to the left navigation for information about the mutations defined in the `QuoteGraphQl` module. \ No newline at end of file