---
title: Note
description: The API for interacting with the note applied to checkout.
api_version: 2025-10
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/note
  md: https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/note.md
---

# NoteAPI

The API for interacting with the note applied to checkout.

## StandardApi

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

* note

  SubscribableSignalLike\<string | undefined>

  required

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

### SubscribableSignalLike

Represents a read-only value managed on the main thread that an extension can subscribe to. Example: Checkout uses this to manage the state of an object and communicate state changes to extensions running in a sandboxed web worker. This interface is compatible with \[Preact's ReadonlySignal]\(https\://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709). Some fields are deprecated but still supported for backwards compatibility. In version 2025-10, \[\`StatefulRemoteSubscribable\`]\(https\://github.com/Shopify/remote-dom/blob/03929aa8418a89d41d294005f219837582718df8/packages/async-subscription/src/types.ts#L17) was replaced with \`ReadonlySignalLike\`. Checkout will remove the old fields some time in the future.

* current

  ```ts
  T
  ```

* destroy

  ```ts
  () => Promise<void>
  ```

* subscribe

  ```ts
  (fn: (value: T) => void) => () => void
  ```

* value

  ```ts
  T
  ```

```ts
export interface SubscribableSignalLike<T> extends ReadonlySignalLike<T> {
  /**
   * @deprecated Use `.value` instead.
   */
  readonly current: T;
  /**
   * @deprecated No longer needed. Use Preact Signal management instead.
   */
  destroy(): Promise<void>;
}
```

## 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 [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/apis/cart-instructions#standardapi-propertydetail-instructions) `notes.canUpdateNote` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.

### NoteChange

```ts
NoteRemoveChange | NoteUpdateChange
```

### NoteRemoveChange

Removes a note

* type

  The type of the \`NoteRemoveChange\` API.

  ```ts
  'removeNote'
  ```

```ts
export interface NoteRemoveChange {
  /**
   * The type of the `NoteRemoveChange` API.
   */
  type: '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'
  ```

```ts
export interface NoteUpdateChange {
  /**
   * The type of the `NoteUpdateChange` API.
   */
  type: 'updateNote';
  /**
   * The new value of the note.
   */
  note: string;
}
```

### NoteChangeResult

```ts
NoteChangeResultSuccess | NoteChangeResultError
```

### NoteChangeResultSuccess

* type

  The type of the \`NoteChangeResultSuccess\` API.

  ```ts
  'success'
  ```

```ts
export interface NoteChangeResultSuccess {
  /**
   * The type of the `NoteChangeResultSuccess` API.
   */
  type: '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'
  ```

```ts
export interface NoteChangeResultError {
  /**
   * The type of the `NoteChangeResultError` API.
   */
  type: 'error';

  /**
   * 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.
   */
  message: string;
}
```

## use​Apply​Note​Change()

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

### Returns

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

### NoteChange

```ts
NoteRemoveChange | NoteUpdateChange
```

### NoteRemoveChange

Removes a note

* type

  The type of the \`NoteRemoveChange\` API.

  ```ts
  'removeNote'
  ```

```ts
export interface NoteRemoveChange {
  /**
   * The type of the `NoteRemoveChange` API.
   */
  type: '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'
  ```

```ts
export interface NoteUpdateChange {
  /**
   * The type of the `NoteUpdateChange` API.
   */
  type: 'updateNote';
  /**
   * The new value of the note.
   */
  note: string;
}
```

### NoteChangeResult

```ts
NoteChangeResultSuccess | NoteChangeResultError
```

### NoteChangeResultSuccess

* type

  The type of the \`NoteChangeResultSuccess\` API.

  ```ts
  'success'
  ```

```ts
export interface NoteChangeResultSuccess {
  /**
   * The type of the `NoteChangeResultSuccess` API.
   */
  type: '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'
  ```

```ts
export interface NoteChangeResultError {
  /**
   * The type of the `NoteChangeResultError` API.
   */
  type: 'error';

  /**
   * 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.
   */
  message: string;
}
```

## Related

[![](https://shopify.dev/images/icons/32/blocks.png)![](https://shopify.dev/images/icons/32/blocks-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/targets)

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

[![](https://shopify.dev/images/icons/32/apps.png)![](https://shopify.dev/images/icons/32/apps-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/components)

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

[![](https://shopify.dev/images/icons/32/gear.png)![](https://shopify.dev/images/icons/32/gear-dark.png)](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)

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

[![](https://shopify.dev/images/icons/32/tutorial.png)![](https://shopify.dev/images/icons/32/tutorial-dark.png)](https://shopify.dev/apps/checkout)

[LearnTutorials](https://shopify.dev/apps/checkout)