createCartHandler

server.(js|ts)

import {
  createStorefrontClient,
  createCartHandler,
  cartGetIdDefault,
  cartSetIdDefault,
} from '@shopify/hydrogen';
import * as remixBuild from '@remix-run/dev/server-build';
import {
  createRequestHandler,
  getStorefrontHeaders,
} from '@shopify/remix-oxygen';

export default {
  async fetch(request, env, executionContext) {
    const {storefront} = createStorefrontClient({
      /* client parameters */
    });

    // Create a cart api instance.
    const cart = createCartHandler({
      storefront,
      getCartId: cartGetIdDefault(request.headers),
      setCartId: cartSetIdDefault(),
    });

    const handleRequest = createRequestHandler({
      build: remixBuild,
      mode: process.env.NODE_ENV,
      getLoadContext: () => ({
        storefront,
        cart, // Pass the cart api instance to the loader context.
      }),
    });

    return await handleRequest(request);
  },
};

import {
  createStorefrontClient,
  createCartHandler,
  cartGetIdDefault,
  cartSetIdDefault,
} from '@shopify/hydrogen';
import * as remixBuild from '@remix-run/dev/server-build';
import {
  createRequestHandler,
  getStorefrontHeaders,
} from '@shopify/remix-oxygen';

export default {
  async fetch(
    request: Request,
    env: Record<string, string>,
    executionContext: ExecutionContext,
  ): Promise<Response> {
    const {storefront} = createStorefrontClient({
      /* client parameters */
    });

    // Create a cart api instance.
    const cart = createCartHandler({
      storefront,
      getCartId: cartGetIdDefault(request.headers),
      setCartId: cartSetIdDefault(),
    });

    const handleRequest = createRequestHandler({
      build: remixBuild,
      mode: process.env.NODE_ENV,
      getLoadContext: () => ({
        storefront,
        cart, // Pass the cart api instance to the loader context.
      }),
    });

    return await handleRequest(request);
  },
};

Example

import {
  createCartHandler,
  cartGetIdDefault,
  cartSetIdDefault,
} from '@shopify/hydrogen';

// Override cart fragments
const cart = createCartHandler({
  storefront,
  getCartId: cartGetIdDefault(request.headers),
  setCartId: cartSetIdDefault(),
  cartQueryFragment: CART_QUERY_FRAGMENT,
  cartMutateFragment: CART_MUTATE_FRAGMENT,
});

// cartQueryFragment requirements:
// - Must be named `CartApiQuery`
// - Only have access to the following query variables:
//   - $cartId: ID!
//   - $country: CountryCode
//   - $language: LanguageCode
//   - $numCartLines: Int
const CART_QUERY_FRAGMENT = `#graphql
  fragment CartApiQuery on Cart {
    id
    totalQuantity
    checkoutUrl
    note
  }
`;

// cartMutateFragment requirements:
// - Must be named `CartApiMutation`
// - Only have access to the following query variables:
//   - $cartId: ID!
//   - $country: CountryCode
//   - $language: LanguageCode
const CART_MUTATE_FRAGMENT = `#graphql
  fragment CartApiMutation on Cart {
    id
    totalQuantity
    checkoutUrl
    lines(first: 100) {
      edges {
        node {
          id
          quantity
        }
      }
    }
  }
`;

Example

import {
  createCartHandler,
  cartGetIdDefault,
  cartSetIdDefault,
  cartLinesAddDefault,
  cartLinesRemoveDefault,
} from '@shopify/hydrogen';

const cartQueryOptions = {
  storefront,
  getCartId: cartGetIdDefault(request.headers),
};

const getCartId = cartGetIdDefault(request.headers);

const cart = createCartHandler({
  storefront,
  getCartId,
  setCartId: cartSetIdDefault(),
  customMethods: {
    editInLine: async (addLines, removeLineIds, optionalParams) => {
      // Using Hydrogen default cart query methods
      await cartLinesAddDefault(cartQueryOptions)(addLines, optionalParams);
      return await cartLinesRemoveDefault(cartQueryOptions)(
        removeLineIds,
        optionalParams,
      );
    },
    addLines: async (lines, optionalParams) => {
      // With your own Storefront API graphql query
      return await storefront.mutate(CART_LINES_ADD_MUTATION, {
        variables: {
          id: optionalParams.cartId || getCartId(),
          lines,
        },
      });
    },
  },
});

