Build an Agent-Ready Commerce API in a Weekend — FastAPI, Vercel, and the Endpoints AI Agents Actually Call.

The Schema layer gets you found. The API layer gets you paid.

An AI agent hitting your storefront does not load a browser. It does not execute JavaScript bundles. It does not click through redirect chains. It calls endpoints directly, parses JSON, decides what to do, and calls more endpoints. If your only agent-facing surface is the HTML page — even one with clean Product and Offer markup — the agent can discover you but cannot transact. To transact, you need an API designed for the agent: stateless, typed, idempotent, and self-describing. That is what this page builds. By the end you will have a working FastAPI app, a verified Vercel deployment, and five core endpoints (eight total) that cover the full agent purchase flow from search to order confirmation — written once, deployed in a weekend, callable by Claude, ChatGPT, LangChain, Haystack, LlamaIndex, and any other framework that consumes OpenAPI.

Why FastAPI + Vercel.

Why FastAPI over Flask, Django REST Framework, or Express

FastAPI wins on four counts specific to agent-facing APIs.

Why Vercel

Vercel's Fluid Compute model — the default for all new projects since April 23, 2025 — eliminates most cold-start concerns. The key facts: 99.37% of requests experience zero cold starts (Vercel, Fluid Compute). The Hobby tier ships with 1,000,000 invocations per month, 4 CPU-hours, 360 GB-hours of provisioned memory, and a 60-second maximum function duration.

What breaks on Vercel serverless

The eight endpoints that cover the full flow.

This is the minimum viable surface for an agent purchase: discovery, detail, availability, intent, rehydration, order status, and webhook push. Five are mandatory. Three (manifest, intent rehydration, webhooks) make the API resilient under real agent traffic. All eight fit in one app.py file.

Checkout Intent — request and response

The most agent-specific endpoint on the list. Three details below the JSON make this endpoint different from a browser cart.

// POST /cart/intent — Request
{
  "items": [
    {"sku": "WOOL-SOCK-RED-M", "quantity": 2}
  ],
  "customer_email": "agent-user@example.com",
  "idempotency_key": "agent-session-abc123-attempt-1"
}

// Response (201 Created)
{
  "intent_id": "intent_8j3kd9s2",
  "status": "pending",
  "items": [
    {"sku": "WOOL-SOCK-RED-M", "quantity": 2, "unit_price": 1999, "line_total": 3998}
  ],
  "subtotal": 3998,
  "currency": "USD",
  "checkout_url": "https://yourstore.com/checkout?token=8j3kd9s2",
  "expires_at": "2026-05-19T14:27:00Z"
}

Availability — response

{
  "sku": "WOOL-SOCK-RED-M",
  "available": true,
  "quantity": 47,
  "restock_eta": null,
  "checked_at": "2026-05-19T13:27:00Z"
}

The full code build.

Four code blocks below. Together they ship. No skeleton — the app.py is a complete FastAPI application you can copy into a fresh directory, install three dependencies, and deploy.

Project directory structure

project/
├─ app.py            ← FastAPI app instance
├─ requirements.txt
├─ vercel.json       ← optional; needed for maxDuration override
└─ README.md

app.py — the complete FastAPI application

"""
AgentMall Commerce API — minimal agent-ready surface.
Deploy to Vercel: a top-level `app` object in app.py is auto-detected.
OpenAPI is exposed automatically at /openapi.json — agents consume it.
"""
import os
import uuid
from datetime import datetime, timedelta, timezone
from typing import List, Optional, Literal

from fastapi import FastAPI, HTTPException, Header, Query
from pydantic import BaseModel, Field, EmailStr

app = FastAPI(
    title="AgentMall Commerce API",
    version="0.1.0",
    description="Agent-ready commerce surface — search, intent, order.",
)

# -----------------------------------------------------------------------------
# Environment
# -----------------------------------------------------------------------------
DATABASE_URL     = os.getenv("DATABASE_URL")
READ_API_KEY     = os.getenv("READ_API_KEY", "dev-read-key")
WRITE_API_KEY    = os.getenv("WRITE_API_KEY", "dev-write-key")
STRIPE_SECRET    = os.getenv("STRIPE_SECRET_KEY")
PUBLIC_BASE_URL  = os.getenv("PUBLIC_BASE_URL", "https://yourstore.com")

