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 API for interacting with the note applied to checkout.

Anchor to standardapiStandardApi

The base API object provided to purchase extension targets.

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

Anchor to useNote
useNote()

Returns the proposed note applied to the checkout.

Anchor to useNote-returnsReturns

string | undefined

Anchor to checkoutapiCheckoutApi

The API object provided to purchase.checkout extension targets.

Anchor to applyNoteChange applyNoteChange (change: ) => Promise<> required: Performs an update on the note attached to the cart and checkout. If successful, this mutation results in an update to the value retrieved through the note property.

Note
This method will return an error if the cart instruction notes.canUpdateNote is false, or the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.
Note: This method will return an error if the <a href="/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-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, Google Pay, or Meta Pay.

NoteChange

NoteRemoveChange | NoteUpdateChange

NoteRemoveChange

Removes a note

type
The type of the `NoteRemoveChange` API.
```
'removeNote'
```

NoteUpdateChange

An Update to a note on the order. for example, the buyer could request detailed packaging instructions in an order note

note
The new value of the note.
```
string
```
type
The type of the `NoteUpdateChange` API.
```
'updateNote'
```

NoteChangeResult

NoteChangeResultSuccess | NoteChangeResultError

NoteChangeResultSuccess

type
The type of the `NoteChangeResultSuccess` API.
```
'success'
```

NoteChangeResultError

message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```
type
The type of the `NoteChangeResultError` API.
```
'error'
```

Anchor to useApplyNoteChange
useApplyNoteChange()

Returns a function to mutate the note property of the checkout.

Anchor to useApplyNoteChange-returnsReturns

(change: ) => Promise<>