Curie Commerce

Add a generated 3D model to the merchant's Shopify store as MODEL_3D media — creating the product if needed — and optionally publish it. This is the store-side 'cut-and-paste' step: pass the hosted `glb_url` of an already-generated model, OR pass just an `image_url` and (when the Curie generation engine is configured) the tool runs the photo→3D step for you. WRITE operation; works only on an installed merchant store (uses the app's offline Admin token). Defaults to a DRAFT product unless `publish: true`. Returns the new product id + the 3D-viewer surface.

Cancel an existing Shopify cart. UCP-canonical dev.ucp.shopping.cart.cancel_cart. Idempotent — re-cancelling a cancelled cart returns success. Passthrough to Shopify Storefront MCP's cancel_cart.

Cancel a Shopify checkout session. UCP-canonical dev.ucp.shopping.checkout.cancel_checkout. Idempotent — re-cancelling returns success. Idempotency-key auto-managed.

Compare 2 to 6 products side-by-side. Returns a comparison matrix with each product's name, price, brand, 3D model availability, key attributes, and a cascade-aware visual hint for each row. Optional criteria narrow which features are weighted (e.g. ['waterproof', 'budget under $150']). Returns matrix data suitable for an inline comparison Artifact. Recommended visualization: a React table Artifact with product columns (image header + name + price) and attribute rows. Use winnerIndex on each row to highlight the winning cell with _meta.curie.brand.palette.accent_color. Include a footer row of criteria_scores with weighted bars.

Complete (finalize payment + place order) a Shopify checkout session. UCP-canonical dev.ucp.shopping.checkout.complete_checkout. Requires a selected_instrument_id from the checkout's available payment instruments. Token-tier merchants complete in-protocol; Free-tier merchants return a continue_url for hosted-redirect handoff. Idempotency-key auto-managed.

Create a new Shopify cart for the target shop, optionally pre-loaded with line items. UCP-canonical dev.ucp.shopping.cart.create_cart. Returns the new cart_id + checkout_url ready for in-chat checkout handoff. Passthrough to Shopify Storefront MCP's create_cart.

Add a line to the caller's aggregated multi-merchant cart with UPSERT-increment semantics — re-adding the same (shop_domain, product_variant_id) increments the existing line's quantity instead of inserting a duplicate row. The cart row is auto-created on first add (find-or-create on identity). Identity is resolved from the request: Authorization: Bearer <jwt> for authed users, X-Curie-Device-Id (or the session device-id) for anon (matches /api/v1/aggregated-cart REST contract). Free / device-scoped — persists the cart anonymously like the wishlist; the actual purchase happens later at checkout.

List the caller's aggregated multi-merchant cart, grouped by shop_domain by default. The cart is auto-created on first call so iOS/web UIs always have a stable id for the cart-icon badge (matches REST GET behaviour). Identity resolved from Authorization: Bearer <jwt> or X-Curie-Device-Id header. Optional `shop_domain` filter returns the flat lines for a single shop. Returns `{ cart_id, shops, total_cents, currency_code, line_count }` — the same envelope the REST GET emits so iOS + web render identical numbers.

Remove a single line from the caller's aggregated cart by line_id. Identity resolved from Authorization: Bearer <jwt> or X-Curie-Device-Id header (same identity that owns the parent cart). Idempotent — removing an already-removed line is a no-op success. Destructive: the row is hard-deleted, not soft-deleted.

Set the quantity on an aggregated cart line. Special case: `quantity: 0` DELETES the line (matches UI affordance 'set to 0' === 'remove'). Identity resolved from Authorization: Bearer <jwt> or X-Curie-Device-Id header (or the session device-id for anon). Free / device-scoped — like the wishlist; the actual purchase happens later at checkout. Returns the updated line, or `{ line: null }` when the line was deleted via quantity:0.

Returns an MCP-UI UIResource for an inline 3D viewer for the given product (when a USDZ/GLB model exists). Hosts that support MCP Apps render the iframe-embedded model-viewer inline in chat; legacy hosts fall back to structured text + a direct USDZ URL. Differs from view_3d_model (which returns just the URL) — try_on_3d returns a renderable iframe component so the 3D is shown without the shopper leaving chat. Recommended visualization (fallback path): an HTML Artifact embedding Google's `<model-viewer>` web component on the GLB URL with `auto-rotate camera-controls ar ar-modes="webxr scene-viewer quick-look" ios-src="<USDZ>"`. Frame ≥480px tall. The Artifact is the fallback when the host doesn't honor `_meta.ui.resourceUri`.

