--- title: Note API description: >- Capture and update the order note the buyer attaches to the checkout, such as delivery instructions or gift messages. api_version: 2026-07-rc source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/target-apis/checkout-apis/note-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/target-apis/checkout-apis/note-api.md api_name: checkout-ui-extensions --- # 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. ### Use 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 * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#checkout-cart-line-list-) * purchase.​checkout.​chat.​render * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/order-summary#thank-you-cart-line-list-) * purchase.​thank-you.​chat.​render * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc/targets/thank-you/header#header-target) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc#target-apis-define-what-your-extension-does) provides note data for the current checkout. Access the following properties on `shopify` to read the order note. Available 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 ``` ### Methods The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/2026-07-rc#target-apis-define-what-your-extension-does) 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. * **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-07-rc/apis/note#properties-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. Render your own localized error text rather than displaying this message to the buyer. ```ts string ``` * type Indicates that the note change couldn't be applied. Check the \`message\` property for details. ```ts 'error' ``` Examples ### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { const note = shopify.note.value; if (!note) { return null; } return ( {note} ); } ``` * #### ##### 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 ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useState} from 'preact/hooks'; export default function extension() { render(, 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 ( {currentNote ? ( {currentNote} ) : null} Add delivery note {currentNote ? ( Remove note ) : null} {saved ? ( Note saved! ) : null} ); } ``` *** ## Best 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. *** ## Limitations * Note changes aren't available when the buyer uses an accelerated checkout method such as Apple Pay or Google Pay. ***