# CartBridge

CartBridge is an AI Checkout Control Center for Shopify merchants. It helps merchants see, test, control, and safely route AI-agent shopping before it becomes a black box. For agents, CartBridge still provides authenticated catalog search, native cart creation, signed quotes, checkout-link fallback, and purchase confirmation after Shopify webhooks sync.

Base URL: https://cartbridge.ai
OpenAPI: https://cartbridge.ai/openapi.yaml
JavaScript client: https://cartbridge.ai/examples/cartbridge-agent-client.mjs
MCP server example: https://cartbridge.ai/examples/cartbridge-mcp-server.mjs
UCP agent profile: https://cartbridge.ai/.well-known/ucp-agent-profile.json

Core rules:
- Always authenticate with Authorization: Bearer CARTBRIDGE_AGENT_KEY.
- Always send X-Buyer-IP for Shopify Storefront calls.
- Never send raw card data, wallet credentials, or bank data.
- CartBridge creates native Shopify carts and returns Shopify checkout URLs.
- Shopify checkout remains responsible for payment, tax, fraud checks, order creation, fulfillment, refunds, and analytics.
- Treat cart totals as estimates until checkout completes and an order webhook syncs.
- Prefer Shopify checkout-link fallback unless CartBridge reports direct UCP / Shop Pay checkout is ready.

Recommended LLM flow:
1. Search products with GET /v1/shopify/products/search?shop={shop}&q={query}&country=US.
2. Pick a buyable variant that fits the user's request and authority policy.
3. Create a native cart with POST /v1/shopify/carts.
4. Show the signed quote to the user and request approval when required.
5. Approve checkout with POST /v1/shopify/carts/{cartId}/checkout-session.
6. Send the user to checkoutUrl for Shopify checkout.
7. Read GET /v1/shopify/carts/{cartId}/purchase-result and surface state, nextAction, confirmation, totals, and line items.
8. If needed, poll cartbridge_purchase_result or cartbridge_wait_for_order until Shopify webhooks reconcile an order.

MCP tools:
- cartbridge_search_products
- cartbridge_prepare_checkout
- cartbridge_create_cart
- cartbridge_approve_checkout
- cartbridge_cart_status
- cartbridge_purchase_result
- cartbridge_ucp_checkout
- cartbridge_wait_for_order

Shortest MCP demo:
Use cartbridge_prepare_checkout with shop, query, userRequest, authorityId, approvedBy, country, and maxTotal. It returns selected variant, cart, quote, checkoutUrl, and purchaseResult.

Purchase result states:
- quote_ready: ask the user to approve the quote.
- checkout_started: wait for Shopify checkout completion and order webhook sync.
- order_synced: show order status and details.
- confirmed: show purchase confirmation and final order details.

Future Shopify UCP / Shop Pay:
CartBridge publishes a UCP agent profile and exposes POST /v1/shopify/ucp/checkouts. This is a probe for Shopify Checkout MCP support. If the merchant storefront is password-protected, the response can report a structured 302 redirect to /password.