Save a product to the caller's wishlist. Pinterest-style — the wishlist row is auto-created on first add (find-or-create on identity). Identity is resolved from the request: Authorization: Bearer <jwt> for authed users, X-Curie-Device-Id for anon (matches /api/v1/wishlist REST contract). When `product_url` is given without `product_id`/`shop_domain`, the URL is parsed into `{shop_domain, product_id}` via Curie's product-url-resolver so re-shares of the same product link dedupe. share_kind ∈ {url, text, image} discriminates the three iOS share-extension payload shapes; the same enum is used here so MCP-driven saves dedupe against iOS-shared saves of the same product.

List items on the caller's wishlist, newest-saved first. Wishlist is auto-created on first call (matches the REST GET behaviour so iOS UI always has a stable id). Identity resolved from Authorization: Bearer <jwt> or X-Curie-Device-Id header. Optional filters: `shop_domain` (only items from one shop), `limit` (cap; default 200, max 500). Returns the wishlist row + items array.

Mark a wishlist item AS moved-to-cart (sets `moved_to_cart_at = now()`). This tool does NOT directly add the item to a Shopify cart — cart wrapping is the host AI's job via the existing `update_cart` MCP tool. Use this tool to record the move intent on the wishlist row; then call `update_cart` separately with the product_id to complete the transfer. Pro-tier only (spends-money intent). Returns the marked-moved timestamp + a note instructing the host AI to follow up with update_cart.

Remove an item from the caller's wishlist by item_id. Identity resolved from Authorization: Bearer <jwt> or X-Curie-Device-Id header (the same identity that owns the wishlist this item belongs to). Idempotent — removing an already-removed item is a no-op success. Destructive: the row is hard-deleted, not soft-deleted.

Check product availability and pricing across retailers. Returns all affiliate links with current prices.

Returns the merchant's brand palette, typography hints, voice/tone profile, signature phrases, forbidden words, and a system_prompt_block the AI client can prepend to subsequent responses so they sound like the merchant rather than generic AI output.

Read a shopper's current cart by id. Returns line items, totals, discount info, and checkout URL. Passthrough to Shopify Storefront MCP's get_cart for the target shop; requires shop scope and is not available for cross-merchant queries.

Read a Shopify checkout session's current state by id. Returns status, line items, shipping address, totals, brand voice. UCP-canonical dev.ucp.shopping.checkout.get_checkout. Passthrough to Shopify Checkout MCP.

Read the live status of an order by id (UCP-canonical dev.ucp.shopping.order.get_order). Returns the real order body — line items, fulfillment/tracking, totals, status — when the order is visible to Curie. Visibility today is per-agent (Shopify Order MCP scope): orders placed THROUGH Curie's checkout return real data; orders placed in another session or on the storefront directly return a graceful "connect your account at chat.curie.app" state (NOT an error) because cross-session/cross-agent history requires the Customer Accounts MCP OAuth handoff (Curie slice 5 — not yet shipped). Renders the order-status surface either way.

Get full details for a specific product by its ID. The UCP/Shopify-Storefront-MCP-canonical product-detail tool. Returns the full Shopify product payload (description, options, variants, selling_plan_groups, requires_selling_plan, selectedOrFirstAvailableVariant, total_variants, url) PLUS Curie's additions (glbUrl, usdzUrl, has3DModel, media cascade, brand voice). Returns a single structured product object suitable for an inline product-detail Artifact. Recommended visualization: a React Artifact with a hero image (or embedded `<model-viewer>` when has_3d_model is true), uppercase brand label, title, price callout, and a vertical attribute list. Use _meta.curie.brand.palette for the surface + accent colors.

Get product recommendations similar to a given product. Useful for 'show me more like this' requests. Returns structured product items (same shape as search_products). Recommended visualization: a horizontal scrolling React Artifact with product cards labeled "More like this" — image, uppercase brand, title, price, 3D pill. Use _meta.curie.brand.palette.brand_color for the accent color and tap-to-view as the primary action.

