Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Attributes API

The API for interacting with cart and checkout attributes.

Use metafields instead of attributes

To store custom data, Shopify recommends that you use the Metafields API to write cart metafields.

Metafields are safer than cart attributes as they support edit and view permissions and app-reserved namespaces to prevent other apps from reading and writing data.

Anchor to StandardApiStandardApi

The base API object provided to purchase extension targets.

Anchor to attributes attributes StatefulRemoteSubscribable<[] | undefined> required: The custom attributes left by the customer to the merchant, either in their cart or during checkout.

Anchor to CheckoutApiCheckoutApi

The API object provided to purchase.checkout extension targets.

Anchor to applyAttributeChange applyAttributeChange (change: ) => Promise<> required: Performs an update on an attribute attached to the cart and checkout. If successful, this mutation results in an update to the value retrieved through the attributes property.

Note
This method will return an error if the cart instruction attributes.canUpdateAttributes is false, or the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.
Note: This method will return an error if the <a href="/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions">cart instruction</a> <code><span class="PreventFireFoxApplyingGapToWBR">attributes.can<wbr/>Update<wbr/>Attributes</span></code> is false, or the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

AttributeChange

AttributeUpdateChange | AttributeRemoveChange

AttributeUpdateChange

Updates an attribute on the order. If an attribute with the provided key does not already exist, it gets created.

key
Key of the attribute to add or update
```
string
```
type
The type of the `AttributeUpdateChange` API.
```
'updateAttribute'
```
value
Value for the attribute to add or update
```
string
```

AttributeRemoveChange

Removes an attribute on the order if an attribute with the provided key already exists.

key
Key of the attribute to remove
```
string
```
type
The type of the `AttributeRemoveChange` API.
```
'removeAttribute'
```

AttributeChangeResult

AttributeChangeResultSuccess | AttributeChangeResultError

AttributeChangeResultSuccess

The returned result of a successful update to an attribute.

type
The type of the `AttributeChangeResultSuccess` API.
```
'success'
```

AttributeChangeResultError

The returned result of an unsuccessful update to an attribute with a message detailing the type of error that occurred.

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 `AttributeChangeResultError` API.
```
'error'
```

Anchor to useApplyAttributeChange
useApplyAttributeChange()

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

Anchor to useApplyAttributeChange-returnsReturns

(change: ) => Promise<>

Anchor to useAttributes
useAttributes()

Returns the proposed attributes applied to the checkout.

Anchor to useAttributes-returnsReturns

[] | undefined

Anchor to useAttributeValues
useAttributeValues(
keys
)

Returns the values for the specified attributes applied to the checkout.

Anchor to useAttributeValues-parametersParameters

Anchor to keys keys string[] required: An array of attribute keys.

Anchor to useAttributeValues-returnsReturns

(string | undefined)[]

Examples

import {

Text,

reactExtension,

useAttributeValues,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.block.render',

() => <Extension />,

);

function Extension() {

const [buyerSelectedFreeTShirt, tshirtSize] =

useAttributeValues([

'buyerSelectedFreeTShirt',

'tshirtSize',

]);

if (Boolean(buyerSelectedFreeTShirt) === true) {

return (

<Text>

You selected a free t-shirt, size:{' '}

{tshirtSize}

</Text>

);

}

return null;

}

Examples

Attribute values

React

import {
  Text,
  reactExtension,
  useAttributeValues,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const [buyerSelectedFreeTShirt, tshirtSize] =
    useAttributeValues([
      'buyerSelectedFreeTShirt',
      'tshirtSize',
    ]);

  if (Boolean(buyerSelectedFreeTShirt) === true) {
    return (
      <Text>
        You selected a free t-shirt, size:{' '}
        {tshirtSize}
      </Text>
    );
  }

  return null;
}

JavaScript

import {
  extension,
  Text,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, {attributes}) => {
    attributes.subscribe(() => {
      renderUI();
    });

    function renderUI() {
      const buyerSelectedFreeTShirt =
        attributes.current?.find(
          (attr) =>
            attr.key ===
            'buyerSelectedFreeTShirt',
        )?.value;

      const tshirtSize = attributes.current?.find(
        (attr) => attr.key === 'tshirtSize',
      )?.value;

      if (
        Boolean(buyerSelectedFreeTShirt) === true
      ) {
        root.replaceChildren(
          root.createComponent(
            Text,
            undefined,
            `You selected a free t-shirt, size: ${tshirtSize}`,
          ),
        );
      } else {
        root.replaceChildren();
      }
    }

    renderUI();
  },
);

Applying changes to attributes

Description

You can add or remove cart and checkout attributes by using the `applyAttributeChange` API.

React

import {
  reactExtension,
  BlockStack,
  Button,
  Text,
  useAttributeValues,
  useApplyAttributeChange,
  useInstructions,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const [giftWrapValue] = useAttributeValues([
    'giftWrap',
  ]);
  const giftWrap = Boolean(giftWrapValue);
  const applyAttributeChange =
    useApplyAttributeChange();
  const instructions = useInstructions();

  async function toggleGiftWrap() {
    const result = giftWrap
      ? await applyAttributeChange({
          type: 'removeAttribute',
          key: 'giftWrap',
        })
      : await applyAttributeChange({
          type: 'updateAttribute',
          key: 'giftWrap',
          value: 'true',
        });
    if (result.type === 'error') {
      console.error(result.message);
    }
  }

  return (
    <BlockStack spacing="tight">
      <Text>
        Gift wrapping:{' '}
        {giftWrap ? 'Added' : 'Not set'}
      </Text>
      <Button
        onPress={toggleGiftWrap}
        disabled={
          !instructions.attributes
            .canUpdateAttributes
        }
      >
        {giftWrap
          ? 'Remove gift wrap'
          : 'Add gift wrap'}
      </Button>
    </BlockStack>
  );
}

JavaScript

import {
  extension,
  BlockStack,
  Button,
  Text,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (
    root,
    {
      attributes,
      instructions,
      applyAttributeChange,
    },
  ) => {
    let giftWrap = false;
    const text = root.createComponent(Text);
    const button = root.createComponent(Button, {
      onPress: async () => {
        const result = giftWrap
          ? await applyAttributeChange({
              type: 'removeAttribute',
              key: 'giftWrap',
            })
          : await applyAttributeChange({
              type: 'updateAttribute',
              key: 'giftWrap',
              value: 'true',
            });
        if (result.type === 'error') {
          console.error(result.message);
        }
      },
    });
    const blockStack = root.createComponent(
      BlockStack,
      {
        spacing: 'tight',
      },
      [text, button],
    );

    attributes.subscribe(updateUI);
    instructions.subscribe(updateUI);

    function updateUI() {
      giftWrap = Boolean(
        attributes.current?.find(
          (attr) => attr.key === 'giftWrap',
        )?.value,
      );

      text.replaceChildren(
        `Gift wrapping: ${giftWrap ? 'Added' : 'Not set'}`,
      );
      button.updateProps({
        disabled:
          !instructions.current?.attributes
            ?.canUpdateAttributes,
      });
      button.replaceChildren(
        giftWrap
          ? 'Remove gift wrap'
          : 'Add gift wrap',
      );
    }
    updateUI();

    root.append(blockstack);
  },
);

Anchor to RelatedRelated

ReferenceTargets

ReferenceComponents

ReferenceConfiguration

LearnTutorials

Was this page helpful?