add_multiple_to_cart
ChatGPTAdd several products to a single Shoppable cart in one call. This is the preferred way to handle a "add A, B, and C to my cart" request — it keeps all items in one cart with one checkout URL, instead of creating separate carts per item. Returns a session ID, a checkout URL, and per-item status (added or skipped with reason).
add_to_cart
ChatGPTAdd a single product (by UPC) to a Shoppable cart. Returns sessionId, itemCount, and an updated checkoutUrl. IMPORTANT for multi-item carts: each call without a sessionId creates a NEW separate cart, so the shopper would have to check out multiple times. If you are adding more than one item in the same conversation: (1) preferred — use add_multiple_to_cart with all UPCs in one call, or (2) pass the sessionId returned by your first add_to_cart call into every subsequent add_to_cart call. Always share the latest checkoutUrl with the shopper, not earlier ones.
find_similar
ChatGPTGiven a product ID, return similar products (same category, comparable price). Useful for offering alternatives or letting the shopper compare options.
get_cart_contents
ChatGPTInspect the contents of an existing cart by session ID. Returns the items currently in the cart with names, merchants, prices, and quantities.
get_checkout_url
ChatGPTGet the checkout URL for an existing cart session.
get_deals
ChatGPTFind products currently on sale, optionally filtered by category, brand, merchant, minimum discount percentage, or max price. Returns a JSON list of discounted products with original and sale prices.
get_merchant
ChatGPTLook up a Shoppable merchant by name or ID. Returns merchant info including catalog size and network.
get_order
ChatGPTLook up an order by order number. BEFORE calling this tool, ask the shopper for at least one of: the email address used on the order, the phone number on the order, the billing postal/zip code, or the last name on the order. Pass whatever they confirm as email, phone, postalCode, or lastName. The order is only returned if at least one of those matches what is on file; otherwise the response is identical to "order not found" so the existence of the order is not leaked. Never share the order number publicly — treat it as something only the shopper should know. (Legacy: orderId is accepted as an alias for orderNumber for older clients.)
get_trending
ChatGPTReturn popular or trending products over a time window (day, week, or month), optionally scoped to a category, brand, or merchant.
list_brands
ChatGPTList available brands, optionally scoped to a merchant or category, or filtered by a name prefix.
list_categories
ChatGPTList available product categories, optionally scoped to a single merchant or to subcategories under a given parent.
remove_from_cart
ChatGPTRemove a single product (by UPC) from a Shoppable cart. Pass the sessionId of the cart and the UPC of the item to remove — get the UPCs from get_cart_contents. Returns the updated itemCount and checkoutUrl. Removing a UPC that is not in the cart is a harmless no-op. Use this whenever the shopper asks to remove or delete an item; do NOT re-add the remaining items to "reset" the cart (adds only append, so that would not remove anything). Always share the updated checkoutUrl afterward.
search_products
ChatGPTSearch Shoppable's product catalog by keyword, brand, or category. Returns a JSON payload with id, name, brand, category, price, salePrice, merchant, image, and a pre-built checkoutUrl for each result. Use the product ID with add_to_cart if you need to refresh the checkout URL later. SEARCH TIPS: the catalog is keyword-matched, so query with concise PRODUCT terms — the core product type plus distinguishing attributes (e.g. "oil-free sunscreen", not "a sunscreen that won't break me out"). Pass price limits via minPrice/maxPrice and a retailer via merchantId rather than putting them in the query text. Drop conversational filler; generic/non-product words (e.g. "good", "professional", "that won't") can surface irrelevant items like books or music whose titles happen to contain those words.
