Agent Commerce API

The PriceLists Commerce API enables AI agents (such as Claude Code with OpenClaw) to search product offers worldwide, compare prices, get quotes, and orchestrate purchases programmatically.

Overview

The API provides five endpoints for the full commerce lifecycle:

Authentication

The API uses a three-tier access model:

• Public (no auth): /search and /register — any agent can search products and self-register without a token.
• Authenticated (Bearer token): /quote, /execute, and /orders — require a Bearer token in the Authorization header.

Authorization: Bearer plk_your_api_key_here

To obtain an API key, call the /register endpoint below. Keys are issued instantly — no approval required.

Registration

Agents can self-register to obtain an API key instantly. No approval or manual setup needed.

POST /api/agent/v1/register

// Request
{
  "name": "MyBot v1.0"
}

// Response (201 Created)
{
  "apiKey": "plk_a1b2c3d4e5f6...",
  "keyPrefix": "plk_a1b2",
  "name": "MyBot v1.0",
  "rateLimit": 60,
  "message": "Store this API key securely. It will not be shown again."
}

API Endpoints

POST /api/agent/v1/search

Search for product offers by text query or product identifiers.

Request Body

{
  "query": "iPhone 15 Pro 256GB",
  "identifiers": {
    "gtin": ["194253938996"],
    "ean": [],
    "mpn": []
  },
  "limit": 10,
  "currency": "USD",
  "locale": "en-US",
  "shipTo": {
    "country": "PL",
    "postalCode": "00-001"
  },
  "rankings": ["cheapest", "best"],
  "bestWeights": {
    "sellerCredibility": 0.80,
    "price": 0.15,
    "deliverySpeed": 0.05
  },
  "filters": {
    "availability": "in_stock_only"
  }
}

Response

{
  "requestId": "req_abc-123",
  "rankings": {
    "cheapest": {
      "offers": [
        {
          "offerId": "of_12345",
          "product": {
            "id": "prod_678",
            "title": "iPhone 15 Pro 256GB",
            "identifiers": { "gtin": ["194253938996"], "ean": [], "mpn": [] },
            "imageUrl": "https://..."
          },
          "merchant": {
            "id": "m_99",
            "name": "TechStore",
            "country": "PL",
            "credibilityScore": 85,
            "website": "https://techstore.pl"
          },
          "pricing": {
            "currency": "USD",
            "itemPrice": 999.99
          },
          "availability": { "status": "in_stock", "quantity": 5 },
          "delivery": { "minDays": 2, "maxDays": 5 },
          "execution": { "mode": "checkout_url" },
          "links": { "offerUrl": "https://...", "checkoutUrl": "https://..." },
          "scores": { "bestScore": 0.72 }
        }
      ],
      "nextCursor": null
    },
    "best": { "offers": [...], "nextCursor": null }
  }
}

POST /api/agent/v1/quote

Create a time-limited quote to lock in pricing before execution.

// Request
{
  "offerId": "of_12345",
  "quantity": 1,
  "currency": "USD",
  "shipTo": { "country": "PL", "postalCode": "00-001" }
}

// Response
{
  "quoteId": "qt_abc-def-123",
  "expiresAt": "2026-02-10T12:15:00+00:00",
  "offer": { ... },
  "final": {
    "currency": "USD",
    "items": 999.99,
    "shipping": 0.0,
    "grandTotal": 999.99
  },
  "execution": {
    "supported": false,
    "mode": "checkout_url",
    "fallbackCheckoutUrl": "https://techstore.pl/product/123"
  }
}

POST /api/agent/v1/execute

Execute a purchase. Requires Idempotency-Key header and confirm: true.

// Headers
Authorization: Bearer plk_...
Idempotency-Key: unique-request-id-123

// Request
{
  "quoteId": "qt_abc-def-123",
  "confirm": true,
  "preference": "api_first"
}

// Response (when merchant API is not supported)
{
  "ok": false,
  "status": "not_supported",
  "orderId": "ord_xyz-789",
  "fallback": {
    "type": "checkout_url",
    "url": "https://techstore.pl/product/123"
  }
}

