Choose a version:

Metafields
API

Requires access to protected customer data for some properties.

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 appMetafields appMetafields StatefulRemoteSubscribable<[]> 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.

Tip
Cart metafields are only available on carts created via the Storefront API version 2023-04 or later.*
Anchor to metafields metafields StatefulRemoteSubscribable<[]> 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

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';
}

Was this section helpful?

Anchor to useAppMetafields
useAppMetafields(
filters
)

Returns the metafields configured with shopify.extension.toml.

Anchor to useAppMetafields-parametersParameters

Anchor to filters filters Default: {}

Anchor to useAppMetafields-returnsReturns

[]

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;
}

Was this section helpful?

Anchor to useMetafield
useMetafield(
filters
)

Returns a single filtered Metafield or undefined.

Anchor to useMetafield-parametersParameters

Anchor to filters filters required

Anchor to useMetafield-returnsReturns

| 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';
}

Was this section helpful?

Anchor to useMetafields
useMetafields(
filters
)

Returns the current array of metafields applied to the checkout. You can optionally filter the list.

Anchor to useMetafields-parametersParameters

Anchor to filters filters

Anchor to useMetafields-returnsReturns

[]

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';
}

Was this section helpful?

Anchor to checkoutapiCheckoutApi

The API object provided to purchase.checkout extension targets.

Anchor to applyMetafieldChange applyMetafieldChange (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.

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;
}

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;
}

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;
}

Was this section helpful?

Anchor to useApplyMetafieldsChange
useApplyMetafieldsChange()

Returns a function to mutate the metafields property of the checkout.

Anchor to useApplyMetafieldsChange-returnsReturns

(change: ) => Promise<>

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;
}

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;
}

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;
}

Was this section helpful?