shopify:cart:note-update

Fires when a buyer sets or clears the cart note. The note is a single free-text field on the cart, used for gift messages and delivery instructions.

You can use this to keep your own copy of the note in sync, or to check what a buyer typed before checkout. The event fires before the note is saved, and the promise resolves with the updated cart.

You dispatch it from the element holding the note field, in the cart drawer or on the cart page.

An empty string clears the note. Because the event fires when the operation starts, it fires whether or not the change succeeds. If the cart declines the change, the promise resolves with the cart as it stands and userErrors explaining why. If the request fails, the promise rejects and shopify:cart:error is dispatched.

Anchor to propertiesProperties

Anchor to context context 'product' | 'cart' | 'dialog' | 'standard-action' required: Where the update came from. The standard-action value is reserved for events that standard storefront actions emit automatically.
Anchor to note note string required: The new note text.
Anchor to promise promise Promise<> required: Resolves with a CartNoteUpdateResult when the update finishes. It rejects if the request fails or is aborted.
Anchor to detail detail Record<string, unknown>: Optional custom data for the storefront's internal use. Listeners can read it.

CartNoteUpdateResult

The value a `shopify:cart:note-update` promise resolves with.

cart
The cart after the note was saved.
```
StandardEventCart | null
```
userErrors
Validation errors from the mutation, such as a note above the length limit.
```
CartMutationUserError[]
```
warnings
Non-blocking warnings from the mutation.
```
CartMutationWarning[]
```
detail
Optional custom data for the storefront's internal use. Listeners can read it.
```
Record<string, unknown>
```

StandardEventCart

A subset of the [Storefront API Cart object](/docs/api/storefront/latest/objects/Cart) that cart events carry.

id
The cart GID.
```
string
```
totalQuantity
The total number of items in the cart.
```
number
```
cost
The total cost of the cart.
```
StandardEventCartCost
```
lines
The lines in the cart.
```
StandardEventCartLine[]
```
discountCodes
The discount codes on the cart.
```
StandardEventCartDiscountCode[]
```

StandardEventCartCost

The cost of a cart or a cart line.

totalAmount
The total amount.
```
MoneyV2
```

MoneyV2

An amount with its currency, matching the Storefront API [`MoneyV2`](/docs/api/storefront/latest/objects/MoneyV2) format.

amount
A decimal money amount, such as `29.99`.
```
string
```
currencyCode
The three-letter currency code, such as `USD`.
```
string
```

StandardEventCartLine

A single line in the cart.

id
The cart line ID. A storefront on the AJAX cart API passes its own line keys through, so don't assume a GID.
```
string
```
quantity
The quantity of merchandise on the line.
```
number
```
cost
The cost of the line.
```
StandardEventCartCost
```

StandardEventCartDiscountCode

A discount code on the cart.

code
The discount code the buyer entered.
```
string
```
applicable
Whether the discount code applies to the cart.
```
boolean
```

CartMutationUserError

A validation error returned by a cart mutation.

code
A machine-readable error code, such as `INVALID` for a malformed input or `MAXIMUM_EXCEEDED` for a quantity above the item's maximum. See [`CartErrorCode`](/docs/api/storefront/latest/enums/CartErrorCode) for the full list.
```
string
```
field
The path to the field that caused the error.
```
string[]
```
message
A human-readable message.
```
string
```

CartMutationWarning

A non-blocking warning returned by a cart mutation.

code
A machine-readable warning code, such as `MERCHANDISE_OUT_OF_STOCK` for a line whose merchandise ran out or `MERCHANDISE_NOT_ENOUGH_STOCK` when only part of the requested quantity is available. See [`CartWarningCode`](/docs/api/storefront/latest/enums/CartWarningCode) for the full list.
```
string
```
message
A human-readable message.
```
string
```
target
The cart line or field the warning applies to.
```
string
```

Examples

Dispatch the event

import { CartNoteUpdateEvent } from '@shopify/standard-events';

const deferred = CartNoteUpdateEvent.createPromise();

element.dispatchEvent(

new CartNoteUpdateEvent({

context: 'cart',

note: textarea.value,

promise: deferred.promise,

}),

);

const ajaxCart = await saveNote(textarea.value);

deferred.resolve({

cart: CartNoteUpdateEvent.createCartFromAjaxResponse(ajaxCart),

});

Examples

Dispatch the event

import { CartNoteUpdateEvent } from '@shopify/standard-events';

const deferred = CartNoteUpdateEvent.createPromise();

element.dispatchEvent(
  new CartNoteUpdateEvent({
    context: 'cart',
    note: textarea.value,
    promise: deferred.promise,
  }),
);

const ajaxCart = await saveNote(textarea.value);

deferred.resolve({
  cart: CartNoteUpdateEvent.createCartFromAjaxResponse(ajaxCart),
});

Listen for the event

document.addEventListener('shopify:cart:note-update', (event) => {
  console.log('Note changing to', event.note);

  event.promise.then(({ cart }) => syncNote(cart?.id, event.note));
});

Was this page helpful?