Developer API

The Pricelists.org API lets you search product offers worldwide, compare prices, get quotes and execute purchases programmatically — including for AI agents (such as Claude Code with OpenClaw).

Quickstart — search offers

Search products and offers across 31M prices. Results include price, delivery cost, availability and the last update time.

Example request

GET https://api.pricelists.org/v2/search
  ?query=Samsung+Galaxy+S25+Ultra
  &country=PL
  &limit=10

Example response

{
  "query": "Samsung Galaxy S25 Ultra",
  "count": 8,
  "offers": [
    {
      "shop": "Media Expert",
      "price": 5199.00,
      "delivery": 0.00,
      "currency": "PLN",
      "available": true,
      "updated_at": "2026-07-22T09:41:00Z"
    }
  ]
}

Free plan: 1,000 requests / month. Authenticate with the X-Api-Key header.

Overview

The agent commerce API covers the full lifecycle through seven endpoints. A machine-readable contract is available as OpenAPI 3.1, with condensed references at llms.txt and llms-full.txt.

Authentication

The API uses a three-tier access model:

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

Authorization: Bearer plk_your_api_key_here

Registration

Agents can self-register to obtain an API key instantly. No approval 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.

{
  "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" }
}

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",
  "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. Submissions go through a moderation workflow before products become searchable.

POST /api/agent/v1/submit

{
  "company_name": "TechStore Poland",
  "company_website": "https://techstore.pl",
  "items": [
    { "title": "iPhone 15 Pro 256GB", "gtin": "194253938996", "brand": "Apple",
      "price": 4999.00, "currency": "PLN", "in_stock": true, "condition": "new",
      "link": "https://techstore.pl/iphone-15-pro" }
  ]
}

// Response (201 Created)
{ "submissionId": 42, "status": "submitted", "itemCount": 1 }

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

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

Install OpenClaw Skill

To use this API with an OpenClaw-compatible agent:

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

Set your key in the PRICELISTS_AGENT_API_KEY variable and add plugin config to ~/.openclaw/openclaw.json. The skill provides six tools: plc_search, plc_quote, plc_execute, plc_order_get, plc_submit, plc_submission_status.

Error Codes

Public Read API (no key required)

A public read API exposes catalog data for lookups, comparisons and price history. No authentication, every response is ETag-cached, and only merchant-confirmed offers are returned. 60 requests/min per IP.

Security Model

• The API never asks for or stores raw card numbers, CVV, or OTP codes.
• Purchase execution is API-first; when a merchant does not support API execution, the agent receives a checkout_url.
• /execute requires explicit confirm: true and an Idempotency-Key.
• All API keys are hashed (SHA-256) — plaintext keys are shown only once.