Choose a version:

Attributes API

Use the Attributes API to read and write custom key-value pairs attached to the cart that persist through checkout. These key-value pairs are a lightweight way to keep buyer choices, operational details, and feature flags on the cart so that extensions and merchant workflows can all access the same values.

Attributes are shared across all extensions and the storefront. Any extension can read or overwrite attributes set by another.

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 Use casesUse cases

Track buyer preferences: Store buyers' custom selections like gift wrapping or personalization options as key-value pairs on the cart.
Conditionally display UI: Show or hide features based on the cart's current attributes.
Store operational data: Capture purchase order numbers, reference codes, or other operational data that the merchant needs for accounting or shipping.

Support

Targets (33)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides attribute data for the current checkout. Access the following properties on shopify to read custom key-value pairs attached to the cart. Available to purchase extension targets.

Anchor to attributes attributes <[]> required: The custom key-value attributes attached to the cart or checkout. These are set by the buyer or by an extension using applyAttributeChange(). The list is empty if no attributes have been added.

SubscribableSignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends `ReadonlySignalLike` with deprecated fields that are still supported for backwards compatibility.

current
The current value of the signal. Equivalent to `.value`, accessing this property subscribes to changes when used in a reactive context.
```
T
```
destroy
Cleans up the subscription and releases any resources held by this signal. After calling `destroy()`, the signal stops receiving updates from the main thread.
```
() => Promise<void>
```
subscribe
Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.
```
T
```

Attribute

key
The identifier for the attribute. Each key must be unique within the set of attributes on the cart or checkout. If you call `applyAttributeChange()` with a key that already exists, then the existing value is replaced.
```
string
```
value
The value associated with the attribute key. This is a freeform string that can store any information the buyer or app provides. Attribute values are always strings. To store structured data, serialize it to JSON and parse it when reading.
```
string
```

Anchor to MethodsMethods

The shopify global object provides methods to modify attribute data. Access the following methods on shopify to apply attribute changes. Available to purchase.checkout extension targets.

Anchor to applyAttributeChange applyAttributeChange (change: ) => Promise<> required: Updates or removes an attribute on the cart and checkout. On success, the attributes property updates to reflect the change.

Note
This method returns an error if the cart instruction attributes.canUpdateAttributes is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
Note: This method returns an error if the <a href="/docs/api/checkout-ui-extensions/2025-10/apis/cart-instructions#properties-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 or Google Pay.

AttributeChange

The input for `applyAttributeChange()`. Pass either an `AttributeUpdateChange` (with `type: 'updateAttribute'`) to set the attribute or an `AttributeRemoveChange` (with `type: 'removeAttribute'`) to delete it.

AttributeUpdateChange | AttributeRemoveChange

AttributeUpdateChange

Updates an attribute on the cart and checkout. If an attribute with the provided key doesn't already exist, then it gets created.

key
The key of the attribute to add or update. If an attribute with this key already exists, then its value is replaced.
```
string
```
type
Identifies this as an attribute update or creation. Set this when creating a change to add or replace an attribute value.
```
'updateAttribute'
```
value
The new value for the attribute.
```
string
```

AttributeRemoveChange

Removes an attribute from the checkout. Pass this to `applyAttributeChange()` to delete an attribute by key. If the key doesn't exist, then the change has no effect.

key
The key of the attribute to remove.
```
string
```
type
Identifies this as an attribute removal. Set this when creating a change to delete an attribute by key.
```
'removeAttribute'
```

AttributeChangeResult

The result of calling `applyAttributeChange()`. Use the `type` property to determine whether the change succeeded or failed.

AttributeChangeResultSuccess | AttributeChangeResultError

AttributeChangeResultSuccess

The result of a successful attribute change. The `type` property is `'success'`.

type
Indicates that the attribute change was applied successfully.
```
'success'
```

AttributeChangeResultError

The result of a failed attribute change. Check the `message` property for details about what went wrong.

