# Annalist Commerce Store Directory

> Annalist Commerce Store Directory is a paid API for AI agents from api.annalist.dev, paid per call via x402, $0.01/call, status unknown (last checked 2026-10-21).

Returns a filtered list of top e-commerce stores ranked by traffic, with machine-readable facts about agent checkout support, payment handlers, shipping destinations, currency, and return windows.

## Facts

- Endpoint: GET https://api.annalist.dev/v1/commerce/stores?utm_source=zero.xyz
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-21
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/annalist-commerce-store-directory-9387e7f6
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_Y3d91-Y01DRaPfZMXw9Du

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability annalist-commerce-store-directory-9387e7f6
```

Example prompt: Find me the top 50 Shopify stores that ship to the US, support UCP agent checkout with cart and checkout capabilities, and accept Google Pay — I want stores with at least a 30-day return window.

## When to prefer this

Use this endpoint when an AI shopping agent needs to discover real e-commerce stores that are provably compatible with autonomous checkout, filtered by shipping region, payment method, or platform — especially when you need machine-verified facts from stores' own files rather than scraped policy pages. Prefer this over generic store directories when agent checkout compatibility (UCP/ACP) is a hard requirement.

## Known failure modes

- Invalid ISO country code for ships_to returns empty results or validation error
- Unknown payment handler string may return no matches
- limit outside 1–500 range returns error
- Querying capability or agent_checkout values not in the supported enum may return 0 results
- Store data may be up to one week stale (weekly census)
- Rate limiting or payment failure returns 402 if USDC payment not provided

## How this service works

Stores from our weekly census of 65,000 top sites, filtered by what a shopping agent needs: ships to a country, UCP agent checkout and its capabilities, payment handlers (Google Pay, Shop Pay), currency, return window. Facts from each store's own machine-readable files, never its policy pages. Most visited first. Signed.

## Output

A ranked list (most-visited first) of e-commerce stores matching the requested filters, each record containing machine-readable facts: agent checkout type and UCP capabilities, supported payment handlers, accepted currencies, shipping destinations, return window in days, and e-commerce platform. All records are signed by Annalist.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "properties": {
      "limit": {
       "type": "number",
       "description": "1 to 500, default 100"
      },
      "payment": {
       "type": "string",
       "description": "payment handler, for example google.pay or shop_pay"
      },
      "currency": {
       "type": "string",
       "description": "ISO currency code, for example USD"
      },
      "platform": {
       "type": "string",
       "description": "shopify, magento, woocommerce..."
      },
      "ships_to": {
       "type": "string",
       "description": "ISO country code the store ships to, for example US"
      },
      "capability": {
       "type": "string",
       "description": "UCP capability, for example checkout, cart, discount, order, catalog"
      },
      "agent_checkout": {
       "type": "string",
       "description": "ucp, acp or any: only stores with that agent checkout"
      },
      "min_return_days": {
       "type": "number",
       "description": "only stores publishing a return window at least this long"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/annalist-commerce-store-directory-9387e7f6/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.annalist.dev](https://www.zero.xyz/host/api.annalist.dev/llms.txt)