---
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: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/attributes-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/attributes-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# 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/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)

### Properties

The Attributes API object provides custom attributes from the order. Access the following properties on the API object to read attribute data.

* **attributes**

  **StatefulRemoteSubscribable\<Attribute\[] | undefined>**

  **required**

  Custom key-value pairs that the buyer attached to the order during cart or checkout, commonly used for special instructions or order customization.

### Attribute

* key

  The attribute name. Keys are unique within the attribute list.

  ```ts
  string
  ```

* value

  The attribute value as a string.

  ```ts
  string
  ```

Examples

### Examples

* ####

  ##### Description

  Read all custom attributes from the order and display each key-value pair. This example uses the \`useAttributes\` hook and iterates over the attribute array.

  ##### React

  ```tsx
  import {
    reactExtension,
    useAttributes,
  } from '@shopify/ui-extensions-react/customer-account';
  import {
    BlockStack,
    Text,
  } from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const attributes = useAttributes();

    if (!attributes || attributes.length === 0) {
      return null;
    }

    return (
      <BlockStack>
        <Text emphasis="bold">Order details</Text>
        {attributes.map((attr) => (
          <Text key={attr.key}>
            {attr.key}: {attr.value}
          </Text>
        ))}
      </BlockStack>
    );
  }
  ```

  ##### TS

  ```ts
  import {
    extension,
    BlockStack,
    Text,
  } from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const attributes = api.attributes.current;

      if (!attributes || attributes.length === 0) return;

      const stack = root.createComponent(BlockStack, {});
      stack.appendChild(
        root.createComponent(Text, {emphasis: 'bold'}, 'Order details'),
      );
      for (const attr of attributes) {
        stack.appendChild(
          root.createComponent(Text, {}, `${attr.key}: ${attr.value}`),
        );
      }
      root.appendChild(stack);
    },
  );
  ```

* ####

  ##### Description

  Look up a specific attribute by key and display its value in a banner. This example uses \`useAttributeValues\` to retrieve a single attribute without filtering the full list.

  ##### React

  ```tsx
  import {
    reactExtension,
    useAttributeValues,
  } from '@shopify/ui-extensions-react/customer-account';
  import {
    Banner,
    Text,
  } from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const [giftMessage] = useAttributeValues(['Gift Message']);

    if (!giftMessage) {
      return null;
    }

    return (
      <Banner status="info" title="Gift message">
        <Text>{giftMessage}</Text>
      </Banner>
    );
  }
  ```

  ##### TS

  ```ts
  import {
    extension,
    Banner,
    Text,
  } from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const attributes = api.attributes.current;
      const giftMessage = attributes?.find(
        (attr) => attr.key === 'Gift Message',
      );

      if (!giftMessage) return;

      const banner = root.createComponent(
        Banner,
        {status: 'info', title: 'Gift message'},
      );
      banner.appendChild(
        root.createComponent(Text, {}, giftMessage.value),
      );
      root.appendChild(banner);
    },
  );
  ```

* ####

  ##### Description

  Read the delivery instructions attribute and display it as a banner. This example uses \`useAttributeValues\` to look up a known key and conditionally renders the result.

  ##### React

  ```tsx
  import {
    reactExtension,
    useAttributeValues,
  } from '@shopify/ui-extensions-react/customer-account';
  import {
    Banner,
  } from '@shopify/ui-extensions/customer-account';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const [instructions] = useAttributeValues([
      'Delivery Instructions',
    ]);

    if (!instructions) {
      return null;
    }

    return (
      <Banner status="info" title="Delivery instructions">
        {instructions}
      </Banner>
    );
  }
  ```

  ##### TS

  ```ts
  import {
    extension,
    Banner,
  } from '@shopify/ui-extensions/customer-account';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      const attributes = api.attributes.current;
      const instructions = attributes?.find(
        (attr) => attr.key === 'Delivery Instructions',
      );

      if (!instructions) return;

      root.appendChild(
        root.createComponent(
          Banner,
          {status: 'info', title: 'Delivery instructions'},
          instructions.value,
        ),
      );
    },
  );
  ```

***

## Best practices

* **Use `useAttributeValues` for known keys**: When you need a specific attribute, use `useAttributeValues` instead of filtering the full list.
* **Handle missing attributes gracefully**: Attributes are optional. The list may be empty or `undefined` if the buyer didn't add any custom data.

***

## Limitations

* Attribute values are always strings. If you stored structured data during checkout, you need to parse it in your extension.
* 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.

***