---

name: add-to-cart description: Adding a product to the shopper's cart. Trigger when they say they want to buy something, add it to cart, or take one — including "I'll take that one" about a product already on screen. Read the full body first — it defines how to identify which product they mean before presenting the cart button. tags: [internal, concierge, requires-yepai-tools] license: MIT-0

Adding to cart

Ported from the add-to-cart-journey. The whole skill is really one question: do I know which product they mean, and do I have its id?

Work out which product

Check, in this order:

1. The page the shopper is on (a product page tells you the product)
2. Products already shown in this conversation
3. What they just typed

Once you know which product it is — run SEARCH_CATALOG(query=<product name or handle>, context='fetching product for add to cart', limit=5) in this same turn, then present the cart button using the id from the matching result. Always search, even when you already have an id from the page or from earlier in the conversation: that search is what makes the card buildable (see below), and it is also what confirms the product is still there. If none of the results is that product — it was removed, or it is not indexed — take the "cannot be found" path below rather than sending the id you were holding.

If you cannot tell which product they mean — ask, once:

NOTIFY_MESSAGE(message_type='text') — "Which product would you like to add to cart?"

Then identify from their answer, validating with SEARCH_CATALOG if needed.

Presenting the cart button

NOTIFY_MESSAGE(message_type='addToCart') with the id alone — one product per card:

{"productsId": ["gid://shopify/Product/123"]}

That is the whole payload. The image, price, variant and link are built downstream from the catalogue entry SEARCH_CATALOG returned for that product, so there is nothing to copy through and nothing to retype.

Never paste the SEARCH_CATALOG result into message_content, and never send it as a quoted string — send the object above. A payload no id can be read out of is dropped before it reaches the shopper, leaving them a sentence with no button under it.

That entry does not live long — a search from several turns back may already be gone, and the call tells you nothing when the lookup misses: it reports queued either way. There is no failure for you to react to and no way for you to tell how much time has passed. Hence the rule above: search in the same turn you present the button, and the entry is guaranteed to be there.

The widget renders the product with an add-to-cart button; the shopper taps it. You are not adding anything to the cart yourself — you are handing them the button.

When the product cannot be found

Two calls in sequence:

1. NOTIFY_MESSAGE(message_type='text') — "I couldn't find that product. Could you tell me the product name or share the product page URL?"
2. NOTIFY_MESSAGE(message_type='suggestionQuestion') — "Try again" plus one alternative such as browsing similar products

No apology. Ask for the one thing that unblocks you.