addProductToCart

Method adding a product to cart in commercetools.

This method sends a POST request to the updateCart endpoint of the Vue Storefront API Middleware and passes the AddMyCartLineItem action to it. In turn, it adds a product to cart in commercetools by sending a request to its GraphQL API. The default GraphQL query used by this method can be found here.

When the method is called with an incorrect cartVersion and commercetools API responds with the ConcurrentModification error, our Server Middleware automatically retries the failed request with the correct version. To disable that behavior, set the versionFallback to false.

In case you need to perform a more complex cart update with multiple update actions at once, use the updateCart method instead.

Signature

export declare function addProductToCart<Res extends PartialUpdateCartResponse = UpdateCartResponse>(
	params: AddProductToCartParams,
	options?: MethodOptions<CustomQuery<"updateCart">>
): Promise<Res>;

Parameters

Name	Required	Type	Description
`params`	Required	`AddProductToCartParams`	Parameter object which can be used with this method. Refer to its type definition to learn about possible properties.
`options`	Optional	`MethodOptions<CustomQuery<"updateCart">>`	Options that can be passed to additionally configure the request or customize the logic in a plugin.

Returns

Returns a representation of the UpdateCartResponse.

Referenced Types

Examples

Adding a product to cart.

import { sdk } from '~/sdk.config.ts';

const { cart } = await sdk.commerce.addProductToCart({
  cartId: '6931b5d2-986f-4d2b-8cba-45007a26eb5e',
  cartVersion: 1,
  sku: 'M0E20000000E59M',
  quantity: 1
});

Adding a product with Custom Fields to cart. Before using this feature, you have to configure a proper Custom Type in commercetools. Also, the value property must be stringified!

import { sdk } from '~/sdk.config.ts';

const { cart } = await sdk.commerce.addProductToCart({
  cartId: '6931b5d2-986f-4d2b-8cba-45007a26eb5e',
  cartVersion: 1,
  sku: 'M0E20000000E59M',
  quantity: 1,
  custom: {
    type: {
      key: 'cart-custom-fields'
    },
    fields: [
      { name: 'spiritAnimal', value: '"Dog"' },
      { name: 'favouriteSinger', value: '"Bono"' }
    ]
  }
});

Adding a product with shipping details to cart. Refer to the createCart method docs for examples on how to create a cart with a list of available shipping addresses.

import { sdk } from '~/sdk.config.ts';

const { cart } = await sdk.commerce.addProductToCart({
  cartId: '6931b5d2-986f-4d2b-8cba-45007a26eb5e',
  cartVersion: 1,
  sku: 'M0E20000000E59M',
  quantity: 1,
  shippingDetails: {
    targets: [{
      addressKey: 'random-shipping-address-key',
      quantity: 1
    }]
  }
});

Adding a product with a supply channel to cart.

import { sdk } from '~/sdk.config.ts';

const { cart } = await sdk.commerce.addProductToCart({
  cartId: '6931b5d2-986f-4d2b-8cba-45007a26eb5e',
  cartVersion: 1,
  sku: 'M0E20000000E59M',
  quantity: 1,
  supplyChannel: {
    key: 'sunrise-store-zurich'
  }
});

Creating a custom GraphQL query for the method in middleware.config.js. We can use it to specify response fields as well as overwrite certain query variables.

module.exports = {
  integrations: {
    ct: {
      // ...
      customQueries: {
        'add-product-to-cart-custom-query': ({ query, variables, metadata }) => {
          Object.assign(variables, metadata?.variables);

          return {
            variables,
            query: `
              mutation updateCart(
                $id: String!,
                $version: Long!,
                $actions: [MyCartUpdateAction!]!,
                $storeKey: KeyReferenceInput
              ) {
                cart: updateMyCart(id: $id, version: $version, actions: $actions, storeKey: $storeKey) {
                  ${metadata.fields}
                }
              }
            `;
          }
        }
      }
    }
  }
};

Adding a product to cart and selecting response fields using the custom GraphQL query from the previous example. Notice how we are using the type parameter to overwrite the default response interface.

import { sdk } from '~/sdk.config.ts';

type CustomUpdateCartResponse = {
  cart: {
    id: string;
    version: string;
  }
}

const { cart } = await sdk.commerce.addProductToCart<CustomUpdateCartResponse>({
  cartId: '6931b5d2-986f-4d2b-8cba-45007a26eb5e',
  cartVersion: 1,
  sku: 'M0E20000000E59M',
  quantity: 1
}, {
  customQuery: {
    updateCart: 'add-product-to-cart-custom-query',
    metadata: {
      fields: 'id, version'
    }
  }
})