addProductsToNewCart mutation

data-variant=info

data-slots=text

The addProductsToNewCart mutation always creates a new cart for the shopper then adds the specified products to that cart. This contrasts with the addProductsToCart mutation, which requires you to specify an existing cart ID as input.

For a logged-in customer, the customer token is passed in the Authorization header.

Use case: smart button on the Product Details Page (PDP)

1. When a shopper clicks a smartbutton on the Product Details Page (PDP), the addProductsToNewCart mutation creates a new cart and adds the items, then returns a cart object, which includes the cart ID field.

2. It is recommended to use the setCartAsInactive mutation after the addProductsToNewCart mutation is successful, in case of an error during the payment process, or the shopper cancelling the payment process in the PDP, to avoid having multiple active carts for logged-in customers.

3. If the shopper clicks the smartbutton again, addProductsToNewCart mutation runs once more to return a new cart object.

Syntax

mutation {
addProductsToNewCart(
        cartItems: [CartItemInput!]!
    ): AddProductsToNewCartOutput 
}

Reference

The addProductsToNewCart reference provides detailed information about the types and fields defined in this mutation.

Example usage

These examples show when the addProductsToNewCart mutation returns a successful, or error message, when creating a new cart in the PDP.

Create a new cart (success)

The following example adds a simple product to a new cart successfully, returning a Cart object.

Request:

mutation {
    addProductsToNewCart(
        cartItems: [
        {
            quantity: 1
            sku: "24-MB04"
        }
        ]
    ) {
        cart {
            id
        }
        user_errors {
            code
            message
        }
    }
}

Response:

{
    "data": {
        "addProductsToNewCart": {
            "cart": {
                "id": "848QJWDI9WJr0LrIz3n6lRdJQkoGRGYf"
            },
            "user_errors": null
        }
    }
}

Create a new cart (failure)

The following example fails to create a new cart beccause the sku does not exist in the catalog. It returns a CartUserInputError object.

Request:

mutation {
    addProductsToNewCart(
        cartItems: [
        {
            quantity: 1
            sku: "24-MB0ee4"
        }
        ]
    ) {
        cart {
            id
        }
        user_errors {
            code
            message
        }
    }
}

Response:

{
    "data": {
        "addProductsToNewCart": {
            "cart": null,
            "user_errors": [
                {
                    "code": "PRODUCT_NOT_FOUND",
                    "message": "Could not find a product with SKU \"24-MB0ee4\""
                }
            ]
        }
    }
}