Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

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.

Anchor to Use casesUse 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

Anchor to PropertiesProperties

The Note API object provides the customer's note from the order. Access the following properties on the API object to read note data.

Anchor to note 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

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 (

{note}

</Banner>

);

}

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

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

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

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

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

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

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);
  },
);

Anchor to LimitationsLimitations

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

Was this page helpful?