MetafieldsAPI
The API for interacting with metafields.
Anchor to standardapiStandardApi
The base API object provided to purchase
, and customer-account.order-status
extension targets.
- Anchor to appMetafieldsappMetafieldsStatefulRemoteSubscribable<[]>required
The metafields requested in the
shopify.extension.toml
file. These metafields are updated when there's a change in the merchandise items being purchased by the customer.Requires access to protected customer data.
TipCart metafields are only available on carts created via the Storefront API version
2023-04
or later.*- Anchor to metafieldsmetafieldsStatefulRemoteSubscribable<[]>required
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_Standard_MetafieldsApi
- appMetafields
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.*
StatefulRemoteSubscribable<AppMetafieldEntry[]>
- metafields
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)
StatefulRemoteSubscribable<Metafield[]>
export interface Docs_Standard_MetafieldsApi
extends Pick<StandardApi, 'appMetafields' | 'metafields'> {}
AppMetafieldEntry
A metafield associated with the shop or a resource on the checkout.
- 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
- metafield
The metadata information.
AppMetafield
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;
}
AppMetafieldEntryTarget
The metafield owner.
- 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`.
"cart" | "shop" | "customer" | "product" | "shopUser" | "variant" | "company" | "companyLocation"
- id
The numeric owner ID that is associated with the metafield.
string
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'
| 'shopUser'
| 'variant'
| 'company'
| 'companyLocation'
| 'cart';
/** The numeric owner ID that is associated with the metafield. */
id: string;
}
AppMetafield
Represents a custom metadata attached to a resource.
- key
The key name of a metafield.
string
- namespace
The namespace for a metafield.
string
- value
The value of a metafield.
string | number | boolean
- valueType
The metafield’s information type.
"string" | "boolean" | "integer" | "json_string" | "float"
- type
The metafield's type name.
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;
}
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.
"string" | "integer" | "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.extension.toml`.
- filters
AppMetafieldFilters
AppMetafieldEntry[]
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]);
}
AppMetafieldFilters
- id
string
- type
"variant" | "shop" | "customer" | "product" | "shopUser" | "company" | "companyLocation" | "cart"
- namespace
string
- key
string
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.
- 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
- metafield
The metadata information.
AppMetafield
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;
}
AppMetafieldEntryTarget
The metafield owner.
- 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`.
"cart" | "shop" | "customer" | "product" | "shopUser" | "variant" | "company" | "companyLocation"
- id
The numeric owner ID that is associated with the metafield.
string
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'
| 'shopUser'
| 'variant'
| 'company'
| 'companyLocation'
| 'cart';
/** The numeric owner ID that is associated with the metafield. */
id: string;
}
AppMetafield
Represents a custom metadata attached to a resource.
- key
The key name of a metafield.
string
- namespace
The namespace for a metafield.
string
- value
The value of a metafield.
string | number | boolean
- valueType
The metafield’s information type.
"string" | "boolean" | "integer" | "json_string" | "float"
- type
The metafield's type name.
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;
}
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 | undefined
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;
}
MetafieldFilter
- namespace
string
- key
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.
"string" | "integer" | "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 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]);
}
MetafieldsFilters
- namespace
string
- key
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.
"string" | "integer" | "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';
}
Anchor to checkoutapiCheckoutApi
The API object provided to purchase.checkout
extension targets.
- Anchor to applyMetafieldChangeapplyMetafieldChange(change: ) => Promise<>required
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
property.
Docs_Checkout_MetafieldsApi
- applyMetafieldChange
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.
(change: MetafieldChange) => Promise<MetafieldChangeResult>
export interface Docs_Checkout_MetafieldsApi
extends Pick<CheckoutApi, 'applyMetafieldChange'> {}
MetafieldChange
MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange
MetafieldRemoveChange
Removes a metafield.
- type
The type of the `MetafieldRemoveChange` API.
"removeMetafield"
- key
The name of the metafield to remove.
string
- namespace
The namespace of the metafield to remove.
string
export interface MetafieldRemoveChange {
/**
* The type of the `MetafieldRemoveChange` API.
*/
type: 'removeMetafield';
/**
* The name of the metafield to remove.
*/
key: string;
/**
* The namespace of the metafield to remove.
*/
namespace: 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.
"string" | "integer" | "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';
}
MetafieldUpdateChange
Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created.
- type
The type of the `MetafieldUpdateChange` API.
"updateMetafield"
- key
The name of the metafield to update.
string
- namespace
The namespace of the metafield to add.
string
- value
The new information to store in the metafield.
string | number
- valueType
The metafield’s information type.
"string" | "integer" | "json_string"
export interface MetafieldUpdateChange {
/**
* The type of the `MetafieldUpdateChange` API.
*/
type: 'updateMetafield';
/** The name of the metafield to update. */
key: string;
/** The namespace of the metafield to add. */
namespace: string;
/** The new information to store in the metafield. */
value: string | number;
/**
* The metafield’s information type.
*/
valueType: 'integer' | 'string' | 'json_string';
}
MetafieldRemoveCartChange
Removes a cart metafield.
- type
The type of the `MetafieldRemoveChange` API.
"removeCartMetafield"
- key
The name of the metafield to remove.
string
- namespace
The namespace of the metafield to remove.
string
export interface MetafieldRemoveCartChange {
/**
* The type of the `MetafieldRemoveChange` API.
*/
type: 'removeCartMetafield';
/**
* The name of the metafield to remove.
*/
key: string;
/**
* The namespace of the metafield to remove.
*/
namespace: string;
}
CartMetafield
Represents a custom metadata attached to a resource.
- key
The key name of a metafield.
string
- namespace
The namespace for a metafield.
string
- value
The value of a metafield.
string
- type
The metafield's type name.
string
export interface CartMetafield {
/** The key name of a metafield. */
key: string;
/** The namespace for a metafield. */
namespace: string;
/** The value of a metafield. */
value: string;
/** The metafield's type name. */
type: string;
}
MetafieldUpdateCartChange
Updates a cart metafield. If a metafield with the provided key and namespace does not already exist, it gets created.
- type
The type of the `MetafieldUpdateChange` API.
"updateCartMetafield"
- metafield
{ key: string; namespace: string; value: string; type: string; }
export interface MetafieldUpdateCartChange {
/**
* The type of the `MetafieldUpdateChange` API.
*/
type: 'updateCartMetafield';
metafield: {
/** The name of the metafield to update. */
key: string;
/** The namespace of the metafield to add. */
namespace: string;
/** The new information to store in the metafield. */
value: string;
/**
* The metafield’s information type.
* See the [`metafields documentation`](/docs/apps/custom-data/metafields/types) for a list of supported types.
*/
type: string;
};
}
MetafieldChangeResult
MetafieldChangeResultSuccess | MetafieldChangeResultError
MetafieldChangeResultSuccess
- type
The type of the `MetafieldChangeResultSuccess` API.
"success"
export interface MetafieldChangeResultSuccess {
/**
* The type of the `MetafieldChangeResultSuccess` API.
*/
type: 'success';
}
MetafieldChangeResultError
- type
The type of the `MetafieldChangeResultError` API.
"error"
- message
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.
string
export interface MetafieldChangeResultError {
/**
* The type of the `MetafieldChangeResultError` API.
*/
type: 'error';
/**
* 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.
*/
message: string;
}
Anchor to useApplyMetafieldsChangeuse Apply Metafields Change()
Returns a function to mutate the metafields
property of the checkout.
UseApplyMetafieldsChangeGeneratedType
Returns a function to mutate the `metafields` property of the checkout.
(change: MetafieldChange) => Promise<MetafieldChangeResult>
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,
);
}
MetafieldChange
MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange
MetafieldRemoveChange
Removes a metafield.
- type
The type of the `MetafieldRemoveChange` API.
"removeMetafield"
- key
The name of the metafield to remove.
string
- namespace
The namespace of the metafield to remove.
string
export interface MetafieldRemoveChange {
/**
* The type of the `MetafieldRemoveChange` API.
*/
type: 'removeMetafield';
/**
* The name of the metafield to remove.
*/
key: string;
/**
* The namespace of the metafield to remove.
*/
namespace: 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.
"string" | "integer" | "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';
}
MetafieldUpdateChange
Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created.
- type
The type of the `MetafieldUpdateChange` API.
"updateMetafield"
- key
The name of the metafield to update.
string
- namespace
The namespace of the metafield to add.
string
- value
The new information to store in the metafield.
string | number
- valueType
The metafield’s information type.
"string" | "integer" | "json_string"
export interface MetafieldUpdateChange {
/**
* The type of the `MetafieldUpdateChange` API.
*/
type: 'updateMetafield';
/** The name of the metafield to update. */
key: string;
/** The namespace of the metafield to add. */
namespace: string;
/** The new information to store in the metafield. */
value: string | number;
/**
* The metafield’s information type.
*/
valueType: 'integer' | 'string' | 'json_string';
}
MetafieldRemoveCartChange
Removes a cart metafield.
- type
The type of the `MetafieldRemoveChange` API.
"removeCartMetafield"
- key
The name of the metafield to remove.
string
- namespace
The namespace of the metafield to remove.
string
export interface MetafieldRemoveCartChange {
/**
* The type of the `MetafieldRemoveChange` API.
*/
type: 'removeCartMetafield';
/**
* The name of the metafield to remove.
*/
key: string;
/**
* The namespace of the metafield to remove.
*/
namespace: string;
}
CartMetafield
Represents a custom metadata attached to a resource.
- key
The key name of a metafield.
string
- namespace
The namespace for a metafield.
string
- value
The value of a metafield.
string
- type
The metafield's type name.
string
export interface CartMetafield {
/** The key name of a metafield. */
key: string;
/** The namespace for a metafield. */
namespace: string;
/** The value of a metafield. */
value: string;
/** The metafield's type name. */
type: string;
}
MetafieldUpdateCartChange
Updates a cart metafield. If a metafield with the provided key and namespace does not already exist, it gets created.
- type
The type of the `MetafieldUpdateChange` API.
"updateCartMetafield"
- metafield
{ key: string; namespace: string; value: string; type: string; }
export interface MetafieldUpdateCartChange {
/**
* The type of the `MetafieldUpdateChange` API.
*/
type: 'updateCartMetafield';
metafield: {
/** The name of the metafield to update. */
key: string;
/** The namespace of the metafield to add. */
namespace: string;
/** The new information to store in the metafield. */
value: string;
/**
* The metafield’s information type.
* See the [`metafields documentation`](/docs/apps/custom-data/metafields/types) for a list of supported types.
*/
type: string;
};
}
MetafieldChangeResult
MetafieldChangeResultSuccess | MetafieldChangeResultError
MetafieldChangeResultSuccess
- type
The type of the `MetafieldChangeResultSuccess` API.
"success"
export interface MetafieldChangeResultSuccess {
/**
* The type of the `MetafieldChangeResultSuccess` API.
*/
type: 'success';
}
MetafieldChangeResultError
- type
The type of the `MetafieldChangeResultError` API.
"error"
- message
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.
string
export interface MetafieldChangeResultError {
/**
* The type of the `MetafieldChangeResultError` API.
*/
type: 'error';
/**
* 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.
*/
message: string;
}