Choose a version:

Note API

The Note API provides access to the order note attached to the checkout. Use this API to display, add, update, or remove order notes that buyers use for delivery instructions or special requests.

Anchor to Use casesUse cases

Display the order note: Show the buyer the note they've attached to the checkout.
Add or update an order note: Let buyers write delivery or gift instructions during checkout.
Remove an order note: Clear the note when the buyer no longer needs it.

Support

Targets (31)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides note data for the current checkout. Access the following properties on shopify to read the order note. Available to purchase extension targets.

Anchor to note note <string | undefined> required: A note left by the customer to the merchant, either in their cart or during checkout.

The value is undefined if the buyer hasn't entered a note. Use this to display or react to order-level instructions such as delivery preferences or gift messages.

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

Anchor to MethodsMethods

The shopify global object provides methods to modify note data. Access the following methods on shopify to add, update, or remove the order note. Available to purchase.checkout extension targets.

Anchor to applyNoteChange applyNoteChange (change: ) => Promise<> required: Sets or removes the buyer's note on the checkout. On success, the note property updates to reflect the change.

Note
This method returns an error if the cart instruction notes.canUpdateNote is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
Note: This method returns an error if the <a href="/docs/api/checkout-ui-extensions/latest/apis/cart-instructions#properties-propertydetail-instructions">cart instruction</a> <code><span class="PreventFireFoxApplyingGapToWBR">notes.can<wbr/>Update<wbr/>Note</span></code> is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

NoteChange

The input for `applyNoteChange()`. Pass either a `NoteUpdateChange` (with `type: 'updateNote'`) to set the note or a `NoteRemoveChange` (with `type: 'removeNote'`) to clear it.

NoteRemoveChange | NoteUpdateChange

NoteRemoveChange

Clears the buyer's note from the checkout. Pass this to `applyNoteChange()` to remove any existing note.

type
Identifies this as a note removal. Set this when creating a change to clear the buyer's note.
```
'removeNote'
```

NoteUpdateChange

Sets or replaces the buyer's note on the checkout. Pass this to `applyNoteChange()` to update the note.

note
The text to set as the buyer's note. This replaces any existing note entirely rather than appending to it.
```
string
```
type
Identifies this as a note update. Set this when creating a change to set or replace the buyer's note.
```
'updateNote'
```

NoteChangeResult

The result of calling `applyNoteChange()`. Use the `type` property to determine whether the change succeeded or failed.

NoteChangeResultSuccess | NoteChangeResultError

NoteChangeResultSuccess

The result of a successful note change. The `type` property is `'success'`.

type
Indicates that the note change was applied successfully.
```
'success'
```

NoteChangeResultError

The result of a failed note change. Check the `message` property for details about what went wrong.

message
A message that explains the error. This message is useful for debugging. It isn't localized and shouldn't be displayed to the buyer. Render your own localized error text rather than displaying this message to the buyer.
```
string
```
type
Indicates that the note change couldn't be applied. Check the `message` property for details.
```
'error'
```

Examples

jsx

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

import {render} from 'preact';

export default function extension() {

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

}

function Extension() {

const note = shopify.note.value;

if (!note) {

return null;

}

return (

<s-banner heading="Order note">

{note}

</s-banner>

);

}

Examples

Description

Show the buyer's delivery or gift instructions when a note exists. This example renders the note inside a banner, returning nothing when the note is `undefined`.

jsx

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

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

function Extension() {
  const note = shopify.note.value;

  if (!note) {
    return null;
  }

  return (
    <s-banner heading="Order note">
      {note}
    </s-banner>
  );
}

Description

Add delivery instructions or remove an existing order note. This example calls `shopify.applyNoteChange` after checking [`instructions.notes.canUpdateNote`](/docs/api/checkout-ui-extensions/apis/cart-instructions), and supports both updating and clearing the note.

jsx

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

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

function Extension() {
  const currentNote = shopify.note.value;
  const [saved, setSaved] = useState(false);

  const canUpdate =
    shopify.instructions.value.notes
      .canUpdateNote;

  async function addNote() {
    const result =
      await shopify.applyNoteChange({
        type: 'updateNote',
        note: 'Please leave at front door',
      });

    if (result.type === 'error') {
      console.error(result.message);
    } else {
      setSaved(true);
    }
  }

  async function removeNote() {
    const result =
      await shopify.applyNoteChange({
        type: 'removeNote',
      });

    if (result.type === 'error') {
      console.error(result.message);
    } else {
      setSaved(false);
    }
  }

  if (!canUpdate) {
    return null;
  }

  return (
    <s-stack>
      {currentNote ? (
        <s-banner heading="Order note">
          {currentNote}
        </s-banner>
      ) : null}
      <s-button onClick={addNote}>
        Add delivery note
      </s-button>
      {currentNote ? (
        <s-button
          tone="critical"
          onClick={removeNote}
        >
          Remove note
        </s-button>
      ) : null}
      {saved ? (
        <s-text tone="success">Note saved!</s-text>
      ) : null}
    </s-stack>
  );
}

Anchor to Best practicesBest practices

Use NoteRemoveChange to clear the note: To remove a note, pass { type: 'removeNote' } instead of updating with an empty string. This cleanly sets the note value to undefined.
Check for undefined, not empty string: The note value is undefined when no note exists, not ''. Use note === undefined rather than note === '' when determining whether a note is present.

Anchor to LimitationsLimitations

Note changes aren't available when the buyer uses an accelerated checkout method such as Apple Pay or Google Pay.

Was this page helpful?