--- title: Attributes API description: >- 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. api_version: 2026-04 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/attributes-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/attributes-api.md --- # 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](https://shopify.dev/docs/apps/build/customer-accounts/metafields-in-customer-accounts) instead. ### Use 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 * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-item-render-after-) * [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-list-render-after-) * [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#payments-and-returns-targets) * [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#return-details-render-after-) * [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#target-apis-define-what-your-extension-does) 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. * **attributes** **SubscribableSignalLike\** **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. ```ts 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. ```ts () => Promise ``` * 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. ```ts (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. ```ts 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. ```ts 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. ```ts string ``` Examples ### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const attributes = shopify.attributes.value; const instructions = attributes?.find( (attr) => attr.key === 'deliveryInstructions', ); if (!instructions) { return null; } return ( Delivery instructions {instructions.value} ); } ``` * #### ##### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const attributes = shopify.attributes.value; const giftMessage = attributes?.find( (attr) => attr.key === 'giftMessage', ); if (!giftMessage) { return null; } return ( Gift message "{giftMessage.value}" ); } ``` * #### ##### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, 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 ( Preferred delivery date: {formatted} ); } ``` *** ## Best 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. *** ## Limitations * 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. ***