# -----------------------------------------------------------------------------
# Pydantic models — drive OpenAPI; agent frameworks read these.
# -----------------------------------------------------------------------------
class Product(BaseModel):
    sku: str = Field(..., description="Stable SKU; the agent's primary identifier.")
    title: str
    price: int = Field(..., description="Price in integer cents. $19.99 = 1999.")
    currency: str = Field("USD", description="ISO 4217 currency code.")
    available: bool
    quantity: int = 0
    url: str
    image_url: Optional[str] = None
    description: Optional[str] = None

class SearchResponse(BaseModel):
    items: List[Product]
    next_cursor: Optional[str] = None
    total_estimate: int

class AvailabilityResponse(BaseModel):
    sku: str
    available: bool
    quantity: int
    restock_eta: Optional[datetime] = None
    checked_at: datetime

class CartItemRequest(BaseModel):
    sku: str
    quantity: int = Field(..., ge=1, description="Whole units, at least one.")

class CartIntentRequest(BaseModel):
    items: List[CartItemRequest]
    customer_email: EmailStr
    idempotency_key: str = Field(
        ..., min_length=8,
        description="Agent-generated UUID per checkout attempt. Same key returns same intent_id.",
    )

class CartIntentLineItem(BaseModel):
    sku: str
    quantity: int
    unit_price: int
    line_total: int

class CartIntentResponse(BaseModel):
    intent_id: str
    status: Literal["pending", "ready", "expired", "consumed"]
    items: List[CartIntentLineItem]
    subtotal: int
    total_cents: int
    currency: str = "USD"
    checkout_url: str
    expires_at: datetime

class OrderResponse(BaseModel):
    order_id: str
    status: Literal["pending", "paid", "failed", "shipped"]
    fulfillment_status: Literal["unfulfilled", "in_transit", "delivered", "returned"]
    tracking: Optional[str] = None
    updated_at: datetime

class ApiError(BaseModel):
    code: str
    message: str
    retry_recommended: bool = False
    retry_after_seconds: Optional[int] = None
    details: Optional[dict] = None

# -----------------------------------------------------------------------------
# Auth — Bearer API key; static credentials for agent compatibility.
# -----------------------------------------------------------------------------
def require_read(authorization: Optional[str] = Header(None)) -> None:
    if not authorization or authorization != f"Bearer {READ_API_KEY}":
        raise HTTPException(status_code=401, detail="Invalid or missing API key.")

def require_write(authorization: Optional[str] = Header(None)) -> None:
    if not authorization or authorization != f"Bearer {WRITE_API_KEY}":
        raise HTTPException(status_code=401, detail="Invalid or missing write API key.")

# -----------------------------------------------------------------------------
# Tiny in-memory catalog — replace with your DB layer.
# -----------------------------------------------------------------------------
CATALOG = {
    "WOOL-SOCK-RED-M": Product(
        sku="WOOL-SOCK-RED-M",
        title="Merino Wool Socks — Red, Medium",
        price=1999,
        currency="USD",
        available=True,
        quantity=47,
        url=f"{PUBLIC_BASE_URL}/products/wool-sock-red-m",
        image_url=f"{PUBLIC_BASE_URL}/img/wool-sock-red-m.jpg",
        description="80% merino wool, mid-calf height, machine washable.",
    ),
}

INTENTS: dict = {}   # idempotency_key -> intent_id
INTENT_DB: dict = {} # intent_id -> CartIntentResponse

# -----------------------------------------------------------------------------
# Routes
# -----------------------------------------------------------------------------
@app.get("/catalog/manifest")
def catalog_manifest():
    """Discovery metadata. Agents read this first to build context."""
    return {
        "api_version": "0.1.0",
        "catalog_version": "2026-05-19",
        "endpoints": [
            "/products/search",
            "/products/{sku}",
            "/products/{sku}/availability",
            "/cart/intent",
            "/cart/intent/{intent_id}",
            "/orders/{order_id}",
        ],
        "auth": {"type": "api_key", "header": "Authorization: Bearer <key>"},
        "openapi_url": f"{PUBLIC_BASE_URL}/openapi.json",
    }

