Choose a version:

Attributes API

The Attributes API provides read-only access to the custom key-value pairs attached to the order. Use this API to read custom attributes attached to the order, such as delivery instructions or gift messages.

This API reads attributes that were set when the order was placed. To store your own custom data on orders, use metafields instead.

Anchor to Use casesUse cases

Display delivery instructions: Read and display special instructions the buyer provided, such as "Leave at the back door."
Show gift messages: Display a gift message the buyer attached to their order.
Process custom data: Access key-value pairs added by other extensions during checkout, such as a preferred delivery date.

Support

Targets (10)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides the custom key-value pairs attached to the order. Access the following properties on shopify to read attributes such as delivery instructions, gift messages, or other information the buyer provided during checkout.

Anchor to attributes attributes <[] | undefined> required: The custom key-value pairs attached to the order by the customer or by other extensions during cart or checkout. These are commonly used for delivery instructions, gift messages, or other information the buyer provides. The value is undefined if no attributes were set.

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
```

Examples

jsx

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

import {render} from 'preact';

export default async () => {

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

};

function Extension() {

const attributes = shopify.attributes.value;

const instructions = attributes?.find(

(attr) => attr.key === 'deliveryInstructions',

);

if (!instructions) {

return null;

}

return (

<s-banner tone="info">

<s-text type="strong">

Delivery instructions

</s-text>

<s-text>{instructions.value}</s-text>

</s-banner>

);

}

Examples

Description

Find and display delivery instructions from the order attributes. This example reads `shopify.attributes` and uses `Array.find()` to locate a specific attribute by key, then renders the value in a banner.

jsx

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

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

function Extension() {
  const attributes = shopify.attributes.value;
  const instructions = attributes?.find(
    (attr) => attr.key === 'deliveryInstructions',
  );

  if (!instructions) {
    return null;
  }

  return (
    <s-banner tone="info">
      <s-text type="strong">
        Delivery instructions
      </s-text>
      <s-text>{instructions.value}</s-text>
    </s-banner>
  );
}

Description

Display a gift message the buyer attached to their order. This example searches the attributes array for a `giftMessage` key and conditionally renders the message when present.

jsx

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

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

function Extension() {
  const attributes = shopify.attributes.value;
  const giftMessage = attributes?.find(
    (attr) => attr.key === 'giftMessage',
  );

  if (!giftMessage) {
    return null;
  }

  return (
    <s-box>
      <s-text type="strong">Gift message</s-text>
      <s-divider />
      <s-text type="emphasis">
        "{giftMessage.value}"
      </s-text>
    </s-box>
  );
}

Description

Read and format a preferred delivery date from the order attributes. This example finds the `preferredDeliveryDate` attribute and formats it using `Date.toLocaleDateString()` for display.

jsx

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

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

function Extension() {
  const attributes = shopify.attributes.value;
  const deliveryDate = attributes?.find(
    (attr) => attr.key === 'preferredDeliveryDate',
  );

  if (!deliveryDate) {
    return null;
  }

  const formatted = new Date(
    deliveryDate.value,
  ).toLocaleDateString(undefined, {
    weekday: 'long',
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  });

  return (
    <s-banner tone="info">
      <s-text>
        Preferred delivery date: {formatted}
      </s-text>
    </s-banner>
  );
}

Anchor to Best practicesBest practices

Look up attributes by key: Attributes are returned as an array of key-value pairs. Use Array.find() to look up a specific attribute by its key property.

Anchor to LimitationsLimitations

There's no metadata about who set an attribute. You can't determine whether an attribute was set by the buyer, a theme, or another extension.

Was this page helpful?