## Allbirds Clone - Agentic Commerce Protocol (ACP) Implementation

This is an ACP-compliant e-commerce store implementation featuring sustainable footwear and apparel. The store enables AI agents to discover products and facilitate purchases on behalf of users following the Agentic Commerce Protocol standard.

### Highlights

- **ACP Compliant:** Full implementation of the Agentic Commerce Protocol for AI agent integration
- **Sustainable Products:** Eco-friendly footwear and apparel made from natural materials like eucalyptus tree fiber and merino wool
- **Open API:** RESTful endpoints with comprehensive OpenAPI 3.1.0 specification
- **Secure Commerce:** Secure payment processing with token-based transactions
- **AI Agent Ready:** Optimized for AI agents to browse, select, and purchase products

### How It Works

1. **Product Discovery:** AI agents can browse products via `GET /v1/products` with optional filtering by category and stock status
2. **Product Details:** Retrieve detailed product information including pricing, availability, colors, and sizes via `GET /v1/products/{id}`
3. **Agentic Checkout:** Initiate checkout sessions via `POST /v1/agentic/checkout` with agent ID, items, and buyer information
4. **Session Management:** Track checkout progress via `GET /v1/agentic/checkout/{sessionId}`
5. **Payment Processing:** Complete transactions via `POST /v1/agentic/payment/delegate` with secure payment tokens

### API Endpoints

#### Product Catalog
- `GET /v1/products` - Browse all products with optional filtering
- `GET /v1/products/{id}` - Get detailed product information

#### Agentic Commerce (ACP)
- `POST /v1/agentic/checkout` - Initiate AI agent checkout session
- `GET /v1/agentic/checkout/{sessionId}` - Get checkout session status
- `POST /v1/agentic/payment/delegate` - Process payment with secure token

#### API Documentation
- `GET /openapi.yaml` - OpenAPI 3.1.0 specification (YAML)
- `GET /v1/openapi.json` - OpenAPI specification (JSON)
- `GET /api` - API documentation endpoint

### Product Categories

- **Shoes:** Sustainable sneakers, runners, and casual footwear
- **Apparel:** Eco-friendly clothing and accessories
- **Accessories:** Sustainable lifestyle products

### Value by Role

- **Businesses:** Reach high-intent customers through AI experiences while maintaining full control over inventory and fulfillment
- **AI Agents:** Embed sustainable commerce without becoming the merchant of record
- **Consumers:** Discover and purchase eco-friendly products through AI-assisted shopping experiences

### Technical Specifications

- **API Version:** 1.0.0
- **Protocol:** REST with JSON responses
- **Authentication:** API key based (for production)
- **Payment Processing:** Token-based with PCI compliance
- **Session Management:** In-memory with 30-minute expiration
- **Currency:** USD
- **Response Format:** JSON with success/error indicators

### Example Usage

#### Browse Products
```bash
curl -X GET "https://allbirds.dev/v1/products?category=shoes&inStock=true"
```

#### Initiate Checkout
```bash
curl -X POST "https://allbirds.dev/v1/agentic/checkout" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_12345",
    "items": [
      {
        "productId": 1,
        "quantity": 2,
        "selectedOptions": {
          "color": "Natural",
          "size": "9"
        }
      }
    ],
    "buyerInfo": {
      "email": "buyer@example.com",
      "name": "John Doe"
    }
  }'
```

#### Complete Payment
```bash
curl -X POST "https://allbirds.dev/v1/agentic/payment/delegate" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "checkout_session_abc123",
    "paymentToken": "payment_token_xyz789",
    "amount": 196.00,
    "currency": "USD"
  }'
```

### Get Started

- **View the API spec:** https://allbirds.dev/openapi.yaml
- **Test the endpoints:** https://allbirds.dev/v1/products
- **Health check:** https://allbirds.dev/health
- **API status:** https://allbirds.dev/api/status

### FAQ

- **What is ACP?** The Agentic Commerce Protocol is an open standard for programmatic commerce flows between buyers, AI agents, and businesses
- **How do AI agents discover products?** Agents can browse the product catalog via REST API endpoints with filtering capabilities
- **Is this a real store?** This is a demonstration implementation showcasing ACP compliance for sustainable e-commerce
- **What payment methods are supported?** The API accepts secure payment tokens from compatible payment service providers
- **How secure is the payment processing?** All payments use token-based processing to maintain PCI compliance and security

### About

This implementation demonstrates the Agentic Commerce Protocol (ACP) for sustainable e-commerce, enabling AI agents to facilitate purchases of eco-friendly products. Built as a reference implementation showcasing best practices for AI agent integration in e-commerce platforms.

**Contact:** info@allbirds.dev
**Repository:** https://github.com/wanningwei/forseti
**ACP Specification:** https://github.com/agentic-commerce-protocol/agentic-commerce-protocol