cart
Creates a function that accepts an object of CartInput and returns a new cart
Anchor to cartCreateDefault-parametersParameters
- Anchor to optionsoptionsCartQueryOptionsrequired
CartCreateFunction
CartQueryOptions
- storefront
The storefront client instance created by [`createStorefrontClient`](docs/api/hydrogen/latest/utilities/createstorefrontclient).
Storefront - getCartId
A function that returns the cart ID.
() => string - cartFragment
The cart fragment to override the one used in this query.
string
{
/**
* The storefront client instance created by [`createStorefrontClient`](docs/api/hydrogen/latest/utilities/createstorefrontclient).
*/
storefront: Storefront;
/**
* A function that returns the cart ID.
*/
getCartId: () => string | undefined;
/**
* The cart fragment to override the one used in this query.
*/
cartFragment?: string;
}Storefront
Interface to interact with the Storefront API.
- query
The function to run a query on Storefront API.
<OverrideReturnType = any, RawGqlString extends string = string>(query: RawGqlString, ...options: RawGqlString extends never ? IsOptionalVariables<StorefrontQueries[RawGqlString]> extends true ? [StorefrontQuerySecondParam<RawGqlString>?] : [StorefrontQuerySecondParam<RawGqlString>] : [StorefrontQuerySecondParam<string>?]) => Promise<RawGqlString extends never ? StorefrontQueries[RawGqlString]["return"] : OverrideReturnType> - mutate
The function to run a mutation on Storefront API.
<OverrideReturnType = any, RawGqlString extends string = string>(mutation: RawGqlString, ...options: RawGqlString extends never ? IsOptionalVariables<StorefrontMutations[RawGqlString]> extends true ? [StorefrontMutateSecondParam<RawGqlString>?] : [StorefrontMutateSecondParam<RawGqlString>] : [StorefrontCommonOptions<{ readonly [variable: string]: unknown; }>?]) => Promise<RawGqlString extends never ? StorefrontMutations[RawGqlString]["return"] : OverrideReturnType> - cache
The cache instance passed in from the `createStorefrontClient` argument.
Cache - CacheNone
Re-export of [`CacheNone`](/docs/api/hydrogen/2023-10/utilities/cachenone).
() => NoStoreStrategy - CacheLong
Re-export of [`CacheLong`](/docs/api/hydrogen/2023-10/utilities/cachelong).
(overrideOptions?: AllCacheOptions) => AllCacheOptions - CacheShort
Re-export of [`CacheShort`](/docs/api/hydrogen/2023-10/utilities/cacheshort).
(overrideOptions?: AllCacheOptions) => AllCacheOptions - CacheCustom
Re-export of [`CacheCustom`](/docs/api/hydrogen/2023-10/utilities/cachecustom).
(overrideOptions: AllCacheOptions) => AllCacheOptions - generateCacheControlHeader
Re-export of [`generateCacheControlHeader`](/docs/api/hydrogen/2023-10/utilities/generatecachecontrolheader).
(cacheOptions: AllCacheOptions) => string - getPublicTokenHeaders
Returns an object that contains headers that are needed for each query to Storefront API GraphQL endpoint. See [`getPublicTokenHeaders` in Hydrogen React](/docs/api/hydrogen-react/2023-10/utilities/createstorefrontclient#:~:text=%27graphql%27.-,getPublicTokenHeaders,-(props%3F%3A) for more details.
(props?: Partial<Pick<StorefrontClientProps, "contentType">> & Pick<StorefrontClientProps, "publicStorefrontToken">) => Record<string, string> - getPrivateTokenHeaders
Returns an object that contains headers that are needed for each query to Storefront API GraphQL endpoint for API calls made from a server. See [`getPrivateTokenHeaders` in Hydrogen React](/docs/api/hydrogen-react/2023-10/utilities/createstorefrontclient#:~:text=storefrontApiVersion-,getPrivateTokenHeaders,-(props%3F%3A) for more details.
(props?: Partial<Pick<StorefrontClientProps, "contentType">> & Pick<StorefrontClientProps, "privateStorefrontToken"> & { buyerIp?: string; }) => Record<string, string> - getShopifyDomain
Creates the fully-qualified URL to your myshopify.com domain. See [`getShopifyDomain` in Hydrogen React](/docs/api/hydrogen-react/2023-10/utilities/createstorefrontclient#:~:text=StorefrontClientReturn-,getShopifyDomain,-(props%3F%3A) for more details.
(props?: Partial<Pick<StorefrontClientProps, "storeDomain">>) => string - getApiUrl
Creates the fully-qualified URL to your store's GraphQL endpoint. See [`getStorefrontApiUrl` in Hydrogen React](/docs/api/hydrogen-react/2023-10/utilities/createstorefrontclient#:~:text=storeDomain-,getStorefrontApiUrl,-(props%3F%3A) for more details.
(props?: Partial<Pick<StorefrontClientProps, "storeDomain" | "storefrontApiVersion">>) => string - isApiError
Determines if the error is resulted from a Storefront API call.
(error: any) => boolean - i18n
The `i18n` object passed in from the `createStorefrontClient` argument.
TI18n
{
/** The function to run a query on Storefront API. */
query: <OverrideReturnType = any, RawGqlString extends string = string>(
query: RawGqlString,
...options: RawGqlString extends keyof StorefrontQueries // Do we have any generated query types?
? IsOptionalVariables<StorefrontQueries[RawGqlString]> extends true
? [StorefrontQuerySecondParam<RawGqlString>?] // Using codegen, query has no variables
: [StorefrontQuerySecondParam<RawGqlString>] // Using codegen, query needs variables
: [StorefrontQuerySecondParam?] // No codegen, variables always optional
) => Promise<
RawGqlString extends keyof StorefrontQueries // Do we have any generated query types?
? StorefrontQueries[RawGqlString]['return'] // Using codegen, return type is known
: OverrideReturnType // No codegen, let user specify return type
>;
/** The function to run a mutation on Storefront API. */
mutate: <OverrideReturnType = any, RawGqlString extends string = string>(
mutation: RawGqlString,
...options: RawGqlString extends keyof StorefrontMutations // Do we have any generated mutation types?
? IsOptionalVariables<StorefrontMutations[RawGqlString]> extends true
? [StorefrontMutateSecondParam<RawGqlString>?] // Using codegen, mutation has no variables
: [StorefrontMutateSecondParam<RawGqlString>] // Using codegen, mutation needs variables
: [StorefrontMutateSecondParam?] // No codegen, variables always optional
) => Promise<
RawGqlString extends keyof StorefrontMutations // Do we have any generated mutation types?
? StorefrontMutations[RawGqlString]['return'] // Using codegen, return type is known
: OverrideReturnType // No codegen, let user specify return type
>;
/** The cache instance passed in from the `createStorefrontClient` argument. */
cache?: Cache;
/** Re-export of [`CacheNone`](/docs/api/hydrogen/2023-10/utilities/cachenone). */
CacheNone: typeof CacheNone;
/** Re-export of [`CacheLong`](/docs/api/hydrogen/2023-10/utilities/cachelong). */
CacheLong: typeof CacheLong;
/** Re-export of [`CacheShort`](/docs/api/hydrogen/2023-10/utilities/cacheshort). */
CacheShort: typeof CacheShort;
/** Re-export of [`CacheCustom`](/docs/api/hydrogen/2023-10/utilities/cachecustom). */
CacheCustom: typeof CacheCustom;
/** Re-export of [`generateCacheControlHeader`](/docs/api/hydrogen/2023-10/utilities/generatecachecontrolheader). */
generateCacheControlHeader: typeof generateCacheControlHeader;
/** Returns an object that contains headers that are needed for each query to Storefront API GraphQL endpoint. See [`getPublicTokenHeaders` in Hydrogen React](/docs/api/hydrogen-react/2023-10/utilities/createstorefrontclient#:~:text=%27graphql%27.-,getPublicTokenHeaders,-(props%3F%3A) for more details. */
getPublicTokenHeaders: ReturnType<
typeof createStorefrontUtilities
>['getPublicTokenHeaders'];
/** Returns an object that contains headers that are needed for each query to Storefront API GraphQL endpoint for API calls made from a server. See [`getPrivateTokenHeaders` in Hydrogen React](/docs/api/hydrogen-react/2023-10/utilities/createstorefrontclient#:~:text=storefrontApiVersion-,getPrivateTokenHeaders,-(props%3F%3A) for more details.*/
getPrivateTokenHeaders: ReturnType<
typeof createStorefrontUtilities
>['getPrivateTokenHeaders'];
/** Creates the fully-qualified URL to your myshopify.com domain. See [`getShopifyDomain` in Hydrogen React](/docs/api/hydrogen-react/2023-10/utilities/createstorefrontclient#:~:text=StorefrontClientReturn-,getShopifyDomain,-(props%3F%3A) for more details. */
getShopifyDomain: ReturnType<
typeof createStorefrontUtilities
>['getShopifyDomain'];
/** Creates the fully-qualified URL to your store's GraphQL endpoint. See [`getStorefrontApiUrl` in Hydrogen React](/docs/api/hydrogen-react/2023-10/utilities/createstorefrontclient#:~:text=storeDomain-,getStorefrontApiUrl,-(props%3F%3A) for more details.*/
getApiUrl: ReturnType<
typeof createStorefrontUtilities
>['getStorefrontApiUrl'];
/** Determines if the error is resulted from a Storefront API call. */
isApiError: (error: any) => boolean;
/** The `i18n` object passed in from the `createStorefrontClient` argument. */
i18n: TI18n;
}IsOptionalVariables
Omit<
OperationTypeValue['variables'],
AutoAddedVariableNames
> extends EmptyVariables
? true // No need to pass variables
: GenericVariables extends OperationTypeValue['variables']
? true // We don't know what variables are needed
: falseAutoAddedVariableNames
'country' | 'language'EmptyVariables
{[key: string]: never}GenericVariables
ExecutionArgs['variableValues']StorefrontQueries
Maps all the queries found in the project to variables and return types.
export interface StorefrontQueries {
// Example of how a generated query type looks like:
// '#graphql query q1 {...}': {return: Q1Query; variables: Q1QueryVariables};
}StorefrontQuerySecondParam
(RawGqlString extends keyof StorefrontQueries
? StorefrontCommonOptions<StorefrontQueries[RawGqlString]['variables']>
: StorefrontCommonOptions<GenericVariables>) & {cache?: CachingStrategy}StorefrontCommonOptions
{
headers?: HeadersInit;
storefrontApiVersion?: string;
} & (IsOptionalVariables<{variables: Variables}> extends true
? {variables?: Variables}
: {variables: Variables})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.
- mode
The caching mode, generally `public`, `private`, or `no-store`.
string - 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).
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).
number - 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).
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).
number
AllCacheOptionsStorefrontMutations
Maps all the mutations found in the project to variables and return types.
export interface StorefrontMutations {
// Example of how a generated mutation type looks like:
// '#graphql mutation m1 {...}': {return: M1Mutation; variables: M1MutationVariables};
}StorefrontMutateSecondParam
RawGqlString extends keyof StorefrontMutations
? StorefrontCommonOptions<StorefrontMutations[RawGqlString]['variables']>
: StorefrontCommonOptions<GenericVariables>NoStoreStrategy
- mode
string
{
mode: string;
}AllCacheOptions
Override options for a cache strategy.
- mode
The caching mode, generally `public`, `private`, or `no-store`.
string - 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).
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).
number - 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).
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).
number
export interface AllCacheOptions {
/**
* The caching mode, generally `public`, `private`, or `no-store`.
*/
mode?: string;
/**
* 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).
*/
maxAge?: number;
/**
* 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).
*/
staleWhileRevalidate?: number;
/**
* 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).
*/
sMaxAge?: number;
/**
* 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).
*/
staleIfError?: number;
}CartCreateFunction
- input
CartInput - optionalParams
CartOptionalInput
Promise<CartQueryData>export type CartCreateFunction = (
input: CartInput,
optionalParams?: CartOptionalInput,
) => Promise<CartQueryData>;CartInput
CartInputCartOptionalInput
- cartId
The cart id.
string - country
The country code.
CountryCode - language
The language code.
LanguageCode
{
/**
* The cart id.
* @default cart.getCartId();
*/
cartId?: Scalars['ID']['input'];
/**
* The country code.
* @default storefront.i18n.country
*/
country?: CountryCode;
/**
* The language code.
* @default storefront.i18n.language
*/
language?: LanguageCode;
}CartQueryData
- cart
Cart - errors
CartUserError[] | MetafieldsSetUserError[] | MetafieldDeleteUserError[]
{
cart: Cart;
errors?:
| CartUserError[]
| MetafieldsSetUserError[]
| MetafieldDeleteUserError[];
}Cart
CartCartUserError
CartUserErrorMetafieldsSetUserError
MetafieldsSetUserErrorMetafieldDeleteUserError
MetafieldDeleteUserErrorExample
JavaScript
Examples
example
Description
This is the default example
JavaScript
import {cartCreateDefault} from '@shopify/hydrogen'; const cartCreate = cartCreateDefault({ storefront, getCartId, }); const result = await cartCreate({ lines: [ { merchandiseId: 'gid://shopify/ProductVariant/123456789', quantity: 1, }, ], });