Shopping agents

Shop San Collective through the JSON API.

San Collective is a Shopify-first marketplace surface. Agents can search products, compare options, group carts by merchant, and hand shoppers off to each Shopify store's checkout without scraping merchant storefronts.

llms.txtCapabilities JSONOpenAPI JSON

Recommended Flow

  1. Discover capabilities.Read /api/capabilities or /openapi.json.
  2. Start from natural language.POST /api/assistant with includeResults: true to get a Catalog query, filters, and product results.
  3. Inspect products.Use /api/product for fresh gallery, variant, availability, offer, and checkout data.
  4. Compare alternatives.Use /api/compare and /api/compare-summary to explain tradeoffs.
  5. Build the cart.POST selected items to /api/cart with checkoutStrategy: "ucp_cart". The response tries merchant-scoped UCP carts first, then falls back to Shopify checkout URLs or cart permalinks.
  6. Hand off checkout.Open each group's checkoutAction.url, or use /api/checkout-handofffor a single product.

Example Request

POST /api/assistant
{
  "message": "camp chairs under $150 available now",
  "includeResults": true,
  "shipsToCountry": "US",
  "limit": 8
}
POST /api/cart
{
  "checkoutStrategy": "ucp_cart",
  "items": [
    {
      "productId": "gid://shopify/Product/...",
      "variantId": "gid://shopify/ProductVariant/...",
      "quantity": 1,
      "checkoutUrl": "https://merchant.example/cart/123:1",
      "seller": { "name": "Merchant", "url": "https://merchant.example" }
    }
  ]
}

Commerce Rules

  • Use San Collective API responses instead of scraping merchant storefronts.
  • San Collective never processes payment and is never merchant of record.
  • Multi-store carts produce one Shopify checkout or UCP cart handoff per merchant.
  • For humans, /checkout provides a browser-readable merchant checkout review.
  • Product and offer responses include refreshedAt timestamps where available.