createCart

Method creating a new cart in commercetools.

This method sends a POST request to the createCart endpoint of the Vue Storefront API Middleware. In turn, it creates a cart in commercetools by sending a request to its GraphQL API. The default GraphQL query used by this method can be found here.

When vsf-commercetools-token cookie is present in the browser, this method will create a cart for the user (anonymous or authenticated) linked to the token. In case there is no cookie, it will create a cart and initialize an anonymous session.

The default values for the currency and country properties will be derived from the vsf-currency and vsf-country cookies. The default value for the inventoryMode property can be set in middleware.config.js. You can also define values for these properties on a per-request basis through the method params.

If you are using commercetools stores and have configured the feature in your Vue Storefront application correctly, this method will create a cart for the current store. By default, its key is read from the vsf-store cookie. However, you can overwrite it by using the customQuery parameter. Refer to the Examples section for more details.

Signature

export declare function createCart<Res extends PartialCreateCartResponse = CreateCartResponse>(
	params?: CreateCartParams,
	options?: MethodOptions<CustomQuery<"createCart">>
): Promise<Res>;

Parameters

Returns

Returns a representation of the CreateCartResponse.

Referenced Types

• PartialCreateCartResponse
• CreateCartResponse
• CreateCartParams
• MethodOptions
• CustomQuery

Examples

Creating a new cart.

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

const { cart } = await sdk.commerce.createCart();

Creating a new cart from a draft.

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

const { cart } = await sdk.commerce.createCart({
  currency: 'USD',
  customerEmail: 'test@gmail.com'
})

Creating a new cart with Custom Fields. 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.createCart({
  custom: {
    type: {
      key: 'cart-custom-fields'
    },
    fields: [
      { name: 'spiritAnimal', value: '"Dog"' },
      { name: 'favouriteSinger', value: '"Bono"' }
    ]
  }
});

Creating a new cart with a list of shipping addresses available for its line items. Refer to the addProductToCart method docs for examples on how to use such a list later.

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

const { cart } = await sdk.commerce.createCart({
  itemShippingAddresses: [{
    country: 'US',
    key: 'random-shipping-address-key'
  }]
});

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 (e.g. storeKey).

module.exports = {
  integrations: {
    ct: {
      // ...
      customQueries: {
        'create-cart-custom-query': ({ query, variables, metadata }) => {
          variables.storeKey = metadata.storeKey;

          return {
            variables,
            query: `
              mutation createCart($draft: MyCartDraft!, $storeKey: KeyReferenceInput) {
                cart: createMyCart(draft: $draft, storeKey: $storeKey) {
                  ${metadata.fields}
                }
              }
            `;
          }
        }
      }
    }
  }
};

Creating a new cart for a specific store 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 CustomCreateCartResponse = {
  cart: {
    id: string;
    version: string;
    store: {
      key: string;
    }
  }
}

const { cart } = await sdk.commerce.createCart<CustomCreateCartResponse>(null, {
  customQuery: {
    createCart: 'create-cart-custom-query',
    metadata: { storeKey: 'europe', fields: 'id,version,store{key}' }
  }
});