The API for interacting with metafields.
The base API object provided to `purchase`, and `customer-account.order-status` extension targets.
The metafields requested in the [`shopify.extension.toml`](/docs/api/checkout-ui-extensions/configuration) file. These metafields are updated when there's a change in the merchandise items being purchased by the customer. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data). > Tip: > Cart metafields are only available on carts created via the Storefront API version `2023-04` or later.*
The metafields that apply to the current checkout. Metafields are stored locally on the client and are applied to the order object after the checkout completes. These metafields are shared by all extensions running on checkout, and persist for as long as the customer is working on this checkout. Once the order is created, you can query these metafields using the [GraphQL Admin API](/docs/admin-api/graphql/reference/orders/order#metafield-2021-01)
A metafield associated with the shop or a resource on the checkout.
The target that is associated to the metadata. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
The metadata information.
The metafield owner.
The type of the metafield owner. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
The numeric owner ID that is associated with the metafield.
Represents a custom metadata attached to a resource.
The key name of a metafield.
The namespace for a metafield.
The value of a metafield.
The metafield’s information type.
The metafield's type name.
Metadata associated with the checkout.
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. This must be between 2 and 20 characters in length (inclusive).
The information to be stored as metadata.
The metafield’s information type.
Returns the metafields configured with `shopify.extension.toml`.
Returns the metafields configured with `shopify.extension.toml`.
filters: AppMetafieldFilters
export function useAppMetafields< Target extends RenderExtensionTarget = RenderExtensionTarget, >(filters: AppMetafieldFilters = {}): AppMetafieldEntry[] { const appMetafields = useSubscription(useApi<Target>().appMetafields); return useMemo(() => { if (filters.key && !filters.namespace) { throw new CheckoutUIExtensionError( 'You must pass in a namespace with a key', ); } const filterKeys = Object.keys(filters) as AppMetafieldFilterKeys[]; if (filterKeys.length) { return appMetafields.filter((app) => { return filterKeys.every((key) => { if (key === 'id' || key === 'type') { return app.target[key] === filters[key]; } return app.metafield[key] === filters[key]; }); }); } return appMetafields; }, [filters, appMetafields]); }
A metafield associated with the shop or a resource on the checkout.
The target that is associated to the metadata. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
The metadata information.
The metafield owner.
The type of the metafield owner. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
The numeric owner ID that is associated with the metafield.
Represents a custom metadata attached to a resource.
The key name of a metafield.
The namespace for a metafield.
The value of a metafield.
The metafield’s information type.
The metafield's type name.
Returns a single filtered `Metafield` or `undefined`.
Returns a single filtered `Metafield` or `undefined`.
filters: MetafieldFilter
export function useMetafield(filters: MetafieldFilter): Metafield | undefined { const {namespace, key} = filters; if (!namespace || !key) { throw new CheckoutUIExtensionError( 'You must pass in both a namespace and key', ); } const metafields = useMetafields({namespace, key}); return metafields.length ? metafields[0] : undefined; }
Metadata associated with the checkout.
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. This must be between 2 and 20 characters in length (inclusive).
The information to be stored as metadata.
The metafield’s information type.
Returns the current array of `metafields` applied to the checkout. You can optionally filter the list.
Returns the current array of `metafields` applied to the checkout. You can optionally filter the list.
filters: MetafieldsFilters
export function useMetafields< Target extends RenderExtensionTarget = RenderExtensionTarget, >(filters?: MetafieldsFilters): Metafield[] { const metaFields = useSubscription(useApi<Target>().metafields); return useMemo(() => { if (filters) { const {namespace, key} = filters; if (!namespace) { throw new CheckoutUIExtensionError( 'You must pass in a namespace with a key', ); } const filteredResults = metaFields.filter( (metafield) => metafield.namespace === namespace && (!key || metafield.key === key), ); return filteredResults; } return metaFields; }, [filters, metaFields]); }
Metadata associated with the checkout.
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. This must be between 2 and 20 characters in length (inclusive).
The information to be stored as metadata.
The metafield’s information type.
The API object provided to `purchase.checkout` extension targets.
Performs an update on a piece of metadata attached to the checkout. If successful, this mutation results in an update to the value retrieved through the [`metafields`](/docs/api/checkout-ui-extensions/apis/metafields#standardapi-propertydetail-metafields) property.
MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange
Removes a metafield.
The type of the `MetafieldRemoveChange` API.
The name of the metafield to remove.
The namespace of the metafield to remove.
Metadata associated with the checkout.
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. This must be between 2 and 20 characters in length (inclusive).
The information to be stored as metadata.
The metafield’s information type.
Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created.
The type of the `MetafieldUpdateChange` API.
The name of the metafield to update.
The namespace of the metafield to add.
The new information to store in the metafield.
The metafield’s information type.
Removes a cart metafield.
The type of the `MetafieldRemoveChange` API.
The name of the metafield to remove.
The namespace of the metafield to remove.
Represents a custom metadata attached to a resource.
The key name of a metafield.
The namespace for a metafield.
The value of a metafield.
The metafield's type name.
Updates a cart metafield. If a metafield with the provided key and namespace does not already exist, it gets created.
The type of the `MetafieldUpdateChange` API.
MetafieldChangeResultSuccess | MetafieldChangeResultError
The type of the `MetafieldChangeResultSuccess` API.
The type of the `MetafieldChangeResultError` API.
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
Returns a function to mutate the `metafields` property of the checkout.
Returns a function to mutate the `metafields` property of the checkout.
export function useApplyMetafieldsChange< Target extends RenderExtensionTarget = RenderExtensionTarget, >(): (change: MetafieldChange) => Promise<MetafieldChangeResult> { const api = useApi<Target>(); if ('applyMetafieldChange' in api) { return api.applyMetafieldChange; } throw new ExtensionHasNoMethodError( 'applyMetafieldChange', api.extension.target, ); }
MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange
Removes a metafield.
The type of the `MetafieldRemoveChange` API.
The name of the metafield to remove.
The namespace of the metafield to remove.
Metadata associated with the checkout.
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. This must be between 2 and 20 characters in length (inclusive).
The information to be stored as metadata.
The metafield’s information type.
Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created.
The type of the `MetafieldUpdateChange` API.
The name of the metafield to update.
The namespace of the metafield to add.
The new information to store in the metafield.
The metafield’s information type.
Removes a cart metafield.
The type of the `MetafieldRemoveChange` API.
The name of the metafield to remove.
The namespace of the metafield to remove.
Represents a custom metadata attached to a resource.
The key name of a metafield.
The namespace for a metafield.
The value of a metafield.
The metafield's type name.
Updates a cart metafield. If a metafield with the provided key and namespace does not already exist, it gets created.
The type of the `MetafieldUpdateChange` API.
MetafieldChangeResultSuccess | MetafieldChangeResultError
The type of the `MetafieldChangeResultSuccess` API.
The type of the `MetafieldChangeResultError` API.
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.