Documentation

Everything you need to make your store agent-ready.

Quick Start — 5 minutes

Create your OCP manifest

Create .well-known/ocp.json at the root of your website:

.well-known/ocp.json

{
  "version": "1.0",
  "merchant": {
    "name": "My Store",
    "url": "https://mystore.com",
    "currency": "USD"
  },
  "capabilities": {
    "catalog": true,
    "search": true
  },
  "discovery": {
    "feed": "https://mystore.com/ocp/products.jsonl",
    "feed_format": "jsonl",
    "total_products": 100
  },
  "permissions": {
    "requires_human_checkout": true
  }
}

Write your protocol description

Create /ocp.md — a natural language description of your store for AI agents:

ocp.md

# My Store — Open Commerce Protocol

## About
We sell premium widgets in 3 categories: Standard, Pro, and Kits.
Prices range from $29 to $500. We ship worldwide.

## Products
- Standard Widget ($29.99) — Everyday use, ships same day
- Pro Widget ($79.99) — Heavy use, 2-year warranty
- Starter Kit ($49.99) — Best for beginners

## Policies
- 30-day returns
- Free shipping over $50
- All prices in USD

Generate your product feed

Create /ocp/products.jsonl — one JSON product per line:

ocp/products.jsonl

{"id":"widget-1","name":"Standard Widget","price":29.99,"currency":"USD","url":"https://mystore.com/p/widget-1","in_stock":true,"agent_notes":"Runs true to size. Best for casual use."}
{"id":"widget-2","name":"Pro Widget","price":79.99,"currency":"USD","url":"https://mystore.com/p/widget-2","in_stock":true,"agent_notes":"For heavy use 8+ hours/day. Includes 2-year warranty."}

Verify with the CLI

npx @opencommerceprotocol/cli validate https://mystore.com

✓ /.well-known/ocp.json — valid
✓ /ocp.md — found
✓ /ocp/products.jsonl — 2 products, all valid
Score: 80/100

Manifest Reference

The manifest at /.well-known/ocp.json declares your store's identity, capabilities, and configuration.

versionstringrequiredProtocol version. Always "1.0".

merchant.namestringrequiredStore display name.

merchant.urlURIrequiredCanonical store URL.

merchant.currencystringISO 4217 currency code (e.g. "USD").

capabilities.catalogbooleanWhether catalog/product listing is available.

capabilities.searchbooleanWhether full-text product search is available.

capabilities.cartbooleanWhether cart add/update/get is supported.

capabilities.checkout"full"|"redirect"|"escalate"|"none"Checkout mode. Default: "none".

discovery.feedURIURL to JSONL product feed.

discovery.total_productsintegerCount of products in the feed.

permissions.requires_human_checkoutbooleanWhether human must confirm checkout. Default: true.

permissions.agent_purchase_limitnumberMax cart value agents can create (0 = no limit).

permissions.rate_limitstringRate limit string, e.g. "60/minute".

permissions.accepted_agent_context_fieldsstring[]Which AgentContext fields the merchant accepts.

shipping.regionsstring[]ISO country codes the merchant ships to.

shipping.methodsstring[]Shipping methods offered (standard, express, overnight).

shipping.free_abovenumberOrder value above which shipping is free.

Product Feed Specification

The product feed is a JSONL file (one JSON object per line) at the URL specified in discovery.feed. Each line represents one product.

agent_notes is the most valuable field — write it in natural language for LLMs. Include sizing info, compatibility notes, purchase advice, common questions, and use cases.

{
  "id": "prod-123",           // required — unique identifier
  "name": "Blue Widget",      // required — product name (max 200 chars)
  "price": 29.99,             // required — numeric price
  "currency": "USD",          // required — ISO 4217 code
  "url": "https://...",       // required — product page URL
  "description": "...",       // optional — may contain HTML
  "image": "https://...",     // optional — primary image URL
  "in_stock": true,           // optional — availability flag
  "category": "Widgets",      // optional — primary category
  "sku": "WGT-001",          // optional — stock keeping unit
  "brand": "Acme",            // optional — brand/manufacturer
  "variants": [...],          // optional — size/color variants
  "agent_notes": "...",       // optional — natural language for AI
  "updated_at": "2026-01-01T00:00:00Z",  // optional — ISO 8601

  // B2B / Structured Specs (optional)
  "specs": [{"name": "Weight", "value": 250, "unit": "g"}],
  "certifications": [{"name": "ISO 9001", "body": "ISO"}],
  "minimum_order_quantity": 100,
  "lead_time_days": 14,
  "bulk_pricing": [{"min_quantity": 100, "price": 4.50}],

  // Price Intelligence (optional)
  "price_guarantee": {"type": "lowest_30d"},
  "promotions": [{"description": "20% off", "discount_type": "percentage", "discount_value": 20}],
  "price_per_unit": {"amount": 2.99, "unit": "kg"}
}