---
title: Note API
description: >-
  The Note API provides read-only access to the optional text note that the
  customer left during checkout. Use this API to display delivery instructions,
  special requests, or other freeform messages the customer included with their
  order.
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/note-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/note-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.

# Note API

The Note API provides read-only access to the optional text note that the customer left during checkout. Use this API to display delivery instructions, special requests, or other freeform messages the customer included with their order.

### Use cases

* **Display delivery instructions**: Show the customer's note containing special delivery instructions, such as "Ring the doorbell twice."
* **Show special requests**: Display any special requests the customer included with their order.
* **Conditional rendering**: Check whether a note exists and conditionally render a section in your extension.

### 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 Note API object provides the customer's note from the order. Access the following properties on the API object to read note data.

* **note**

  **StatefulRemoteSubscribable\<string | undefined>**

  **required**

  A free-form text note that the buyer left for the merchant during cart or checkout, commonly used for special delivery instructions or order requests.

Examples

### Examples

* ####

  ##### Description

  Read the order note and display it in a text block. This example uses the \`useNote\` hook and handles the case where the note is \`undefined\`.

  ##### React

  ```tsx
  import {
    reactExtension,
    useNote,
  } 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 note = useNote();

    if (!note) {
      return null;
    }

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

  ##### TS

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

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

      if (!note) return;

      root.appendChild(
        root.createComponent(
          Banner,
          {status: 'info', title: 'Order note'},
          note,
        ),
      );
    },
  );
  ```

* ####

  ##### Description

  Check whether a note exists and conditionally display a banner. This example uses \`useNote\` and only renders the banner when the note value is truthy.

  ##### React

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

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

  function Extension() {
    const note = useNote();

    return (
      <Text appearance={note ? 'success' : 'subdued'}>
        {note
          ? 'A note was included with this order.'
          : 'No note was included with this order.'}
      </Text>
    );
  }
  ```

  ##### TS

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

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

      root.appendChild(
        root.createComponent(
          Text,
          {appearance: note ? 'success' : 'subdued'},
          note
            ? 'A note was included with this order.'
            : 'No note was included with this order.',
        ),
      );
    },
  );
  ```

* ####

  ##### Description

  Read the note and display it as special delivery instructions. This example uses \`useNote\` and renders the text with a descriptive heading.

  ##### React

  ```tsx
  import {
    reactExtension,
    useNote,
  } 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 note = useNote();

    if (!note) {
      return null;
    }

    return (
      <BlockStack>
        <Text emphasis="bold">Special instructions</Text>
        <Text>{note}</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 note = api.note.current;

      if (!note) return;

      const stack = root.createComponent(BlockStack, {});
      stack.appendChild(
        root.createComponent(
          Text,
          {emphasis: 'bold'},
          'Special instructions',
        ),
      );
      stack.appendChild(root.createComponent(Text, {}, note));
      root.appendChild(stack);
    },
  );
  ```

***

## Limitations

* Only a single note is supported per order. There's no way to retrieve multiple notes or a note history.

***