GET /api/agent/v1/orders/{orderId}

Poll order status after execution.

{
  "orderId": "ord_xyz-789",
  "status": "not_supported",
  "executionMode": "manual",
  "checkoutUrl": "https://techstore.pl/product/123",
  "receipt": { "currency": "USD", "total": 999.99 }
}

Ranking Modes

Submissions (Entity + Product Listing)

Agents can submit new companies (entities) and their product offers for inclusion in the PriceLists database. Submissions go through a moderation workflow before products become searchable.

POST /api/agent/v1/submit

Submit a pricelist with company info and product items. Requires Bearer token and at least one item.

// Request
{
  "company_name": "TechStore Poland",
  "company_website": "https://techstore.pl",
  "company_email": "[email protected]",
  "company_phone": "+48 123 456 789",
  "company_region": "EU",
  "items": [
    {
      "title": "iPhone 15 Pro 256GB",
      "gtin": "194253938996",
      "brand": "Apple",
      "price": 4999.00,
      "currency": "PLN",
      "in_stock": true,
      "stock_quantity": 25,
      "condition": "new",
      "link": "https://techstore.pl/iphone-15-pro",
      "image_link": "https://techstore.pl/img/iphone15pro.jpg"
    }
  ]
}

// Response (201 Created)
{
  "submissionId": 42,
  "status": "submitted",
  "itemCount": 1,
  "message": "Submission received and queued for review."
}

Each item accepts: title (required), gtin, mpn, brand, upc, sku, description, image_link, link, price, currency (3-letter ISO), in_stock, stock_quantity, condition (new/used/refurbished).

GET /api/agent/v1/submissions/{id}

Check submission status. Only the submitting agent can view their own submissions.

{
  "submissionId": 42,
  "status": "approved",
  "companyName": "TechStore Poland",
  "itemCount": 1,
  "reviewNotes": "Approved. Products will be visible after processing.",
  "reviewedAt": "2026-02-10T14:30:00+00:00",
  "createdAt": "2026-02-10T12:00:00+00:00",
  "items": [
    {
      "id": 101,
      "title": "iPhone 15 Pro 256GB",
      "gtin": "194253938996",
      "mpn": null,
      "brand": "Apple",
      "price": 4999.00,
      "currency": "PLN",
      "itemStatus": "approved",
      "itemNotes": null
    }
  ]
}

Install OpenClaw Skill

To use this API with an OpenClaw-compatible agent:

1. Install the plugin locally:

   openclaw plugins install -l /path/to/pricelists-commerce-openclaw

2. Register via the API (POST /api/agent/v1/register) or set an existing key in the PRICELISTS_AGENT_API_KEY environment variable
3. Add plugin config to ~/.openclaw/openclaw.json:

   {
     "plugins": {
       "entries": {
         "pricelists-commerce": {
           "enabled": true,
           "config": {
             "baseUrl": "https://pricelists.org/api/agent",
             "apiKey": "${PRICELISTS_AGENT_API_KEY}",
             "timeoutMs": 12000,
             "defaults": {
               "currency": "USD",
               "locale": "en-US",
               "shipTo": { "country": "PL", "postalCode": "00-001" }
             }
           }
         }
       }
     }
   }

4. Restart the gateway and start a new session

The skill provides four tools: plc_search, plc_quote, plc_execute (optional, side-effect), and plc_order_get.

Error Codes

Security Model

• The API never asks for or stores raw card numbers, CVV, or OTP codes.
• Purchase execution is API-first with merchant adapters. When a merchant does not support API execution, the agent receives a checkout_url for the user to complete manually.
• The /execute endpoint requires explicit confirm: true and an Idempotency-Key header to prevent duplicate purchases.
• All API keys are hashed (SHA-256) — plaintext keys are shown only once at creation time.
• Rate limiting: 30 req/min for public search (per IP), 5 req/min for registration (per IP), 60 req/min for authenticated endpoints (per API key).