Protocol Specification

npm install @opencommerceprotocol/spec

import { OCPManifest, OCPProduct, OCP_VERSION } from '@opencommerceprotocol/spec';

{
  "version": "1.0",
  "merchant": {
    "name": "My Store",
    "url": "https://mystore.com",
    "currency": "USD",
    "locale": "en",
    "logo": "https://mystore.com/logo.png",
    "description": "Quality products for everyone",
    "contact": "support@mystore.com"
  },
  "capabilities": {
    "catalog": true,
    "search": true,
    "cart": true,
    "checkout": "redirect",
    "orders": false,
    "returns": false
  },
  "discovery": {
    "feed": "https://mystore.com/ocp/products.jsonl",
    "feed_format": "jsonl",
    "feed_updated": "2026-03-01T00:00:00Z",
    "total_products": 500
  },
  "interact": {
    "runtime": "https://cdn.opencommerceprotocol.org/runtime/v1/ocp-runtime.min.js",
    "webmcp": true,
    "tools": ["search_products", "get_product", "add_to_cart", "begin_checkout"]
  },
  "bridge": {
    "mcp": "https://mystore.com/mcp",
    "ucp": "https://mystore.com/.well-known/ucp",
    "acp": "https://mystore.com/acp",
    "a2a": "https://mystore.com/.well-known/agent.json"
  },
  "payments": {
    "handlers": ["card", "paypal", "apple_pay"],
    "currencies": ["USD", "EUR"]
  },
  "permissions": {
    "requires_human_checkout": true,
    "agent_purchase_limit": 500,
    "rate_limit": "100/hour"
  },
  "shipping": {
    "regions": ["US", "CA", "GB"],
    "methods": ["standard", "express", "overnight"],
    "free_above": 50
  }
}

{"id":"prod-001","name":"Premium Wireless Headphones","price":149.99,"currency":"USD","url":"https://mystore.com/products/headphones","availability":"in_stock","description":"Studio-quality sound with active noise cancellation.","image":"https://mystore.com/images/headphones.jpg","category":"Electronics","agent_notes":"Best-seller. Ideal for frequent flyers and open-plan offices. 30-hour battery.","variants":[{"id":"var-black","name":"Black","price":149.99,"availability":"in_stock"},{"id":"var-white","name":"White","price":149.99,"availability":"limited"}]}
{"id":"prod-002","name":"USB-C Hub","price":49.99,"currency":"USD","url":"https://mystore.com/products/usb-hub","availability":"in_stock","category":"Electronics","agent_notes":"7-in-1. Works with all USB-C laptops. HDMI 4K@60Hz."}

import type { OCPHandlers } from '@opencommerceprotocol/spec';

const handlers: Partial<OCPHandlers> = {
  search_products: async ({ query, category, min_price, max_price, in_stock, limit, offset, sort }) => {
    // Returns: ProductResult[]
  },
  get_product: async ({ id }) => {
    // Returns: OCPProduct
  },
  get_product_qa: async ({ id, question }) => {
    // Returns: QAResult { answer, confidence?, sources? }
  },
  compare_products: async ({ ids, attributes }) => {
    // Returns: ComparisonResult { products, comparison?, spec_matrix?, recommendation? }
  },
  add_to_cart: async ({ product_id, quantity, variant_id, agent_context }) => {
    // Returns: CartResult { success, cart, message? }
  },
  get_cart: async () => {
    // Returns: Cart { items, total, currency, session_id? }
  },
  update_cart: async ({ items }) => {
    // Returns: Cart
  },
  begin_checkout: async ({ prefill, callback_url, agent_context }) => {
    // Returns: CheckoutResult { checkout_url, session_id, expires_at?, ... }
  },
  check_availability: async ({ id, location, quantity }) => {
    // Returns: AvailabilityResult { availability, in_stock, quantity?, ... }
  },
  check_checkout_status: async ({ session_id }) => {
    // Returns: CheckoutStatusResult { session_id, status, order_id?, message?, ... }
  },
  get_promotions: async ({ product_id, category }) => {
    // Returns: PromotionsResult { promotions: Promotion[] }
  },
};

import type { AgentContext } from '@opencommerceprotocol/spec';

const agentContext: AgentContext = {
  agent_id: 'chatgpt-shopping',
  session_ref: 'sess-abc123',
  buyer_preferences: {
    locale: 'en-US',
    shipping_country: 'US',
    size: 'M',
    color: 'blue',
    loyalty_ids: [{ program: 'store-rewards', member_id: 'MBR-001' }],
  },
};

import type { CheckoutPrefill, CheckoutResult } from '@opencommerceprotocol/spec';

const prefill: CheckoutPrefill = {
  email: 'buyer@example.com',
  name: 'Jane Doe',
  shipping_address: {
    line1: '123 Main St',
    city: 'Austin',
    postal_code: '78701',
    country: 'US',
  },
  payment_method_hint: 'apple_pay',
};

// CheckoutResult returned by begin_checkout:
// {
//   checkout_url: string;
//   session_id: string;
//   expires_at?: string;
//   prefilled_fields?: string[];
//   checkout_type?: 'full_page' | 'embedded' | 'api';
//   status_url?: string;
//   estimated_total?: { subtotal, tax?, shipping?, total, currency };
// }

import {
  OCP_VERSION,           // '1.0'
  OCP_MANIFEST_PATH,     // '/.well-known/ocp.json'
  OCP_FEED_PATH,         // '/ocp/products.jsonl'
  OCP_DOC_PATH,          // '/ocp.md'
  OCP_TOOL_DESCRIPTIONS, // Record<string, string> — descriptions for all 11 tools
  OCP_TOOL_NAMES,        // string[] — all 11 tool names
} from '@opencommerceprotocol/spec';

import { manifestSchema, productSchema } from '@opencommerceprotocol/spec';
import Ajv from 'ajv';

const ajv = new Ajv();
const validate = ajv.compile(manifestSchema);
const valid = validate(myManifest);

if (!valid) {
  console.error(validate.errors);
}