--- title: Note API description: The API for interacting with the note applied to checkout. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/note-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/note-api.md --- # Note API The API for interacting with the note applied to checkout. ### Support Targets (31) ### Supported targets * purchase.​checkout.​actions.​render-before * purchase.​checkout.​block.​render * purchase.​checkout.​cart-line-item.​render-after * purchase.​checkout.​cart-line-list.​render-after * purchase.​checkout.​chat.​render * purchase.​checkout.​contact.​render-after * purchase.​checkout.​delivery-address.​render-after * purchase.​checkout.​delivery-address.​render-before * purchase.​checkout.​footer.​render-after * purchase.​checkout.​header.​render-after * purchase.​checkout.​payment-method-list.​render-after * purchase.​checkout.​payment-method-list.​render-before * purchase.​checkout.​pickup-location-list.​render-after * purchase.​checkout.​pickup-location-list.​render-before * purchase.​checkout.​pickup-location-option-item.​render-after * purchase.​checkout.​pickup-point-list.​render-after * purchase.​checkout.​pickup-point-list.​render-before * purchase.​checkout.​reductions.​render-after * purchase.​checkout.​reductions.​render-before * purchase.​checkout.​shipping-option-item.​details.​render * purchase.​checkout.​shipping-option-item.​render-after * purchase.​checkout.​shipping-option-list.​render-after * purchase.​checkout.​shipping-option-list.​render-before * purchase.​thank-you.​announcement.​render * purchase.​thank-you.​block.​render * purchase.​thank-you.​cart-line-item.​render-after * purchase.​thank-you.​cart-line-list.​render-after * purchase.​thank-you.​chat.​render * purchase.​thank-you.​customer-information.​render-after * purchase.​thank-you.​footer.​render-after * purchase.​thank-you.​header.​render-after ## StandardApi The base API object provided to `purchase` extension targets. * **note** **SubscribableSignalLike\** **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. ```ts 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. ```ts () => Promise ``` * 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. ```ts (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. ```ts T ``` ## 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\** **required** Sets or removes the buyer's note on the checkout. On success, the [`note`](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/apis/note#standardapi-propertydetail-note) property updates to reflect the change. **Note:** This method returns an error if the \cart instruction\ \\notes.can\Update\Note\\ 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. ```ts 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. ```ts '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. ```ts string ``` * type Identifies this as a note update. Set this when creating a change to set or replace the buyer's note. ```ts 'updateNote' ``` ### NoteChangeResult The result of calling \`applyNoteChange()\`. Use the \`type\` property to determine whether the change succeeded or failed. ```ts NoteChangeResultSuccess | NoteChangeResultError ``` ### NoteChangeResultSuccess The result of a successful note change. The \`type\` property is \`'success'\`. * type Indicates that the note change was applied successfully. ```ts '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. ```ts string ``` * type Indicates that the note change couldn't be applied. Check the \`message\` property for details. ```ts 'error' ``` ## use​Apply​Note​Change() Returns a function to mutate the `note` property of the checkout. ### Returns * **(change: NoteChange) => Promise\** ## 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)