# Metafields The API for interacting with metafields. ## OrderStatusApi The API object provided to this and other `customer-account.order-status` extension targets. ### Docs_OrderStatus_MetafieldsApi ### appMetafields value: `StatefulRemoteSubscribable` The metafields requested in the [`shopify.ui.extension.toml`](https://shopify.dev/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](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### metafields value: `StatefulRemoteSubscribable` The metafields that apply to the current order. The actual resource on which these metafields exist depends on the source of the order: - If the source is an order, then the metafields are on the order. - If the source is a draft order, then the initial value of metafields are from the draft order, and any new metafields you write are applied to the order created by the checkout. - For all other sources, the metafields are only stored locally on the client creating the checkout, and are applied to the order that results from checkout. 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](https://shopify.dev/docs/admin-api/graphql/reference/orders/order#metafield-2021-01) ### AppMetafieldEntry A metafield associated with the shop or a resource on the checkout. ### metafield value: `AppMetafield` The metadata information. ### target value: `AppMetafieldEntryTarget` The target that is associated to the metadata. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`. ### AppMetafield Represents a custom metadata attached to a resource. ### key value: `string` The key name of a metafield. ### namespace value: `string` The namespace for a metafield. ### type value: `string` The metafield's type name. ### value value: `string | number | boolean` The value of a metafield. ### valueType value: `'boolean' | 'float' | 'integer' | 'json_string' | 'string'` The metafield’s information type. ### AppMetafieldEntryTarget The metafield owner. ### id value: `string` The numeric owner ID that is associated with the metafield. ### type value: `| 'customer' | 'product' | 'shop' | 'variant' | 'company' | 'companyLocation' | 'cart'` The type of the metafield owner. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`. ### Metafield Metadata associated with the checkout. ### key value: `string` The name of the metafield. It must be between 3 and 30 characters in length (inclusive). ### namespace value: `string` 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). ### value value: `string | number` The information to be stored as metadata. ### valueType value: `'integer' | 'string' | 'json_string'` The metafield’s information type. ## useAppMetafields Returns the metafields configured with `shopify.extension.toml`. ### UseAppMetafieldsGeneratedType Returns the metafields configured with `shopify.ui.extension.toml`. #### Returns: AppMetafieldEntry[] #### Params: - filters: AppMetafieldFilters export function useAppMetafields< Target extends RenderOrderStatusExtensionTarget = RenderOrderStatusExtensionTarget, >(filters: AppMetafieldFilters = {}): AppMetafieldEntry[] { const api = useApi(); const extensionTarget = api.extension.target; if (!('appMetafields' in api)) { throw new ExtensionHasNoFieldError('appMetafields', extensionTarget); } const appMetafields = useSubscription(api.appMetafields); return useMemo(() => { if (filters.key && !filters.namespace) { throw new CustomerAccountUIExtensionError( '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]); } ### AppMetafieldFilters ### id value: `AppMetafieldEntryTarget` ### key value: `Metafield` ### namespace value: `Metafield` ### type value: `AppMetafieldEntryTarget` ### AppMetafieldEntryTarget The metafield owner. ### id value: `string` The numeric owner ID that is associated with the metafield. ### type value: `| 'customer' | 'product' | 'shop' | 'variant' | 'company' | 'companyLocation' | 'cart'` The type of the metafield owner. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`. ### Metafield Metadata associated with the checkout. ### key value: `string` The name of the metafield. It must be between 3 and 30 characters in length (inclusive). ### namespace value: `string` 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). ### value value: `string | number` The information to be stored as metadata. ### valueType value: `'integer' | 'string' | 'json_string'` The metafield’s information type. ### AppMetafieldEntry A metafield associated with the shop or a resource on the checkout. ### metafield value: `AppMetafield` The metadata information. ### target value: `AppMetafieldEntryTarget` The target that is associated to the metadata. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`. ### AppMetafield Represents a custom metadata attached to a resource. ### key value: `string` The key name of a metafield. ### namespace value: `string` The namespace for a metafield. ### type value: `string` The metafield's type name. ### value value: `string | number | boolean` The value of a metafield. ### valueType value: `'boolean' | 'float' | 'integer' | 'json_string' | 'string'` The metafield’s information type. ## useMetafield Returns a single filtered `Metafield` or `undefined`. ### UseMetafieldGeneratedType Returns a single filtered `Metafield` or `undefined`. #### Returns: Metafield | undefined #### Params: - filters: MetafieldFilter export function useMetafield(filters: MetafieldFilter): Metafield | undefined { const {namespace, key} = filters; if (!namespace || !key) { throw new CustomerAccountUIExtensionError( 'You must pass in both a namespace and key', ); } const metafields = useMetafields({namespace, key}); return metafields.length ? metafields[0] : undefined; } ### MetafieldFilter ### key value: `string` ### namespace value: `string` ### Metafield Metadata associated with the checkout. ### key value: `string` The name of the metafield. It must be between 3 and 30 characters in length (inclusive). ### namespace value: `string` 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). ### value value: `string | number` The information to be stored as metadata. ### valueType value: `'integer' | 'string' | 'json_string'` The metafield’s information type. ## useMetafields Returns the current array of `metafields` applied to the checkout. You can optionally filter the list. ### UseMetafieldsGeneratedType Returns the current array of `metafields` applied to the checkout. You can optionally filter the list. #### Returns: Metafield[] #### Params: - filters: MetafieldsFilters export function useMetafields< Target extends RenderOrderStatusExtensionTarget = RenderOrderStatusExtensionTarget, >(filters?: MetafieldsFilters): Metafield[] { const api = useApi(); const extensionTarget = api.extension.target; if (!('metafields' in api)) { throw new ExtensionHasNoFieldError('metafields', extensionTarget); } const metaFields = useSubscription(api.metafields); return useMemo(() => { if (filters) { const {namespace, key} = filters; if (!namespace) { throw new CustomerAccountUIExtensionError( '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]); } ### MetafieldsFilters ### key value: `string` ### namespace value: `string` ### Metafield Metadata associated with the checkout. ### key value: `string` The name of the metafield. It must be between 3 and 30 characters in length (inclusive). ### namespace value: `string` 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). ### value value: `string | number` The information to be stored as metadata. ### valueType value: `'integer' | 'string' | 'json_string'` The metafield’s information type.