--- title: createCartHandler description: Creates an API that can be used to interact with the cart. api_version: 2026-04 source_url: html: >- https://shopify.dev/docs/api/hydrogen/latest/utilities/cart/createcarthandler md: >- https://shopify.dev/docs/api/hydrogen/latest/utilities/cart/createcarthandler.md api_name: hydrogen --- # createCartHandler Creates an API that can be used to interact with the cart. #### createCartHandler(options) * **getCartId** **() => string** **required** A function that returns the cart id in the form of `gid://shopify/Cart/c1-123`. * **setCartId** **(cartId: string) => Headers** **required** A function that sets the cart ID. * **storefront** **Storefront** **required** The storefront client instance created by [`createStorefrontClient`](docs/api/hydrogen/utilities/createstorefrontclient). * **buyerIdentity** **CartBuyerIdentityInput** Buyer identity. Default buyer identity is passed to cartCreate. * **cartMutateFragment** **string** The cart mutation fragment used in most mutation requests, except for `setMetafields` and `deleteMetafield`. See the [example usage](https://shopify.dev/docs/api/hydrogen/utilities/createcarthandler#example-cart-fragments) in the documentation. * **cartQueryFragment** **string** The cart query fragment used by `cart.get()`. See the [example usage](https://shopify.dev/docs/api/hydrogen/utilities/createcarthandler#example-cart-fragments) in the documentation. * **customMethods** **TCustomMethods** Define custom methods or override existing methods for your cart API instance. See the [example usage](https://shopify.dev/docs/api/hydrogen/utilities/createcarthandler#example-custom-methods) in the documentation. ### CartBuyerIdentityInput ### Headers ### Storefront Interface to interact with the Storefront API. * cache The \*\*\`Cache\`\*\* interface provides a persistent storage mechanism for Request / Response object pairs that are cached in long lived memory. Available only in secure contexts. \[MDN Reference]\(https://developer.mozilla.org/docs/Web/API/Cache) ```ts Cache ``` * CacheCustom ```ts (overrideOptions: AllCacheOptions) => AllCacheOptions ``` * CacheLong ```ts (overrideOptions?: AllCacheOptions) => AllCacheOptions ``` * CacheNone ```ts () => NoStoreStrategy ``` * CacheShort ```ts (overrideOptions?: AllCacheOptions) => AllCacheOptions ``` * forward Forwards the request to the Storefront API. It reads the API version from the request URL. ```ts (request: Request, options?: Pick) => Promise ``` * forwardMcp Forwards the request to the Storefront MCP endpoint. ```ts (request: Request) => Promise ``` * generateCacheControlHeader ```ts (cacheOptions: AllCacheOptions) => string ``` * getApiUrl ```ts (props?: Partial>) => string ``` * getHeaders ```ts () => Record ``` * getPrivateTokenHeaders ```ts (props?: Partial> & Pick & { buyerIp?: string; }) => Record ``` * getPublicTokenHeaders ```ts (props?: Partial> & Pick) => Record ``` * getShopifyDomain ```ts (props?: Partial>) => string ``` * i18n ```ts TI18n ``` * isMcpUrl Checks if the request URL matches the Storefront MCP endpoint. ```ts (request: { url?: string; }) => boolean ``` * isStorefrontApiUrl Checks if the request URL matches the Storefront API GraphQL endpoint. ```ts (request: { url?: string; }) => boolean ``` * mutate ```ts < OverrideReturnType extends any = never, RawGqlString extends string = string, >( mutation: RawGqlString, ...options: ClientVariablesInRestParams< StorefrontMutations, RawGqlString, StorefrontCommonExtraParams, AutoAddedVariableNames > ) => Promise< ClientReturn & StorefrontError > ``` * query ```ts < OverrideReturnType extends any = never, RawGqlString extends string = string, >( query: RawGqlString, ...options: ClientVariablesInRestParams< StorefrontQueries, RawGqlString, StorefrontCommonExtraParams & Pick, AutoAddedVariableNames > ) => Promise< ClientReturn & StorefrontError > ``` * setCollectedSubrequestHeaders Sets the collected subrequest headers in the response. Useful to forward the cookies and server-timing headers from server subrequests to the browser. ```ts (response: { headers: Headers; }) => void ``` ### AllCacheOptions Override options for a cache strategy. * maxAge The maximum amount of time in seconds that a resource will be considered fresh. See \`max-age\` in the \[MDN docs]\(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#:\~:text=Response%20Directives-,max%2Dage,-The%20max%2Dage). ```ts number ``` * mode The caching mode, generally \`public\`, \`private\`, or \`no-store\`. ```ts string ``` * sMaxAge Similar to \`maxAge\` but specific to shared caches. See \`s-maxage\` in the \[MDN docs]\(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#s-maxage). ```ts number ``` * staleIfError Indicate that the cache should serve the stale response if an error occurs while revalidating the cache. See \`stale-if-error\` in the \[MDN docs]\(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-if-error). ```ts number ``` * staleWhileRevalidate Indicate that the cache should serve the stale response in the background while revalidating the cache. See \`stale-while-revalidate\` in the \[MDN docs]\(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-while-revalidate). ```ts number ``` ### NoStoreStrategy * mode ```ts string ``` ### StorefrontCommonExtraParams * displayName ```ts string ``` * headers ```ts HeadersInit ``` * storefrontApiVersion ```ts string ``` ### StorefrontClientProps * contentType Customizes which \`"content-type"\` header is added when using \`getPrivateTokenHeaders()\` and \`getPublicTokenHeaders()\`. When fetching with a \`JSON.stringify()\`-ed \`body\`, use \`"json"\`. When fetching with a \`body\` that is a plain string, use \`"graphql"\`. Defaults to \`"json"\` Can also be customized on a call-by-call basis by passing in \`'contentType'\` to both \`getPrivateTokenHeaders({...})\` and \`getPublicTokenHeaders({...})\`, for example: \`getPublicTokenHeaders({contentType: 'graphql'})\` ```ts 'json' | 'graphql' ``` * privateStorefrontToken The Storefront API delegate access token. Refer to the \[authentication]\(https://shopify.dev/api/storefront#authentication) and \[delegate access token]\(https://shopify.dev/apps/auth/oauth/delegate-access-tokens) documentation for more details. ```ts string ``` * publicStorefrontToken The Storefront API access token. Refer to the \[authentication]\(https://shopify.dev/api/storefront#authentication) documentation for more details. ```ts string ``` * storeDomain The host name of the domain (eg: \`{shop}.myshopify.com\`). ```ts string ``` * storefrontApiVersion The Storefront API version. This should almost always be the same as the version Hydrogen React was built for. Learn more about Shopify \[API versioning]\(https://shopify.dev/api/usage/versioning) for more details. ```ts string ``` ### StorefrontMutations Maps all the mutations found in the project to variables and return types. ### AutoAddedVariableNames ```ts 'country' | 'language' ``` ### StorefrontError * errors ```ts StorefrontApiErrors ``` ### StorefrontApiErrors ```ts JsonGraphQLError[] | undefined ``` ### JsonGraphQLError * extensions Reserved for implementors to extend the protocol however they see fit, and hence there are no additional restrictions on its contents. ```ts { [key: string]: unknown; } ``` * locations If an error can be associated to a particular point in the requested GraphQL document, it should contain a list of locations. ```ts { line: number; column: number; }[] ``` * message ```ts string ``` * name ```ts string ``` * path If an error can be associated to a particular field in the GraphQL result, it \_must\_ contain an entry with the key \`path\` that details the path of the response field which experienced the error. This allows clients to identify whether a null result is intentional or caused by a runtime error. ```ts (string | number)[] ``` * stack ```ts string ``` ### StorefrontQueries Maps all the queries found in the project to variables and return types. ### StorefrontQueryOptions ```ts StorefrontCommonExtraParams & { query: string; mutation?: never; cache?: CachingStrategy; } ``` ### CachingStrategy Use the \`CachingStrategy\` to define a custom caching mechanism for your data. Or use one of the pre-defined caching strategies: CacheNone, CacheShort, CacheLong. * maxAge The maximum amount of time in seconds that a resource will be considered fresh. See \`max-age\` in the \[MDN docs]\(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#:\~:text=Response%20Directives-,max%2Dage,-The%20max%2Dage). ```ts number ``` * mode The caching mode, generally \`public\`, \`private\`, or \`no-store\`. ```ts string ``` * sMaxAge Similar to \`maxAge\` but specific to shared caches. See \`s-maxage\` in the \[MDN docs]\(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#s-maxage). ```ts number ``` * staleIfError Indicate that the cache should serve the stale response if an error occurs while revalidating the cache. See \`stale-if-error\` in the \[MDN docs]\(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-if-error). ```ts number ``` * staleWhileRevalidate Indicate that the cache should serve the stale response in the background while revalidating the cache. See \`stale-while-revalidate\` in the \[MDN docs]\(https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-while-revalidate). ```ts number ``` #### Returns The handler returns the following default methods. Any [custom](https://shopify.dev/docs/api/hydrogen/utilities/createcarthandler#example-custom-methods) or overwritten methods will also be available in the returned cart instance. * **addDeliveryAddresses** **CartDeliveryAddressesAddFunction** Adds a delivery address to the cart. * **addGiftCardCodes** **CartGiftCardCodesAddFunction** Adds gift card codes to the cart without replacing existing ones. * **addLines** **CartLinesAddFunction** Adds items to the cart. If the cart doesn't exist, a new one will be created. * **create** **CartCreateFunction** Creates a new cart. * **deleteMetafield** **CartMetafieldDeleteFunction** Removes a custom field (metafield) from the cart. * **get** **CartGetFunction** Retrieves the cart information. * **getCartId** **() => string** Retrieves the unique identifier of the cart. By default, it gets the ID from the request cookie. * **removeDeliveryAddresses** **CartDeliveryAddressesRemoveFunction** Removes a delivery address from the cart * **removeGiftCardCodes** **CartGiftCardCodesRemoveFunction** Removes gift card codes from the cart. * **removeLines** **CartLinesRemoveFunction** Removes items from the cart. * **replaceDeliveryAddresses** **CartDeliveryAddressesReplaceFunction** Replace all delivery addresses on the cart. * **setCartId** **(cartId: string) => Headers** Sets the unique identifier of the cart. By default, it sets the ID in the header cookie. * **setMetafields** **CartMetafieldsSetFunction** Adds extra information (metafields) to the cart. If the cart doesn't exist, a new one will be created. * **updateAttributes** **CartAttributesUpdateFunction** Updates additional information (attributes) in the cart. * **updateBuyerIdentity** **CartBuyerIdentityUpdateFunction** Updates the buyer's information in the cart. If the cart doesn't exist, a new one will be created. * **updateDeliveryAddresses** **CartDeliveryAddressesUpdateFunction** Update cart delivery addresses. * **updateDiscountCodes** **CartDiscountCodesUpdateFunction** Updates discount codes in the cart. * **updateGiftCardCodes** **CartGiftCardCodesUpdateFunction** Updates gift card codes in the cart. * **updateLines** **CartLinesUpdateFunction** Updates items in the cart. * **updateNote** **CartNoteUpdateFunction** Updates the note in the cart. If the cart doesn't exist, a new one will be created. * **updateSelectedDeliveryOption** **CartSelectedDeliveryOptionsUpdateFunction** Updates the selected delivery options in the cart. Only available for carts associated with a customer access token. ### CartDeliveryAddressesAddFunction * addresses ```ts CartSelectableAddressInput[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartOptionalInput * cartId The cart id. ```ts string ``` * country The country code. ```ts CountryCode ``` * language The language code. ```ts LanguageCode ``` * visitorConsent Visitor consent preferences for the Storefront API's ```ts VisitorConsent ``` ### VisitorConsent * analytics ```ts ConsentStatus ``` * marketing ```ts ConsentStatus ``` * preferences ```ts ConsentStatus ``` * sale\_of\_data ```ts ConsentStatus ``` ### ConsentStatus ```ts boolean | undefined ``` ### CartQueryDataReturn ```ts CartQueryData & { errors?: StorefrontApiErrors; } ``` ### CartQueryData * cart A cart represents the merchandise that a buyer intends to purchase, and the estimated cost associated with the cart, throughout a customer's session. Use the \[\`checkoutUrl\`]\(https://shopify.dev/docs/api/storefront/current/objects/Cart#field-checkoutUrl) field to direct buyers to Shopify's web checkout to complete their purchase. Learn more about \[interacting with carts]\(https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/cart/manage). ```ts Cart ``` * userErrors ```ts | CartUserError[] | MetafieldsSetUserError[] | MetafieldDeleteUserError[] ``` * warnings ```ts CartWarning[] ``` ### Cart * attributes The cart's attributes. ```ts { __typename?: "Attribute"; key?: string; value?: string; }[] ``` * buyerIdentity The cart's buyer identity. ```ts CartType['buyerIdentity'] ``` * checkoutUrl The checkout URL for the cart, if the cart has been created in the Storefront API. ```ts string ``` * cost The cost for the cart, including the subtotal, total, taxes, and duties. ```ts CartType['cost'] ``` * discountCodes The discount codes applied to the cart. ```ts { __typename?: "CartDiscountCode"; applicable?: boolean; code?: string; }[] ``` * id The cart's ID if it has been created through the Storefront API. ```ts string ``` * lines The cart lines. ```ts Array ``` * note The cart's note. ```ts string ``` * totalQuantity The total number of items in the cart, across all lines. If there are no lines, then the value is 0. ```ts number ``` ### CartUserError ### MetafieldsSetUserError ### MetafieldDeleteUserError ### CartWarning ### CartGiftCardCodesAddFunction * giftCardCodes ```ts string[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartLinesAddFunction * lines ```ts CartLineInput[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartLineInput ### CartCreateFunction * input ```ts CartInput ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartInput ### CartMetafieldDeleteFunction * key ```ts string ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartGetFunction * cartInput ```ts CartGetProps ``` returns ```ts Promise ``` ### CartGetProps * cartId The cart ID. ```ts string ``` * country The country code. ```ts CountryCode ``` * language The language code. ```ts LanguageCode ``` * numCartLines The number of cart lines to be returned. ```ts number ``` * visitorConsent Visitor consent preferences for the Storefront API's ```ts VisitorConsent ``` ### CartReturn ```ts Cart & { errors?: StorefrontApiErrors; } ``` ### CartDeliveryAddressesRemoveFunction * addressIds ```ts string[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartGiftCardCodesRemoveFunction * appliedGiftCardIds ```ts string[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartLinesRemoveFunction * lineIds ```ts string[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartDeliveryAddressesReplaceFunction * addresses ```ts CartSelectableAddressInput[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartMetafieldsSetFunction * metafields ```ts MetafieldWithoutOwnerId[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### MetafieldWithoutOwnerId ### CartAttributesUpdateFunction * attributes ```ts AttributeInput[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### AttributeInput ### CartBuyerIdentityUpdateFunction * buyerIdentity ```ts CartBuyerIdentityInput ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartDeliveryAddressesUpdateFunction * addresses ```ts CartSelectableAddressUpdateInput[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartDiscountCodesUpdateFunction * discountCodes ```ts string[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartGiftCardCodesUpdateFunction * giftCardCodes ```ts string[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartLinesUpdateFunction * lines ```ts CartLineUpdateInput[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartLineUpdateInput ### CartNoteUpdateFunction * note ```ts string ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartSelectedDeliveryOptionsUpdateFunction * selectedDeliveryOptions ```ts CartSelectedDeliveryOptionInput[] ``` * optionalParams ```ts CartOptionalInput ``` returns ```ts Promise ``` ### CartSelectedDeliveryOptionInput Examples ### Examples * #### Server.(js|ts) ##### JavaScript ```js import { createStorefrontClient, createCartHandler, cartGetIdDefault, cartSetIdDefault, createRequestHandler, } from '@shopify/hydrogen'; import * as reactRouterBuild from 'virtual:react-router/server-build'; 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: reactRouterBuild, mode: process.env.NODE_ENV, getLoadContext: () => ({ storefront, cart, // Pass the cart api instance to the loader context. }), }); return await handleRequest(request); }, }; ``` ##### TypeScript ```ts import { createStorefrontClient, createCartHandler, cartGetIdDefault, cartSetIdDefault, createRequestHandler, } from '@shopify/hydrogen'; import * as reactRouterBuild from 'virtual:react-router/server-build'; export default { async fetch( request: Request, env: Record, executionContext: ExecutionContext, ): Promise { const {storefront} = createStorefrontClient({ /* client parameters */ }); // Create a cart api instance. const cart = createCartHandler({ storefront, getCartId: cartGetIdDefault(request.headers), setCartId: cartSetIdDefault(), }); const handleRequest = createRequestHandler({ build: reactRouterBuild, mode: process.env.NODE_ENV, getLoadContext: () => ({ storefront, cart, // Pass the cart api instance to the loader context. }), }); return await handleRequest(request); }, }; ``` ***