@app.get("/products/search", response_model=SearchResponse)
def products_search(
    q: Optional[str] = Query(None, description="Natural-language query."),
    category: Optional[str] = None,
    price_max: Optional[int] = Query(None, description="Max price in cents."),
    in_stock_only: bool = False,
    limit: int = Query(20, ge=1, le=100),
    cursor: Optional[str] = None,
    _: None = None,  # auth optional for search; require_read for private catalogs
):
    """Product discovery. Supports natural-language q and structured filters."""
    items = list(CATALOG.values())
    if in_stock_only:
        items = [p for p in items if p.available]
    if price_max is not None:
        items = [p for p in items if p.price <= price_max]
    if q:
        ql = q.lower()
        items = [p for p in items if ql in p.title.lower() or ql in (p.description or "").lower()]
    return SearchResponse(items=items[:limit], next_cursor=None, total_estimate=len(items))

@app.get("/products/{sku}", response_model=Product)
def products_detail(sku: str):
    """Full product detail. Price is integer cents."""
    product = CATALOG.get(sku)
    if not product:
        raise HTTPException(status_code=404, detail=f"SKU {sku} not found.")
    return product

@app.get("/products/{sku}/availability", response_model=AvailabilityResponse)
def products_availability(sku: str):
    """Live stock check. Call this before every checkout intent."""
    product = CATALOG.get(sku)
    if not product:
        raise HTTPException(status_code=404, detail=f"SKU {sku} not found.")
    return AvailabilityResponse(
        sku=product.sku,
        available=product.available,
        quantity=product.quantity,
        restock_eta=None,
        checked_at=datetime.now(timezone.utc),
    )

@app.post("/cart/intent", response_model=CartIntentResponse, status_code=201)
def cart_intent_create(req: CartIntentRequest):
    """
    Create a checkout intent. Idempotent on idempotency_key — the same key
    always returns the same intent_id. Re-validates inventory server-side.
    """
    # Idempotency — return existing intent if key has been seen.
    if req.idempotency_key in INTENTS:
        return INTENT_DB[INTENTS[req.idempotency_key]]

    line_items, subtotal = [], 0
    for item in req.items:
        product = CATALOG.get(item.sku)
        if not product:
            raise HTTPException(status_code=404, detail=f"SKU {item.sku} not found.")
        if not product.available or product.quantity < item.quantity:
            raise HTTPException(
                status_code=409,
                detail=f"SKU {item.sku} unavailable in requested quantity.",
            )
        line_total = product.price * item.quantity
        subtotal += line_total
        line_items.append(CartIntentLineItem(
            sku=item.sku, quantity=item.quantity,
            unit_price=product.price, line_total=line_total,
        ))

    intent_id = f"intent_{uuid.uuid4().hex[:10]}"
    intent = CartIntentResponse(
        intent_id=intent_id,
        status="pending",
        items=line_items,
        subtotal=subtotal,
        total_cents=subtotal,
        currency="USD",
        checkout_url=f"{PUBLIC_BASE_URL}/checkout?token={intent_id}",
        expires_at=datetime.now(timezone.utc) + timedelta(minutes=20),
    )
    INTENTS[req.idempotency_key] = intent_id
    INTENT_DB[intent_id] = intent
    return intent

@app.get("/cart/intent/{intent_id}", response_model=CartIntentResponse)
def cart_intent_get(intent_id: str):
    """Rehydrate intent state. Lets the agent resume after interruption."""
    intent = INTENT_DB.get(intent_id)
    if not intent:
        raise HTTPException(status_code=404, detail=f"Intent {intent_id} not found.")
    return intent

