MetafieldsAPI
The API for interacting with metafields.
Anchor to orderstatusapiOrderStatusApi
The API object provided to this and other customer-account.order-status extension targets.
- Anchor to appMetafieldsappMetafieldsStatefulRemoteSubscribable<[]>required
The metafields requested in the
shopify.ui.extension.tomlfile. These metafields are updated when there's a change in the merchandise items being purchased by the customer.Requires access to protected customer data.
- Anchor to metafieldsmetafieldsStatefulRemoteSubscribable<[]>required
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
Docs_OrderStatus_MetafieldsApi
- appMetafields
The metafields requested in the [`shopify.ui.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).
StatefulRemoteSubscribable<AppMetafieldEntry[]> - metafields
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](/docs/admin-api/graphql/reference/orders/order#metafield-2021-01)
StatefulRemoteSubscribable<Metafield[]>
export interface Docs_OrderStatus_MetafieldsApi
extends Pick<OrderStatusApi<any>, 'appMetafields' | 'metafields'> {}AppMetafieldEntry
A metafield associated with the shop or a resource on the checkout.
- metafield
The metadata information.
AppMetafield - target
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`.
AppMetafieldEntryTarget
export interface AppMetafieldEntry {
/**
* 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`.
*/
target: AppMetafieldEntryTarget;
/** The metadata information. */
metafield: AppMetafield;
}AppMetafield
Represents a custom metadata attached to a resource.
- key
The key name of a metafield.
string - namespace
The namespace for a metafield.
string - type
The metafield's type name.
string - value
The value of a metafield.
string | number | boolean - valueType
The metafield’s information type.
'boolean' | 'float' | 'integer' | 'json_string' | 'string'
export interface AppMetafield {
/** The key name of a metafield. */
key: string;
/** The namespace for a metafield. */
namespace: string;
/** The value of a metafield. */
value: string | number | boolean;
/** The metafield’s information type. */
valueType: 'boolean' | 'float' | 'integer' | 'json_string' | 'string';
/** The metafield's type name. */
type: string;
}AppMetafieldEntryTarget
The metafield owner.
- id
The numeric owner ID that is associated with the metafield.
string - type
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`.
| 'customer' | 'product' | 'shop' | 'variant' | 'company' | 'companyLocation' | 'cart'
export interface AppMetafieldEntryTarget {
/**
* 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`.
*/
type:
| 'customer'
| 'product'
| 'shop'
| 'variant'
| 'company'
| 'companyLocation'
| 'cart';
/** The numeric owner ID that is associated with the metafield. */
id: string;
}Metafield
Metadata associated with the checkout.
- key
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
string - namespace
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).
string - value
The information to be stored as metadata.
string | number - valueType
The metafield’s information type.
'integer' | 'string' | 'json_string'
export interface Metafield {
/**
* The name of the metafield. It must be between 3 and 30 characters in
* length (inclusive).
*/
key: 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).
*/
namespace: string;
/**
* The information to be stored as metadata.
*/
value: string | number;
/** The metafield’s information type. */
valueType: 'integer' | 'string' | 'json_string';
}Returns the metafields configured with shopify.extension.toml.
Anchor to useAppMetafields-parametersParameters
- Anchor to filtersfiltersDefault: {}
UseAppMetafieldsGeneratedType
Returns the metafields configured with `shopify.ui.extension.toml`.
- filters
AppMetafieldFilters
AppMetafieldEntry[]export function useAppMetafields<
Target extends RenderOrderStatusExtensionTarget = RenderOrderStatusExtensionTarget,
>(filters: AppMetafieldFilters = {}): AppMetafieldEntry[] {
const api = useApi<Target>();
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
string - key
string - namespace
string - type
"variant" | "customer" | "product" | "shop" | "company" | "companyLocation" | "cart"
interface AppMetafieldFilters {
id?: AppMetafieldEntryTarget['id'];
type?: AppMetafieldEntryTarget['type'];
namespace?: Metafield['namespace'];
key?: Metafield['key'];
}AppMetafieldEntry
A metafield associated with the shop or a resource on the checkout.
- metafield
The metadata information.
AppMetafield - target
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`.
AppMetafieldEntryTarget
export interface AppMetafieldEntry {
/**
* 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`.
*/
target: AppMetafieldEntryTarget;
/** The metadata information. */
metafield: AppMetafield;
}AppMetafield
Represents a custom metadata attached to a resource.
- key
The key name of a metafield.
string - namespace
The namespace for a metafield.
string - type
The metafield's type name.
string - value
The value of a metafield.
string | number | boolean - valueType
The metafield’s information type.
'boolean' | 'float' | 'integer' | 'json_string' | 'string'
export interface AppMetafield {
/** The key name of a metafield. */
key: string;
/** The namespace for a metafield. */
namespace: string;
/** The value of a metafield. */
value: string | number | boolean;
/** The metafield’s information type. */
valueType: 'boolean' | 'float' | 'integer' | 'json_string' | 'string';
/** The metafield's type name. */
type: string;
}AppMetafieldEntryTarget
The metafield owner.
- id
The numeric owner ID that is associated with the metafield.
string - type
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`.
| 'customer' | 'product' | 'shop' | 'variant' | 'company' | 'companyLocation' | 'cart'
export interface AppMetafieldEntryTarget {
/**
* 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`.
*/
type:
| 'customer'
| 'product'
| 'shop'
| 'variant'
| 'company'
| 'companyLocation'
| 'cart';
/** The numeric owner ID that is associated with the metafield. */
id: string;
}Returns a single filtered Metafield or undefined.
Anchor to useMetafield-parametersParameters
- Anchor to filtersfiltersrequired
UseMetafieldGeneratedType
Returns a single filtered `Metafield` or `undefined`.
- filters
MetafieldFilter
Metafield | undefinedexport 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
string - namespace
string
interface MetafieldFilter {
namespace: string;
key: string;
}Metafield
Metadata associated with the checkout.
- key
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
string - namespace
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).
string - value
The information to be stored as metadata.
string | number - valueType
The metafield’s information type.
'integer' | 'string' | 'json_string'
export interface Metafield {
/**
* The name of the metafield. It must be between 3 and 30 characters in
* length (inclusive).
*/
key: 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).
*/
namespace: string;
/**
* The information to be stored as metadata.
*/
value: string | number;
/** The metafield’s information type. */
valueType: 'integer' | 'string' | 'json_string';
}Returns the current array of metafields applied to the checkout. You can optionally filter the list.
Anchor to useMetafields-parametersParameters
- Anchor to filtersfilters
UseMetafieldsGeneratedType
Returns the current array of `metafields` applied to the checkout. You can optionally filter the list.
- filters
MetafieldsFilters
Metafield[]export function useMetafields<
Target extends RenderOrderStatusExtensionTarget = RenderOrderStatusExtensionTarget,
>(filters?: MetafieldsFilters): Metafield[] {
const api = useApi<Target>();
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
string - namespace
string
interface MetafieldsFilters {
namespace: string;
key?: string;
}Metafield
Metadata associated with the checkout.
- key
The name of the metafield. It must be between 3 and 30 characters in length (inclusive).
string - namespace
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).
string - value
The information to be stored as metadata.
string | number - valueType
The metafield’s information type.
'integer' | 'string' | 'json_string'
export interface Metafield {
/**
* The name of the metafield. It must be between 3 and 30 characters in
* length (inclusive).
*/
key: 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).
*/
namespace: string;
/**
* The information to be stored as metadata.
*/
value: string | number;
/** The metafield’s information type. */
valueType: 'integer' | 'string' | 'json_string';
}