message
A message that explains the error. This message is useful for debugging. It isn't localized and shouldn't be displayed to the buyer.
```
string
```
type
Indicates that the attribute change couldn't be applied. Check the `message` property for details.
```
'error'
```

Anchor to Available Preact hooksAvailable Preact hooks

The following Preact hooks provide a convenience wrapper that makes it easier to perform common tasks without writing your own logic.

Anchor to useAttributeValues
useAttributeValues(
keys
)

The useAttributeValues hook returns an array of attribute values for the specified keys. Use this hook when you need to read the values of only some of the cart's attributes and you know the values' keys.

Anchor to useAttributeValues-parametersParameters

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

Anchor to useAttributeValues-returnsReturns

(string | undefined)[]

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default function extension() {

render(<Extension />, document.body);

}

function Extension() {

const attributes = shopify.attributes.value;

if (attributes.length === 0) {

return (

<s-text>

No custom cart attributes.

</s-text>

);

}

return (

<s-stack>

<s-text>Cart attributes</s-text>

{attributes.map((attribute) => (

<s-text key={attribute.key}>

{attribute.key}: {attribute.value}

</s-text>

))}

</s-stack>

);

}

Examples

Description

Read the full cart attribute list by mapping over `shopify.attributes.value`, which resolves to an array of key-value pairs. Use this pattern when you need every attribute on the cart, such as for a summary, or when keys aren't known ahead of time.

jsx

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

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

function Extension() {
  const attributes = shopify.attributes.value;

  if (attributes.length === 0) {
    return (
      <s-text>
        No custom cart attributes.
      </s-text>
    );
  }

  return (
    <s-stack>
      <s-text>Cart attributes</s-text>
      {attributes.map((attribute) => (
        <s-text key={attribute.key}>
          {attribute.key}: {attribute.value}
        </s-text>
      ))}
    </s-stack>
  );
}

Description

Show content based on specific cart attribute values. This example uses `useAttributeValues` to retrieve two attributes and conditionally displays the buyer's t-shirt selection.

jsx

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

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

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

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

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

  return null;
}

Description

Add or remove a cart attribute based on buyer interaction. This example reads the current `giftWrap` attribute and uses `shopify.applyAttributeChange` to toggle it, checking `instructions.attributes.canUpdateAttributes` before rendering the button.

jsx

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

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

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

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

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

  return (
    <s-stack>
      <s-text>
        Gift wrapping:{' '}
        {giftWrap ? 'Added' : 'Not set'}
      </s-text>
      <s-button
        onClick={toggleGiftWrap}
        disabled={
          !shopify.instructions.value.attributes
            .canUpdateAttributes
        }
      >
        {giftWrap
          ? 'Remove gift wrap'
          : 'Add gift wrap'}
      </s-button>
    </s-stack>
  );
}

Anchor to Best practicesBest practices

Check canUpdateAttributes before rendering mutation UI: Use the instructions property on the global shopify object to verify instructions.attributes.canUpdateAttributes before showing attribute controls. If it's false, hide the feature entirely.
Use descriptive, namespaced keys: Choose clear, unique attribute keys to avoid collisions with other extensions. For example, use myApp_giftWrap rather than gift.

Anchor to LimitationsLimitations

Attribute changes aren't available when the buyer uses an accelerated checkout method such as Apple Pay or Google Pay.

Was this page helpful?

Anchor to Use casesUse cases

Supported targets

Supported targets

Anchor to PropertiesProperties

SubscribableSignalLike

Attribute

Anchor to MethodsMethods

AttributeChange

AttributeUpdateChange

AttributeRemoveChange

AttributeChangeResult

AttributeChangeResultSuccess

AttributeChangeResultError

Anchor to Available Preact hooksAvailable Preact hooks

Anchor to useAttributeValuesuseAttributeValues(keyskeys)

Anchor to useAttributeValues-parametersParameters

Anchor to useAttributeValues-returnsReturns

Anchor to Best practicesBest practices

Anchor to LimitationsLimitations

Anchor to useAttributeValues
useAttributeValues(
keys
)