createCart

Creates a new cart.

It creates a cart in commercetools by sending a request to its GraphQL API. By default, it uses the addBillingAddressDefaultQuery GraphQL query

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.ts. You can also define values for these properties on a per-request basis through the method CreateCartParams.

If you are using commercetools stores, 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

declare function createCart(
	context: CommercetoolsIntegrationContext,
	cartDraft?: CreateCartParams,
	customQuery?: CustomQuery
): Promise<CreateCartResponse>;

Parameters

Returns

Returns a representation of the CreateCartResponse.

Referenced Types

• CommercetoolsIntegrationContext
• CreateCartParams
• CustomQuery
• CreateCartResponse

Examples

Creating a new cart.

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

Creating a new cart from a draft.

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!

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.

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.ts. We can use it to specify response fields as well as overwrite certain query variables (e.g. storeKey).

export const 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.

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