@app.get("/orders/{order_id}", response_model=OrderResponse)
def orders_get(order_id: str):
    """Post-purchase status. Status enum: pending, paid, failed, shipped."""
    # Replace with your real lookup.
    return OrderResponse(
        order_id=order_id,
        status="paid",
        fulfillment_status="in_transit",
        tracking="1Z999AA10123456784",
        updated_at=datetime.now(timezone.utc),
    )

@app.post("/webhooks/order-events", status_code=202)
def webhooks_order_events(payload: dict):
    """
    Push lifecycle updates. Verify signature against your provider
    (Stripe-Signature, Shopify HMAC, etc.) before trusting payload.
    """
    # signature_check(payload, request.headers)  # implement per provider
    return {"received": True}

requirements.txt

fastapi
uvicorn[standard]
pydantic

vercel.json — only for maxDuration override

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "rewrites": [
    { "source": "/(.*)", "destination": "/app.py" }
  ],
  "functions": {
    "app.py": {
      "maxDuration": 60
    }
  }
}

Environment variables — three patterns

import os

DATABASE_URL      = os.getenv("DATABASE_URL")
READ_API_KEY      = os.getenv("READ_API_KEY")
STRIPE_SECRET_KEY = os.getenv("STRIPE_SECRET_KEY")

Set these in Vercel Dashboard → Settings → Environment Variables. Changes apply to new deployments only — redeploy after you add them.

Authentication agents can actually use.

OAuth Authorization Code flow is the default human-facing pattern. It also breaks agents. Below is the auth choice by use case, followed by the reason OAuth fails and the V1 default that works.

Making your API discoverable.

Three surfaces every agent-ready API must publish. The first is free with FastAPI. The second is one line of code. The third is a static JSON file at a known path.

1 · /openapi.json — automatic

FastAPI generates this from your Pydantic models with zero configuration. LangChain, Haystack, LlamaIndex, and OpenAI function calling all consume this spec to build tool definitions at runtime. Describe your Pydantic models with docstrings — FastAPI includes them verbatim in the spec, and agent frameworks use them as tool descriptions.

2 · FastAPI-MCP — one line of code

FastAPI-MCP is an open-source library by Tadata Inc., released April 2025. It converts all FastAPI routes to MCP tools automatically — with zero configuration — preserving Pydantic schemas. Once deployed, Claude can call your endpoints natively over the Model Context Protocol.

from fastapi_mcp import FastApiMCP

mcp = FastApiMCP(app)        # `app` is your FastAPI instance
mcp.mount()                  # exposes the MCP transport on the same app

3 · /.well-known/agent.json — capability manifest

A lightweight static manifest at a known path, for any agent or service that does not consume OpenAPI directly. Serve it from your CDN or as a FastAPI route.

{
  "name": "Example Commerce API",
  "version": "0.1.0",
  "openapi_url": "https://example.com/openapi.json",
  "auth": {"type": "api_key"},
  "capabilities": [
    "search_products", "get_product", "check_availability",
    "create_checkout_intent", "get_order_status"
  ]
}

Agent framework consumption — what reads what

Deployment stack — what fits your traffic shape.

Vercel is the weekend default. The table below is the honest tradeoff matrix once you start measuring real agent latency.

Errors agents can actually use.

Errors must be self-describing enough that the agent can decide whether and how to retry without human intervention. Four things every error must communicate: what failed, whether it is permanent or retryable, which field or state caused it, and what to do next.

Recommended error response structure

{
  "error": {
    "code": "OUT_OF_STOCK",
    "message": "SKU WOOL-SOCK-RED-M has 0 units available. Restock expected 2026-05-25.",
    "retry_recommended": false,
    "retry_after_seconds": null,
    "details": {
      "sku": "WOOL-SOCK-RED-M",
      "requested_quantity": 2,
      "available_quantity": 0
    }
  }
}

HTTP status taxonomy — what the agent should do

Rate limit headers — what to send

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1716126000
Retry-After: 30   (429 responses only)

Agents parse these headers automatically. Recommended starting limits: 100 req/min for GET (read) endpoints, 20 req/min for POST (write) endpoints. If an agent makes more than 50 calls in a 60-second window it is likely in a retry loop — return 429 with Retry-After: 300.

Eight questions builders actually ask.