---
title: Note API
description: The API for interacting with the note applied to checkout.
api_version: 2025-07
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/target-apis/checkout-apis/note-api
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/target-apis/checkout-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/checkout-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/api/checkout-ui-extensions/2026-04/upgrading-to-2026-04) to upgrade your extension.

# Note API

The API for interacting with the note applied to checkout.

## StandardApi

The base API object provided to `purchase` extension targets.

* **note**

  **StatefulRemoteSubscribable\<string | undefined>**

  **required**

  A note left by the customer to the merchant, either in their cart or during checkout.

## use​Note()

Returns the proposed `note` applied to the checkout.

### Returns

* **string | undefined**

## CheckoutApi

The API object provided to `purchase.checkout` extension targets.

* **applyNoteChange**

  **(change: NoteChange) => Promise\<NoteChangeResult>**

  **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`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/note#standardapi-propertydetail-note) property.

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

```ts
NoteRemoveChange | NoteUpdateChange
```

### NoteRemoveChange

Removes a note

* type

  The type of the \`NoteRemoveChange\` API.

  ```ts
  '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.

  ```ts
  string
  ```

* type

  The type of the \`NoteUpdateChange\` API.

  ```ts
  'updateNote'
  ```

### NoteChangeResult

```ts
NoteChangeResultSuccess | NoteChangeResultError
```

### NoteChangeResultSuccess

* type

  The type of the \`NoteChangeResultSuccess\` API.

  ```ts
  '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.

  ```ts
  string
  ```

* type

  The type of the \`NoteChangeResultError\` API.

  ```ts
  'error'
  ```

## use​Apply​Note​Change()

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

### Returns

* **(change: NoteChange) => Promise\<NoteChangeResult>**

## Related

[Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

[Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components)

[Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

[Learn - Tutorials](https://shopify.dev/apps/checkout)