# San Collective

> A Shopify-first vertical marketplace surface. San Collective helps shoppers and AI shopping agents discover, compare, and buy mountain-inspired outdoor gear from independent Shopify merchants. Purchases complete through each merchant's own Shopify checkout. San Collective is never the merchant of record.

## Allowed use

- You may read our pages and JSON endpoints to help a shopper discover and compare products.
- You may hand a shopper off to a merchant's Shopify checkout using the checkout URLs we return.
- Please do not scrape merchant storefronts. Use our endpoints and the Shopify Catalog data we surface instead.
- Identify yourself with a descriptive User-Agent when you can.

## Endpoints

- POST https://sancollective.com/api/assistant — turn a natural-language request into a Catalog query and filters. Body: { message, includeResults?, shipsToCountry?, priceCurrency?, limit? }
- POST https://sancollective.com/api/search — search the Shopify Catalog. Body: { query, shipsToCountry?, region?, priceCurrency?, priceMax?, availableNow?, seller?, limit?, cursor? }
- GET  https://sancollective.com/api/product?id=PRODUCT_ID — full product detail (gallery, variants, offers, checkout URLs).
- POST https://sancollective.com/api/compare — find comparable products across merchants. Body: { productId, title, sellerName?, shipsToCountry? }
- POST https://sancollective.com/api/compare-summary — generate a short, grounded comparison summary. Body: { products: [{ title, price?, currency?, availability?, seller? }] }
- POST https://sancollective.com/api/cart — group collected items into one Shopify checkout per merchant. Body: { items: [{ productId, variantId?, quantity?, checkoutUrl?, seller? }], checkoutStrategy?: "permalink" | "ucp_cart" }
- POST https://sancollective.com/api/checkout-handoff — resolve a single-item Shopify checkout URL. Body: { productId, variantId?, quantity?, checkoutUrl? }
- POST https://sancollective.com/api/lookup — batch product lookup. Body: { ids?: [], urls?: [] }
- GET  https://sancollective.com/api/capabilities — machine-readable capability + policy document.
- GET  https://sancollective.com/openapi.json — OpenAPI 3.1 description of these endpoints.
- GET  https://sancollective.com/agents — browser-readable guide for shopping agents.
- GET  https://sancollective.com/checkout — human checkout review page that prepares UCP merchant carts first, with checkout URL fallback.

## Recommended agent flow

1. Read /api/capabilities or /openapi.json.
2. For natural language requests, call /api/assistant with includeResults=true.
3. Use /api/product or /api/compare when the shopper needs more detail.
4. Use /api/cart with checkoutStrategy="ucp_cart" to create merchant-scoped Shopify UCP carts where available; fall back to checkoutAction.url otherwise.
5. Open each group's checkoutAction.url or use /api/checkout-handoff for a single item.

## Checkout handoff

San Collective does not process payments. Each product carries a Shopify checkout URL for its merchant. When a shopper's items span multiple Shopify stores, they complete one checkout per store. /api/cart can try UCP Cart MCP per merchant and returns cartMcp.status plus a checkoutAction URL; when UCP Cart is unavailable it falls back to a Shopify cart permalink, a single checkout URL, or a store visit. Refresh product availability before opening a checkout when possible.

## Policy

- No scraping of merchant storefronts.
- Product and offer identifiers are stable where Shopify Catalog provides them.
- Responses include availability, refreshedAt timestamps, source attribution, and checkout handoff URLs.