openapi: 3.1.0
info:
  title: Agentic Commerce Protocol - E-commerce Store API
  description: |
    ACP-compliant API for sustainable e-commerce store supporting agentic commerce.
    This API enables AI agents to discover products and facilitate purchases on behalf of users.
    
    **Agentic Commerce Protocol (ACP)** is an open standard for connecting buyers, 
    their AI agents, and businesses to complete purchases seamlessly.
    
    This implementation follows the OpenAI Commerce specifications:
    - Product Feed Specification for product discovery and indexing
    - Agentic Checkout Specification for AI agent-assisted purchases
    - Delegated Payment Specification for secure payment processing
  version: 1.0.0
  contact:
    name: E-commerce Store
    url: https://allbirds.dev
    email: info@allbirds.dev
  license:
    name: Apache-2.0
    url: https://opensource.org/licenses/Apache-2.0
  x-acp-version: "1.0.0"
  x-acp-compliance: true
  x-acp-specifications:
    - "Product Feed Spec v1.0"
    - "Agentic Checkout Spec v1.0"
    - "Delegated Payment Spec v1.0"

servers:
  - url: https://allbirds.dev
    description: Production server

paths:
  /v1/feed:
    get:
      summary: Get Product Feed
      description: |
        Retrieve the complete product catalog feed following the ACP Product Feed Specification.
        This endpoint provides structured product data for AI agents to discover and index products.
        Supports TSV, CSV, XML, and JSON formats as specified in the ACP Product Feed Spec.
      operationId: getProductFeed
      tags:
        - Product Feed
      parameters:
        - name: format
          in: query
          description: Output format for the product feed
          required: false
          schema:
            type: string
            enum: [json, tsv, csv, xml]
            default: json
        - name: enable_search
          in: query
          description: Filter products by search availability
          required: false
          schema:
            type: boolean
        - name: enable_checkout
          in: query
          description: Filter products by checkout availability
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: Product feed retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductFeed'
            text/tab-separated-values:
              schema:
                type: string
                description: TSV format product feed
            text/csv:
              schema:
                type: string
                description: CSV format product feed
            application/xml:
              schema:
                type: string
                description: XML format product feed

  /v1/products:
    get:
      summary: Get products (redirects to product feed)
      description: |
        This endpoint redirects to the ACP-compliant product feed endpoint.
        For backward compatibility, requests to /v1/products are redirected to /v1/feed.
      operationId: getProducts
      tags:
        - Products
      responses:
        '301':
          description: Redirect to ACP-compliant product feed
          headers:
            Location:
              description: URL to redirect to
              schema:
                type: string
                example: "/v1/feed?format=json"

  /v1/products/{id}:
    get:
      summary: Get product by ID
      description: Retrieve a specific product by its ID
      operationId: getProductById
      tags:
        - Products
      parameters:
        - name: id
          in: path
          description: Product ID
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Product'
                  timestamp:
                    type: string
                    format: date-time
        '404':
          description: Product not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  # ACP Agentic Checkout Endpoints
  /agentic/checkout:
    post:
      summary: Initiate agentic checkout
      description: |
        Initiates an agentic checkout session for AI agents to facilitate purchases.
        This endpoint follows the Agentic Commerce Protocol (ACP) standard.
      operationId: initiateAgenticCheckout
      tags:
        - Agentic Commerce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgenticCheckoutRequest'
      responses:
        '200':
          description: Checkout session initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgenticCheckoutResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /agentic/checkout/{sessionId}:
    get:
      summary: Get checkout session status
      description: Retrieve the current status of an agentic checkout session
      operationId: getCheckoutSession
      tags:
        - Agentic Commerce
      parameters:
        - name: sessionId
          in: path
          description: Checkout session ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Checkout session status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSessionStatus'
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /agentic/payment/delegate:
    post:
      summary: Delegate payment processing
      description: |
        Delegates payment processing to the merchant's payment provider.
        This endpoint follows the ACP delegate payment specification.
      operationId: delegatePayment
      tags:
        - Agentic Commerce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DelegatePaymentRequest'
      responses:
        '200':
          description: Payment delegated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DelegatePaymentResponse'
        '400':
          description: Invalid payment request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    ProductFeed:
      type: object
      required:
        - products
        - feed_metadata
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        feed_metadata:
          type: object
          properties:
            feed_version:
              type: string
              example: "1.0.0"
            last_updated:
              type: string
              format: date-time
              example: "2025-01-20T10:30:00Z"
            total_products:
              type: integer
              example: 4
            format:
              type: string
              enum: [json, tsv, csv, xml]
              example: "json"

    ProductsData:
      type: object
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        total:
          type: integer
          example: 4

    Product:
      type: object
      required:
        - id
        - title
        - price
        - product_category
        - description
        - link
        - enable_search
        - enable_checkout
        - seller_name
        - seller_url
        - return_policy
        - return_window
      properties:
        # OpenAI Flags (ACP Required)
        enable_search:
          type: boolean
          description: Controls whether the product can be surfaced in ChatGPT search results
          example: true
        enable_checkout:
          type: boolean
          description: Allows direct purchase inside ChatGPT
          example: true
        
        # Basic Product Data (ACP Required)
        id:
          type: string
          description: Merchant product ID (unique, max 100 chars)
          example: "SKU12345"
        gtin:
          type: string
          description: Universal product identifier (8-14 digits)
          example: "123456789543"
        mpn:
          type: string
          description: Manufacturer part number (max 70 chars)
          example: "GPT5"
        title:
          type: string
          description: Product title (max 150 chars)
          example: "Tree Runners - Men's Trail Running Shoes"
        description:
          type: string
          description: Full product description (max 5,000 chars)
          example: "Comfortable sneakers made from eucalyptus tree fiber with cushioned sole and breathable design"
        link:
          type: string
          format: uri
          description: Product detail page URL
          example: "https://allbirds.dev/product/SKU12345"
        
        # Item Information (ACP Required)
        condition:
          type: string
          enum: [new, refurbished, used]
          description: Condition of product
          example: "new"
        product_category:
          type: string
          description: Category path using ">" separator
          example: "Apparel & Accessories > Shoes > Athletic Shoes"
        brand:
          type: string
          description: Product brand (max 70 chars)
          example: "Allbirds"
        material:
          type: string
          description: Primary material(s) (max 100 chars)
          example: "Eucalyptus Tree Fiber"
        
        # Pricing (ACP Required)
        price:
          type: number
          description: Product price
          example: 98.00
        currency:
          type: string
          description: Currency code (ISO 4217)
          example: "USD"
        availability:
          type: string
          enum: [in_stock, out_of_stock, preorder, discontinued]
          description: Product availability
          example: "in_stock"
        
        # Media (ACP Recommended)
        image_link:
          type: string
          format: uri
          description: Main product image URL
          example: "https://allbirds.dev/images/tree-runners.jpg"
        additional_image_link:
          type: array
          items:
            type: string
            format: uri
          description: Additional product image URLs
          example: ["https://allbirds.dev/images/tree-runners-side.jpg"]
        
        # Variants (ACP Optional)
        color:
          type: string
          description: Product color
          example: "Natural"
        size:
          type: string
          description: Product size
          example: "9"
        gender:
          type: string
          enum: [male, female, unisex]
          description: Gender target
          example: "unisex"
        
        # Merchant Info (ACP Required)
        seller_name:
          type: string
          description: Seller name (max 70 chars)
          example: "Allbirds Store"
        seller_url:
          type: string
          format: uri
          description: Seller page
          example: "https://allbirds.dev/store"
        seller_privacy_policy:
          type: string
          format: uri
          description: Seller-specific policies
          example: "https://allbirds.dev/privacy"
        seller_tos:
          type: string
          format: uri
          description: Seller-specific terms of service
          example: "https://allbirds.dev/terms"
        
        # Returns (ACP Required)
        return_policy:
          type: string
          format: uri
          description: Return policy URL
          example: "https://allbirds.dev/returns"
        return_window:
          type: integer
          description: Days allowed for return
          example: 30
        
        # Performance Signals (ACP Recommended)
        popularity_score:
          type: number
          description: Popularity indicator (0-5 scale)
          example: 4.7
        product_review_count:
          type: integer
          description: Number of product reviews
          example: 254
        product_review_rating:
          type: number
          description: Average review score (0-5 scale)
          example: 4.6
        
        # Fulfillment (ACP Optional)
        shipping:
          type: string
          description: Shipping method/cost/region
          example: "US:CA:Standard:9.99 USD"
        delivery_estimate:
          type: string
          format: date
          description: Estimated arrival date
          example: "2025-08-12"

    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: "Missing required fields"
        required:
          type: array
          items:
            type: string
          example: ["serviceType", "urgency", "firstName"]

    # ACP Agentic Commerce Schemas
    AgenticCheckoutRequest:
      type: object
      required:
        - agent_id
        - items
        - buyer_info
        - session_context
      properties:
        agent_id:
          type: string
          description: Unique identifier for the AI agent initiating the checkout
          example: "agent_12345"
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItem'
          description: List of items to purchase
          minItems: 1
        buyer_info:
          $ref: '#/components/schemas/BuyerInfo'
        session_context:
          $ref: '#/components/schemas/SessionContext'
        metadata:
          type: object
          description: Additional metadata for the transaction
          additionalProperties: true

    SessionContext:
      type: object
      required:
        - user_agent
        - timestamp
      properties:
        user_agent:
          type: string
          description: User agent string from the AI agent
          example: "ChatGPT-Agent/1.0"
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the session was initiated
          example: "2025-01-20T10:30:00Z"
        session_id:
          type: string
          description: Optional session identifier
          example: "session_abc123"
        context_data:
          type: object
          description: Additional context data
          additionalProperties: true

    CartItem:
      type: object
      required:
        - product_id
        - quantity
      properties:
        product_id:
          type: string
          description: Product ID from the catalog (must match Product.id)
          example: "SKU12345"
        quantity:
          type: integer
          minimum: 1
          maximum: 100
          description: Quantity to purchase
          example: 2
        selected_options:
          type: object
          description: Selected product options (color, size, etc.)
          properties:
            color:
              type: string
              example: "Natural"
            size:
              type: string
              example: "9"
            material:
              type: string
              example: "Eucalyptus"
        price_override:
          type: number
          description: Override price for this item (optional)
          example: 95.00
        currency:
          type: string
          description: Currency for price override
          example: "USD"

    BuyerInfo:
      type: object
      required:
        - email
        - contact_info
      properties:
        email:
          type: string
          format: email
          description: Buyer's email address
          example: "buyer@example.com"
        contact_info:
          $ref: '#/components/schemas/ContactInfo'
        shipping_address:
          $ref: '#/components/schemas/Address'
        billing_address:
          $ref: '#/components/schemas/Address'
        preferences:
          type: object
          description: Buyer preferences and settings
          properties:
            language:
              type: string
              example: "en-US"
            currency:
              type: string
              example: "USD"
            marketing_consent:
              type: boolean
              example: false

    ContactInfo:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Buyer's full name
          example: "John Doe"
        phone:
          type: string
          description: Phone number (optional)
          example: "+1-555-123-4567"
        company:
          type: string
          description: Company name (optional)
          example: "Acme Corp"

    Address:
      type: object
      required:
        - street
        - city
        - state
        - postal_code
        - country
      properties:
        street:
          type: string
          description: Street address
          example: "123 Main St"
        city:
          type: string
          description: City name
          example: "San Francisco"
        state:
          type: string
          description: State or province
          example: "CA"
        postal_code:
          type: string
          description: Postal or ZIP code
          example: "94105"
        country:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
          example: "US"
        apartment:
          type: string
          description: Apartment or suite number (optional)
          example: "Apt 4B"

    AgenticCheckoutResponse:
      type: object
      required:
        - success
        - session_id
        - checkout_url
        - session_expires_at
        - total_amount
        - currency
      properties:
        success:
          type: boolean
          example: true
        session_id:
          type: string
          description: Unique checkout session identifier
          example: "checkout_session_abc123"
        checkout_url:
          type: string
          format: uri
          description: URL for completing the checkout
          example: "https://checkout.allbirds.wanning.dev/session/abc123"
        session_expires_at:
          type: string
          format: date-time
          description: Session expiration time
          example: "2025-01-20T11:00:00Z"
        total_amount:
          type: number
          description: Total amount for the checkout
          example: 196.00
        currency:
          type: string
          description: Currency code (ISO 4217)
          example: "USD"
        payment_methods:
          type: array
          description: Available payment methods
          items:
            type: string
          example: ["credit_card", "paypal", "apple_pay"]
        shipping_options:
          type: array
          description: Available shipping options
          items:
            $ref: '#/components/schemas/ShippingOption'

    ShippingOption:
      type: object
      required:
        - id
        - name
        - cost
        - estimated_days
      properties:
        id:
          type: string
          description: Shipping option identifier
          example: "standard"
        name:
          type: string
          description: Shipping option name
          example: "Standard Shipping"
        cost:
          type: number
          description: Shipping cost
          example: 9.99
        currency:
          type: string
          description: Currency code
          example: "USD"
        estimated_days:
          type: integer
          description: Estimated delivery time in days
          example: 5
        description:
          type: string
          description: Additional shipping details
          example: "5-7 business days"

    CheckoutSessionStatus:
      type: object
      required:
        - session_id
        - status
        - created_at
        - updated_at
      properties:
        session_id:
          type: string
          example: "checkout_session_abc123"
        status:
          type: string
          enum: [pending, processing, completed, expired, cancelled, failed]
          example: "pending"
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItem'
        total_amount:
          type: number
          example: 196.00
        currency:
          type: string
          example: "USD"
        payment_status:
          type: string
          enum: [pending, processing, completed, failed, refunded]
          example: "pending"
        shipping_status:
          type: string
          enum: [pending, processing, shipped, delivered, cancelled]
          example: "pending"
        created_at:
          type: string
          format: date-time
          example: "2025-01-20T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2025-01-20T10:35:00Z"

    DelegatePaymentRequest:
      type: object
      required:
        - session_id
        - payment_method
        - payment_details
        - amount
        - currency
      properties:
        session_id:
          type: string
          description: Checkout session ID
          example: "checkout_session_abc123"
        payment_method:
          type: string
          enum: [credit_card, debit_card, paypal, apple_pay, google_pay, bank_transfer]
          description: Payment method type
          example: "credit_card"
        payment_details:
          type: object
          description: Payment method specific details
          properties:
            token:
              type: string
              description: Secure payment token from the AI agent's payment provider
              example: "payment_token_xyz789"
            last_four:
              type: string
              description: Last four digits of card (if applicable)
              example: "1234"
            expiry_month:
              type: integer
              description: Card expiry month (if applicable)
              example: 12
            expiry_year:
              type: integer
              description: Card expiry year (if applicable)
              example: 2025
        amount:
          type: number
          description: Payment amount
          example: 196.00
        currency:
          type: string
          description: Currency code (ISO 4217)
          example: "USD"
        metadata:
          type: object
          description: Additional payment metadata
          additionalProperties: true

    DelegatePaymentResponse:
      type: object
      required:
        - success
        - payment_id
        - status
        - processed_at
      properties:
        success:
          type: boolean
          example: true
        payment_id:
          type: string
          description: Unique payment identifier
          example: "payment_12345"
        status:
          type: string
          enum: [pending, processing, completed, failed, refunded]
          example: "completed"
        transaction_id:
          type: string
          description: External transaction ID from payment provider
          example: "txn_67890"
        amount:
          type: number
          example: 196.00
        currency:
          type: string
          example: "USD"
        processed_at:
          type: string
          format: date-time
          example: "2025-01-20T10:35:00Z"
        payment_method:
          type: string
          description: Payment method used
          example: "credit_card"
        failure_reason:
          type: string
          description: Reason for payment failure (if applicable)
          example: "insufficient_funds"

tags:
  - name: Product Feed
    description: |
      Product Feed endpoints following the ACP Product Feed Specification.
      Provides structured product data for AI agents to discover and index products.
  - name: Products
    description: Product catalog and inventory management
  - name: Agentic Commerce
    description: |
      Agentic Commerce Protocol (ACP) endpoints for AI agent integration.
      These endpoints enable AI agents to discover products and facilitate purchases
      on behalf of users following the ACP standard.