Skip to main content

Metafields

Requires access to protected customer data for some properties.

The API for interacting with metafields.

The base API object provided to purchase extension targets.

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

App owned metafields are supported and are returned using the $app format. The fully qualified reserved namespace format such as app--{your-app-id}[--{optional-namespace}] is not supported. See app owned metafields for more information.

Requires access to protected customer data.

Anchor to metafields
metafields
<[]>
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

Caution

metafields is deprecated. Use appMetafields with cart metafields instead.

Deprecated

Use appMetafields with cart metafields instead.

Returns the metafields configured with shopify.extension.toml.

Anchor to filters
filters
Default: {}

[]

Returns a single filtered Metafield or undefined.

Caution

useMetafield is deprecated. Use useAppMetafields with cart metafields instead.

Anchor to filters
filters
required

| undefined

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

Caution

useMetafields is deprecated. Use useAppMetafields with cart metafields instead.

Anchor to filters
filters

[]

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.

Cart metafields will be copied to order metafields at order creation time if there is a matching order metafield definition with the cart to order copyable capability enabled.

Caution

MetafieldRemoveChange and MetafieldUpdateChange are deprecated. Use cart metafields with MetafieldRemoveCartChange and MetafieldUpdateCartChange instead. If MetafieldUpdateChange writes a metafield with the same namespace and key as a cart metafield that’s configured to copy, the cart metafield won’t be copied.

Note

This method will return an error if the cart instruction metafields.canSetCartMetafields is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

Anchor to useApplyMetafieldsChange
useApplyMetafieldsChange()

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

(change: ) => Promise<>
Examples
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

import {useAppMetafields} from '@shopify/ui-extensions/checkout/preact';

export default function extension() {
render(<Extension />, document.body);
}

function Extension() {
const [energyRating] = useAppMetafields({
namespace: '$app',
key: 'energy-rating',
type: 'product',
}).filter(
(entry) =>
entry.target.id ===
shopify.target.value.merchandise.id,
);

return (
energyRating && (
<s-text>
Energy rating:{' '}
{energyRating.metafield.value}
</s-text>
)
);
}
Was this page helpful?