Metafields

API

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

• key

  string

• namespace

  To filter for app owned metafields, use the `$app` format. The fully qualified reserved namespace format such as `app--{your-app-id}[--{optional-namespace}]` is not supported. See [app owned metafields](/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.

  string

• type

  "customer" | "product" | "shop" | "shopUser" | "variant" | "company" | "companyLocation" | "cart"

interface AppMetafieldFilters {
  id?: AppMetafieldEntryTarget['id'];
  type?: AppMetafieldEntryTarget['type'];
  /**
   * To filter for app owned metafields, use the `$app` format. The fully qualified reserved namespace format such as `app--{your-app-id}[--{optional-namespace}]` is not supported.
   *
   * See [app owned metafields](/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.
   */
  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. App owned metafield namespaces are returned using the `$app` format. See [app owned metafields](/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.

  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.
   *
   * App owned metafield namespaces are returned using the `$app` format. See [app owned metafields](/docs/apps/build/custom-data/ownership#reserved-prefixes) for more information.
   */
  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'
      | 'shopUser'
      | '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'
    | 'shopUser'
    | 'variant'
    | 'company'
    | 'companyLocation'
    | 'cart';

  /** The numeric owner ID that is associated with the metafield. */
  id: string;
}

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

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

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

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

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.

• key

  The name of the metafield to remove.

  string

• namespace

  The namespace of the metafield to remove.

  string

• type

  The type of the `MetafieldRemoveChange` API.

  "removeMetafield"

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.

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

MetafieldUpdateChange

Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created.

• key

  The name of the metafield to update.

  string

• namespace

  The namespace of the metafield to add.

  string

• type

  The type of the `MetafieldUpdateChange` API.

  "updateMetafield"

• value

  The new information to store in the metafield.

  string | number

• valueType

  The metafield’s information type.

  'integer' | 'string' | '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.

• key

  The name of the metafield to remove.

  string

• namespace

  The namespace of the metafield to remove.

  string

• type

  The type of the `MetafieldRemoveChange` API.

  "removeCartMetafield"

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

• type

  The metafield's type name.

  string

• value

  The value of a metafield.

  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.

• metafield

  { key: string; namespace: string; value: string; type: string; }

• type

  The type of the `MetafieldUpdateChange` API.

  "updateCartMetafield"

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

• 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

• type

  The type of the `MetafieldChangeResultError` API.

  "error"

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