deerso Developer API

Quick Start

Three steps to your first API call. No API key required for read-only endpoints.

curl "https://api.deerso.com/v1/products?q=deck+screws&per_page=3"

curl "https://api.deerso.com/v1/pricing/ABC123"

curl -X POST "https://api.deerso.com/v1/register" \
  -H "Content-Type: application/json" \
  -d '{"business_name":"Acme","contact_name":"Jane","email":"[email protected]"}'

REST API Reference

Base URL: https://api.deerso.com — All read endpoints are public. Write operations require an API key.

Add ?format=ai to any product/pricing/inventory endpoint for AI-friendly response formatting.

curl "https://api.deerso.com/v1/products?q=drill+bit&brand=DeWalt&per_page=5"

# Response (truncated):
{
  "data": [
    {
      "sku": "DW1361",
      "title": "DeWalt DW1361 Titanium Drill Bit Set",
      "brand": "DeWalt",
      "price": 29.97,
      "in_stock": true
    }
  ],
  "pagination": { "page": 1, "per_page": 5, "total": 42 }
}

curl "https://api.deerso.com/v1/pricing/DW1361?market_context=%7B%22other_prices%22%3A%5B%7B%22source%22%3A%22HomeDepot%22%2C%22price%22%3A34.97%7D%5D%7D"

# Response:
{
  "sku": "DW1361",
  "price": 29.97,
  "currency": "USD",
  "comparison": {
    "cheapest": true,
    "savings_vs_best_competitor": 5.00,
    "competitors": [
      { "source": "HomeDepot", "price": 34.97, "difference": -5.00 }
    ]
  }
}

MCP Server

Connect Claude, ChatGPT, or any MCP-compatible AI assistant directly to the deerso catalog. Supports both stdio and streamable HTTP transports.

{
  "mcpServers": {
    "deerso": {
      "url": "https://api.deerso.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "deerso": {
      "command": "node",
      "args": ["./api/dist/mcp/server.js", "--stdio"]
    }
  }
}

Available Tools

deerso://catalog/categories   — Full category hierarchy
deerso://catalog/brands       — All available brands
deerso://info/shipping        — Shipping methods & delivery estimates
deerso://info/policies        — Wholesale pricing & return policies

MCP Setup Tutorial

Follow these steps to connect your AI assistant to deerso's product catalog, pricing, and inventory in under 2 minutes.

{
  "mcpServers": {
    "deerso": {
      "type": "url",
      "url": "https://api.deerso.com/mcp"
    }
  }
}

curl -X POST https://api.deerso.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0.0"}
    }
  }'

# Expected response:
# {"result":{"protocolVersion":"2025-03-26",
#   "capabilities":{"tools":{"listChanged":true},"resources":{"listChanged":true}},
#   "serverInfo":{"name":"deerso","version":"1.0.0"}}}

ACP Checkout (Agentic Commerce Protocol)

ACP lets AI agents create and complete purchases on behalf of users. The flow is: create session → update buyer/shipping → process payment.

# 1. Create checkout session
curl -X POST "https://api.deerso.com/checkouts" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{"sku": "DW1361", "quantity": 2}],
    "buyer": {"name": "Jane Doe", "email": "[email protected]"}
  }'

# 2. Update shipping address
curl -X PUT "https://api.deerso.com/checkouts/SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "fulfillment_address": {
      "line1": "123 Main St",
      "city": "Portland",
      "state": "OR",
      "postal_code": "97201"
    }
  }'

# 3. Complete payment
curl -X POST "https://api.deerso.com/checkouts/SESSION_ID/complete" \
  -H "Content-Type: application/json" \
  -d '{"payment": {"token": "spt_...", "provider": "stripe"}}'

UCP Discovery

The Universal Commerce Protocol (UCP) endpoint lets AI platforms like Google AI Mode automatically discover deerso's capabilities. No integration work needed — AI crawlers find us at a well-known URL.

curl "https://api.deerso.com/.well-known/ucp"

# Returns capabilities manifest:
{
  "name": "deerso",
  "description": "Wholesale hardware retailer",
  "capabilities": ["product_search", "pricing", "inventory", "checkout"],
  "bindings": {
    "rest": "https://api.deerso.com/v1",
    "mcp": "https://api.deerso.com/mcp"
  },
  "registration": "https://api.deerso.com/v1/register"
}

Competitive Intelligence

Pass competitor prices via the market_context parameter on pricing endpoints or the check_price MCP tool. We'll return a comparison showing where deerso stands.

GET /v1/pricing/DW1361?market_context={
  "other_prices": [
    {"source": "HomeDepot", "price": 34.97},
    {"source": "Lowes", "price": 32.99}
  ],
  "project_type": "deck_build"
}

check_price({
  sku: "DW1361",
  quantity: 5,
  market_context: {
    other_prices: [
      { source: "HomeDepot", price: 34.97 }
    ],
    project_type: "deck_build"
  }
})

Authentication & Rate Limits

# Register
curl -X POST "https://api.deerso.com/v1/register" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Hardware",
    "contact_name": "Jane Doe",
    "email": "[email protected]"
  }'

# Use your key
curl "https://api.deerso.com/v1/account" \
  -H "Authorization: Bearer YOUR_API_KEY"

Protocol Support