Use cartAttributesUpdate to attach an array of AttributeInput objects (key-value string pairs) to the cart; these flow through to the resulting order's attributes.
Use cartNoteUpdate to set a free-text note on the cart that will appear on the resulting order as the order note.
Keep attribute keys namespaced (e.g., prefixed with your app name) to avoid collisions with other integrations writing to the same cart.
Read cart.attributes and cart.note back in the mutation response to confirm the values were stored.
Query these fields later by fetching the cart by ID using the cart query to verify persistence across sessions.
Consult current Shopify docs for any length limits on note text and the maximum number of attribute key-value pairs allowed per cart.
Known gotchas
cartAttributesUpdate replaces the entire attributes array, not merges; always read existing attributes and merge client-side before writing to avoid losing values set by other parts of your app.
Cart attributes are visible to customers via the Storefront API; do not store sensitive or internal data in cart attributes.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp