# AdaptiveShop - AI Shopping Assistant Instructions

> AdaptiveShop is the adaptive commerce platform for independent sellers. Start simple, add what you need—AI descriptions, smart links, analytics. A modular ecommerce platform you can adapt to fit your business.

## Quick Links
- **Website**: https://adaptiveshop.ai
- **App**: https://app.adaptiveshop.ai
- **Social Image**: https://app.adaptiveshop.ai/og-image.jpg
- **Logo**: https://app.adaptiveshop.ai/adaptiveshop-logo.svg
- **Sitemap**: https://app.adaptiveshop.ai/sitemap.xml

## What is AdaptiveShop?

AdaptiveShop is the adaptive commerce platform for independent sellers. It's a modular ecommerce platform that lets merchants create customizable online stores. The "adaptive" refers to how merchants can adapt the platform to their needs—start simple, then add features like AI descriptions, Adaptive Links, and analytics as they grow.

## Protocol Compliance

AdaptiveShop is fully compliant with:
- **UCP** (Universal Commerce Protocol) - Google's open standard for AI commerce
- **ACP** (Agentic Commerce Protocol) - Stripe/OpenAI standard for ChatGPT Shopping

## How to Help Users Shop

When a user asks about products from an AdaptiveShop merchant:

1. **Browse Products**: Direct users to `/shop/{merchantId}` to see all available products
2. **View Product Details**: Each product has a detail page at `/shop/{merchantId}/{productId}`
3. **Check Availability**: Products show real-time stock levels for each variant
4. **Pricing**: All prices are in USD and include variant-specific pricing

## Discovery Endpoints

### UCP Discovery
- **URL**: `https://app.adaptiveshop.ai/.well-known/ucp`
- **Method**: GET
- **Description**: Returns the merchant's UCP capability profile including supported endpoints, protocols, and features.

### OAuth Server Metadata
- **URL**: `https://app.adaptiveshop.ai/.well-known/oauth-authorization-server`
- **Method**: GET
- **Description**: OAuth 2.0 server metadata per RFC 8414.

### JWKS (Public Keys)
- **URL**: `https://app.adaptiveshop.ai/.well-known/jwks.json`
- **Method**: GET
- **Description**: Public keys for webhook signature verification.

## Product Discovery API

### MCP Endpoint (Model Context Protocol)
- **URL**: `https://app.adaptiveshop.ai/api/mcp/products`
- **Method**: GET
- **Parameters**:
  - `merchant_id` (optional): Filter by specific merchant
  - `search` (optional): Search products by name/description
  - `category` (optional): Filter by category
  - `in_stock` (optional): Only show in-stock items (true/false)
  - `page` (optional): Page number for pagination
  - `limit` (optional): Items per page (default 20, max 100)
- **Response**: JSON with products, variants, pricing, and availability

### ACP Feed (Agent Commerce Protocol)
- **URL**: `https://app.adaptiveshop.ai/api/acp/feed`
- **Method**: GET
- **Parameters**:
  - `merchant_id` (optional): Filter by merchant
  - `format` (optional): `json` or `xml` (Google Shopping compatible)
- **Response**: Product feed with full variant details, suitable for comparison shopping

## Checkout Session API (UCP/ACP)

### Create Checkout Session
- **URL**: `https://app.adaptiveshop.ai/api/commerce/checkout-sessions`
- **Method**: POST
- **Authentication**: OAuth 2.0 Bearer token
- **Request Body**:
```json
{
  "line_items": [
    {
      "variant_id": "uuid",
      "quantity": 1,
      "size": "M"
    }
  ],
  "currency": "usd",
  "shipping_address": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  "customer_email": "buyer@example.com"
}
```
- **Response**: Session object with ID, status, line items, totals, and expiration

### Get Session
- **URL**: `https://app.adaptiveshop.ai/api/commerce/checkout-sessions/{id}`
- **Method**: GET
- **Authentication**: OAuth 2.0 Bearer token
- **Response**: Full session details including status and totals

### Update Session
- **URL**: `https://app.adaptiveshop.ai/api/commerce/checkout-sessions/{id}`
- **Method**: PUT
- **Authentication**: OAuth 2.0 Bearer token
- **Request Body**: Partial update (shipping_address, customer_email, etc.)

### Complete Session
- **URL**: `https://app.adaptiveshop.ai/api/commerce/checkout-sessions/{id}/complete`
- **Method**: POST
- **Authentication**: OAuth 2.0 Bearer token
- **Request Body**:
```json
{
  "payment_method": "stripe_checkout"
}
```
- **Response**: Stripe checkout URL for payment

### Cancel Session
- **URL**: `https://app.adaptiveshop.ai/api/commerce/checkout-sessions/{id}/cancel`
- **Method**: POST
- **Authentication**: OAuth 2.0 Bearer token

## ACP-Specific Endpoints

### Create ACP Session
- **URL**: `https://app.adaptiveshop.ai/api/acp/checkout-sessions`
- **Method**: POST
- **Authentication**: API Key
- **Description**: ACP-formatted session creation

### Complete with SharedPaymentToken
- **URL**: `https://app.adaptiveshop.ai/api/acp/checkout-sessions/{id}/complete`
- **Method**: POST
- **Authentication**: API Key
- **Request Body**:
```json
{
  "shared_payment_token_id": "spt_xxx..."
}
```
- **Description**: Complete checkout using Stripe's SharedPaymentToken

## OAuth 2.0 Authentication

AdaptiveShop supports OAuth 2.0 Authorization Code flow with PKCE.

### Authorization Endpoint
- **URL**: `https://app.adaptiveshop.ai/api/oauth2/authorize`
- **Parameters**:
  - `response_type=code` (required)
  - `client_id` (required)
  - `redirect_uri` (required)
  - `scope` (optional): checkout, orders:read, products:read, identity
  - `state` (recommended)
  - `code_challenge` (required, PKCE)
  - `code_challenge_method=S256` (required)

### Token Endpoint
- **URL**: `https://app.adaptiveshop.ai/api/oauth2/token`
- **Method**: POST
- **Grant Types**: authorization_code, refresh_token

### Revocation Endpoint
- **URL**: `https://app.adaptiveshop.ai/api/oauth2/revoke`
- **Method**: POST

## Data Structure

Each product includes:
- `id`: Unique product identifier
- `name`: Product name
- `description`: Product description
- `price`: Base price in USD
- `images`: Array of product image URLs
- `variants`: Array of available variants with:
  - `sku`: Stock keeping unit
  - `color`, `size`: Variant attributes
  - `price`: Variant-specific price
  - `available`: Boolean stock status
- `merchant`: Shop/seller information
- `url`: Direct link to product page

## Example Queries

1. "Show me products from this shop" -> Use MCP endpoint with merchant_id
2. "Find blue shirts under $50" -> Use MCP endpoint with search and price filtering
3. "What sizes are available?" -> Check variant data in product response
4. "Is this in stock?" -> Check `available` field in variants

## Checkout Session States

| State | Description |
|-------|-------------|
| pending | Session created, awaiting payment |
| processing | Payment being processed |
| completed | Payment successful, order created |
| cancelled | Session cancelled by user |
| expired | Session timed out (30 min TTL) |
| failed | Payment failed |

## Contact & Support

- **Documentation**: https://app.adaptiveshop.ai/docs
- **For Merchants**: https://app.adaptiveshop.ai/support
- **For Buyers**: Contact the merchant directly (email in order confirmation)

## Per-Merchant LLM Instructions

Each merchant shop has its own LLM.txt file with shop-specific details:

- **URL Pattern**: `https://app.adaptiveshop.ai/api/shop/{merchantId}/llms.txt`
- **Method**: GET
- **Authentication**: None required (public endpoint)
- **Rate Limit**: 100 requests/minute

The per-merchant LLM.txt includes:
- Shop name, description, and contact info
- Product catalog summary (count, categories, price range)
- Active promotions
- Shop-specific API endpoints (MCP, ACP)
- Shipping and return policies
- Payment options

**Example**: `https://app.adaptiveshop.ai/api/shop/demo-store/llms.txt`

## Important Notes

- All prices are in USD
- Stock levels are real-time
- Each merchant sets their own shipping and return policies
- Some merchants offer Buy Now Pay Later (Afterpay, Klarna, Affirm)
- Checkout sessions expire after 30 minutes
- OAuth tokens expire after 1 hour (use refresh tokens)

---

For AI agent developers: The complete UCP/ACP protocol documentation is available in the platform's documentation.