// Use custom method editInLine that delete and add items in one method
cart.editInLine(
  ['123'],
  [
    {
      merchandiseId: 'gid://shopify/ProductVariant/456789123',
      quantity: 1,
    },
  ],
);

// Use overridden cart.addLines
const result = await cart.addLines(
  [
    {
      merchandiseId: 'gid://shopify/ProductVariant/123456789',
      quantity: 1,
    },
  ],
  {
    cartId: 'c-123',
  },
);
// Output of result:
// {
//   cartLinesAdd: {
//     cart: {
//       id: 'c-123',
//       totalQuantity: 1
//     },
//     errors: []
//   }
// }

const CART_LINES_ADD_MUTATION = `#graphql
  mutation CartLinesAdd(
    $cartId: ID!
    $lines: [CartLineInput!]!
    $country: CountryCode = ZZ
    $language: LanguageCode
  ) @inContext(country: $country, language: $language) {
    cartLinesAdd(cartId: $cartId, lines: $lines) {
      cart {
        id
        totalQuantity
      }
      errors: userErrors {
        message
        field
        code
      }
    }
  }
`;

cart.addLines

export async function action({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.addLines(
    [
      {
        merchandiseId: 'gid://shopify/ProductVariant/123456789',
        quantity: 1,
      },
    ],
    // Optional parameters
    {
      cartId: '123', // override the cart id
      country: 'US', // override the country code to 'US'
      language: 'EN', // override the language code to 'EN'
    },
  );
}

// Output of result:
// {
//   cart: {
//     id: 'c1-123',
//     totalQuantity: 1
//   },
//   errors: []
// }

cart.create

export async function action({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.create(
    {
      lines: [
        {
          merchandiseId: 'gid://shopify/ProductVariant/123456789',
          quantity: 1,
        },
      ],
      discountCodes: ['FREE_SHIPPING'],
    },
    // Optional parameters
    {
      cartId: '123', // override the cart id
      country: 'US', // override the country code to 'US'
      language: 'EN', // override the language code to 'EN'
    },
  );

  // Output of result:
  // {
  //   cart: {
  //     id: 'c1-123',
  //     totalQuantity: 1,
  //     discountCodes: [{ code: 'FREE_SHIPPING'}]
  //   },
  //   errors: []
  // }
}

cart.deleteMetafield

export async function action({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.setMetafields(
    [
      {
        key: 'custom.gift',
        type: 'boolean',
        value: 'true',
      },
    ],
    // Optional parameters
    {
      cartId: '123', // override the cart id
    },
  );

  const result2 = await cart.deleteMetafield(
    'custom.gift',
    // Optional parameters
    {
      cartId: '123', // override the cart id
    },
  );
}

// server.js
// To query for metafields, use the `cartQueryFragment` option when creating the cart handler.
import {
  createCartHandler,
  cartGetIdDefault,
  cartSetIdDefault,
} from '@shopify/hydrogen';

const cart = createCartHandler({
  storefront,
  getCartId: cartGetIdDefault(request.headers),
  setCartId: cartSetIdDefault(),
  cartQueryFragment: CART_QUERY_FRAGMENT,
});

const CART_QUERY_FRAGMENT = `#graphql
  fragment CartApiQuery on Cart {
    id
    metafields(
      identifiers: [{
        namespace: "custom",
        key: "gift"
      ])
    {
      namespace
      key
      type
      value
    }

  }
`;

cart.get

export async function loader({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.get();

  // Optional parameters
  const result2 = await cart.get({
    cartId: '123', // override the cart id
    numCartLines: 50, //override to return 50 cart lines
    country: 'US', // override the country code to 'US'
    language: 'EN', // override the language code to 'EN'
  });
}

cart.getCartId

export async function loader({context}) {
  // Usage
  context.cart.getCartId(); // 'gid://shopify/Cart/123'
}

cart.removeLines

export async function action({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.removeLines(
    ['123'],
    // Optional parameters
    {
      cartId: '123', // override the cart id
      country: 'US', // override the country code to 'US'
      language: 'EN', // override the language code to 'EN'
    },
  );

  // Output of result:
  // {
  //   cart: {
  //     id: 'c1-123',
  //     totalQuantity: 0
  //   },
  //   errors: []
  // }
}

cart.setCartId

export async function action({context}) {
  const {cart} = context;

  const result = await cart.addLines([
    {
      merchandiseId: 'gid://shopify/ProductVariant/123456789',
      quantity: 1,
    },
  ]);

  // Usage
  const headers = cart.setCartId(result.cart.id);
}

cart.setMetafields

export async function action({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.setMetafields(
    [
      {
        key: 'custom.gift',
        type: 'boolean',
        value: 'true',
      },
    ],
    // Optional parameters
    {
      cartId: '123', // override the cart id
    },
  );

  const result2 = await cart.deleteMetafield(
    'custom.gift',
    // Optional parameters
    {
      cartId: '123', // override the cart id
    },
  );
}

// server.js
// To query for metafields, use the `cartQueryFragment` option when creating the cart handler.
import {
  createCartHandler,
  cartGetIdDefault,
  cartSetIdDefault,
} from '@shopify/hydrogen';

const cart = createCartHandler({
  storefront,
  getCartId: cartGetIdDefault(request.headers),
  setCartId: cartSetIdDefault(),
  cartQueryFragment: CART_QUERY_FRAGMENT,
});

const CART_QUERY_FRAGMENT = `#graphql
  fragment CartApiQuery on Cart {
    id
    metafields(
      identifiers: [{
        namespace: "custom",
        key: "gift"
      ])
    {
      namespace
      key
      type
      value
    }

  }
`;

cart.updateAttributes

export async function action({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.updateAttributes(
    [
      {
        key: 'Somekey',
        value: '1',
      },
    ],
    // Optional parameters
    {
      cartId: '123', // override the cart id
    },
  );

  // Output of result:
  // {
  //   cart: {
  //     id: 'c1-123',
  //     totalQuantity: 1
  //   },
  //   errors: []
  // }
}

cart.updateBuyerIdentity

export async function action({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.updateBuyerIdentity(
    {
      customerAccessToken: '123',
    },
    // Optional parameters
    {
      cartId: '123', // override the cart id
      country: 'US', // override the country code to 'US'
      language: 'EN', // override the language code to 'EN'
    },
  );

  // Output of result:
  // {
  //   cart: {
  //     id: 'c1-123',
  //     totalQuantity: 1
  //   },
  //   errors: []
  // }
}

cart.updateDiscountCodes

export async function action({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.updateDiscountCodes(
    ['FREE_SHIPPING'],
    // Optional parameters
    {
      cartId: '123', // override the cart id
      country: 'US', // override the country code to 'US'
      language: 'EN', // override the language code to 'EN'
    },
  );

  // Output of result:
  // {
  //   cart: {
  //     id: 'c1-123',
  //     totalQuantity: 1
  //   },
  //   errors: []
  // }
}

cart.updateLines

export async function action({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.updateLines(
    [
      {
        merchandiseId: 'gid://shopify/ProductVariant/123456789',
        quantity: 2,
      },
    ],
    // Optional parameters
    {
      cartId: '123', // override the cart id
      country: 'US', // override the country code to 'US'
      language: 'EN', // override the language code to 'EN'
    },
  );

  // Output of result:
  // {
  //   cart: {
  //     id: 'c1-123',
  //     totalQuantity: 2
  //   },
  //   errors: []
  // }
}

cart.updateNote

export async function action({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.updateNote(
    'Some notes',
    // Optional parameters
    {
      cartId: '123', // override the cart id
    },
  );

  // Output of result:
  // {
  //   cart: {
  //     id: 'c1-123',
  //     totalQuantity: 0
  //   },
  //   errors: []
  // }
}

cart.updateSelectedDeliveryOptions

export async function action({context}) {
  const {cart} = context;

  // Usage
  const result = await cart.updateSelectedDeliveryOptions(
    [
      {
        deliveryGroupId: '123',
        deliveryOptionHandle: 'Canada Post',
      },
    ],
    // Optional parameters
    {
      cartId: '123', // override the cart id
      country: 'US', // override the country code to 'US'
      language: 'EN', // override the language code to 'EN'
    },
  );

  // Output of result:
  // {
  //   cart: {
  //     id: 'c1-123',
  //     totalQuantity: 2
  //   },
  //   errors: []
  // }
}