Onboarding suggestion chips for the chat surface — the same 'What's trending?' / 'Find me a gift' / 'Compare products' chips chat.curie.app shows above its input. When called on a per-shop MCP endpoint (e.g. /api/mcp/allbirds.com), returns brand-themed prompts mentioning that merchant. When called on /api/mcp/global, returns cross-merchant discovery prompts. Lets any AI host (Claude.ai, ChatGPT, Cursor) render the same starting-suggestions Curie's own chat shows — universal experience across harnesses. Recommended visualization: a React Artifact with a chip-grid UI showing each prompt as a tappable button styled with _meta.curie.brand.palette.brand_color. Optional category groupings if more than 4 chips.

Begin a GUEST checkout flow for one or more products — NO sign-in required. Pass `shop_domain` (e.g. "allbirds.com") on Curie's cross-merchant route so Curie resolves the shop, creates an UNAUTHENTICATED Shopify cart, and returns its `continue_url` — the shop's OWN Shopify-hosted guest checkout where the buyer completes payment securely (Curie never charges or stores card data). On a shop-scoped connector the storeId already names the shop, so `shop_domain` is optional. `product_ids` accept the SAME identifiers `search_catalog` / `get_product` return (Shopify Product GIDs `gid://shopify/Product/...`, product URLs, or Curie UUIDs). Returns a checkout UIResource + cascade media (3D / 360° / image) for every line item.

Batch-retrieve full product objects by ID in ONE call. This is the UCP/Shopify-canonical batch product-lookup primitive (Shopify Catalog MCP's `lookup_catalog`) — the multi-id counterpart of `get_product`. Pass an array of product identifiers (the SAME identifiers `search_catalog` / `get_product` return: Shopify Product GIDs (gid://shopify/Product/...), canonical product URLs, or Curie catalog UUIDs) and Curie resolves them all against the shop's live catalog in one round-trip. Returns the same product-summary list `search_catalog` returns. Use it instead of N separate `get_product` calls when you already know which products you want (e.g. re-hydrating a cart, wishlist, or comparison set). Returns structured product items suitable for inline gallery rendering. Recommended visualization: a horizontal scrolling React Artifact with product cards showing image, uppercase brand, title, price, and a small "3D" pill when has_3d_model is true. Use _meta.curie.brand.palette.brand_color for the accent color and tap-to-view as the primary action.

Search the store catalog by name, brand, style, color, or keywords. This is the UCP/Shopify-canonical catalog-search tool (Shopify Storefront MCP's `search_catalog`, formerly `search_shop_catalog`); `search_products` is a deprecated alias of this tool. Returns matching products with images, prices, and 3D model availability. Use `max_price` / `min_price` for structured price filters — natural-language constraints like 'under $150' embedded in the query are also post-clamped server-side, but passing the structured arg is preferred (matches Shopify UCP `filters.price.min/max`). Returns structured product items suitable for inline gallery rendering. Recommended visualization: a horizontal scrolling React Artifact with product cards showing image, uppercase brand, title, price, and a small "3D" pill when has_3d_model is true. Use _meta.curie.brand.palette.brand_color for the accent color and tap-to-view as the primary action.

Get facts about the shop's policies (returns, shipping, refunds, exchanges) or product FAQs. Example questions: "What's your return policy?", "Do you ship to Canada?", "How long do exchanges take?". Passthrough to Shopify Storefront MCP's search_shop_policies_and_faqs.

Editorial 'best for the job' answer. Given a shopper's job-to-be-done (e.g. 'shoes for flat feet', 'beach wedding outfit under $200'), returns one top pick, 2 alternatives (also-great / budget / step-up), the criteria used to rank them with weights + explainers, and product citations linking back to real product pages. Use when the shopper asks a how-do-I-choose question rather than a specific-product question. Accepts `job_description` (canonical) or `goal` / `job` / `query` (aliases) — same field, named for caller convenience. Recommended visualization: an editorial-style React Artifact card showing a small uppercase "CURIE'S PICK" badge, the problem statement, the top pick (large hero image + name + price + 1-line explainer), then 2 alternative cards in a row labeled by tier (budget / step-up / also-great), then a criteria list with weighted bars. Use _meta.curie.brand.palette for the editorial frame.

Modify a Shopify cart — add line items, update quantities, remove lines. Pass cart_id=null to create a new cart. Returns the updated cart with checkout URL ready for in-chat completion. Passthrough to Shopify Storefront MCP's update_cart.

Update fields on a Shopify checkout session. UCP-canonical dev.ucp.shopping.checkout.update_checkout — Curie's wrapper performs a PUT-semantics-safe diff (fetches current state, merges your partial input, forwards the full payload) so omitting a field doesn't silently delete it. Set `clear_fields[]` to explicitly clear values.