Agentic Commerce Spec

The open standard for measuring how AI shopping agents see your e-commerce catalog.

ChatGPT, Gemini, Claude, Perplexity, Mistral, Le Chat, and DeepSeek recommend products directly to buyers — and skip products they do not understand. Agentic Commerce Spec is the vendor-neutral methodology + reference implementation for measuring whether your products are AI-readable, with a per-dimension breakdown and statistically-validated impact predictions.

Build a Shopify app, a WooCommerce plugin, an internal data quality pipeline, or a SaaS dashboard — they should all agree on the score.

---

Why an open standard?

Every "AI catalog optimization" tool today computes a different score with a different methodology and exposes it through a different metafield namespace. Merchants cannot compare across tools, theme builders cannot read scores reliably, analytics platforms cannot aggregate across the ecosystem. Like SEO before schema.org.

This repo defines:

1. A scoring methodology — 8 dimensions (title, description, images, metadata, taxonomy, variants, reviews, structured data), explicit weights, deterministic computation. See METHODOLOGY.md.
2. A metafield schema — standardized namespace any app can write and any consumer can read. See SPEC.md.
3. A reference TypeScript implementation — runnable on any product JSON. See src/scorer.ts + test/vectors.json.
4. An ML uplift model — calibrated XGBoost per-vertical models that predict AI-traffic uplift from a fix, with held-out AUC ≥ 0.95.

The methodology was built scoring ~50,000 real Shopify products across 10 verticals and validated against ground-truth AI agent recommendations captured daily across 6 agents. Numbers are reproducible from the published artifacts.

---

License model

Dual-license, intentional:

• Specification, methodology, schema, benchmarks: CC0 1.0 — public domain. Reproduce, adopt, embed in platform docs with zero attribution required. The model that made schema.org universal.
• Reference implementation (src/) and ML models (models/): MIT-licensed. Use commercially, fork, redistribute.

CC0 on the spec = no friction for Shopify, BigCommerce, WooCommerce, Magento to ship this inside their official platform docs.

---

Quick start (TypeScript)

npm install @commerce-agentic/spec

import { scoreProduct } from "@commerce-agentic/spec";

const product = {
  title: "Allbirds Wool Runner Mizzles — Natural Black",
  description: "Waterproof wool sneakers built for the rain. ZQ-certified merino, repurposed castor bean oil sole, recycled polyester laces…",
  images: [{ alt: "Side view of Wool Runner Mizzle in Natural Black" }],
  variants: [{ sku: "WRM-NB-9", barcode: "0840028302194", price: "115.00" }],
  metafields: [
    { namespace: "google", key: "google_product_category", value: "Apparel & Accessories > Shoes > Sneakers" },
  ],
  productType: "Sneakers",
  vendor: "Allbirds",
  tags: ["waterproof", "sustainable", "wool"],
};

const result = scoreProduct(product);
// {
//   totalScore: 82,
//   grade: "A",
//   dimensions: { title: 18, description: 14, images: 9, ... },
//   issues: ["Missing JSON-LD product schema", ...],
//   aiVisibilityIndex: 0.78,
// }

Deterministic: same input always yields the same score. CI runs the test vectors on every commit.

---

What is in the box

File	Purpose
SPEC.md	Normative spec: 8 dimensions, weights, metafield schema, conformance levels
METHODOLOGY.md	Each dimension measurement rules with rationale
src/scorer.ts	Reference TypeScript implementation. ~400 LOC, no runtime deps
src/types.ts	Public types
test/vectors.json	Canonical test cases — any conforming impl must produce these scores
models/	Pre-trained XGBoost uplift models (global + per-vertical)
ADOPTERS.md	Apps and platforms shipping with the spec
CHANGELOG.md	Spec version history

---

How to adopt

Implement the spec in your app

1. Read SPEC.md for the metafield namespace.
2. Run scoreProduct() on each product.
3. Write the result into the standardized metafields.
4. Declare conformance: "Implements Agentic Commerce Spec v1.0".

Read scores in a Shopify theme

{% raw %}{% if product.metafields.agentic_commerce.score >= 80 %}
  <span class="badge badge-ai-ready">AI-Ready ⚡</span>
{% endif %}{% endraw %}

Use the ML uplift model

The model artifacts in models/ are MIT-licensed XGBoost JSON. Load them with any XGBoost-compatible runtime (Python, R, JS via xgboost-wasm) to predict AI-traffic uplift on your data.

---

Differentiator

Tool	Methodology	Schema	Reference impl	ML model
Agentic Commerce Spec	Open (CC0), 8 dimensions	Standardized	MIT TypeScript	MIT XGBoost (per-vertical)
Proprietary tool A	Closed	Vendor-specific	None	Closed
Proprietary tool B	Closed	Vendor-specific	None	None
Generic SEO tools	Not designed for AI agents	N/A	N/A	N/A

Switch vendors without breaking your theme, your apps, or your analytics. Vendors compete on better tooling around the same score, not on locking you in.

---

Status

• Spec v1.0 — Frozen for 12+ months. Backwards-compatible additions allowed; breaking changes need a major version bump and a migration guide.
• Reference TypeScript impl — production-ready, 3500+ test vectors passing.
• ML uplift models — global v1.0 (AUC 0.954), per-vertical v1.0 for 10 verticals (apparel, beauty, home, electronics, fitness, food, pets, baby, outdoor, gifts).
• Adopting apps — see ADOPTERS.md. First reference adopter: AI Catalog Score on the Shopify App Store.

---

Ecosystem

The commerce-agentic GitHub org maintains a complete agentic commerce stack:

Repo	Purpose
agentic-commerce-spec	This repo. Normative spec + reference impl.
agentic-commerce-skills	60+ AI agent skills for catalog optimization. Drop-in for Claude Code, Cursor, Cline, Copilot, Gemini CLI.
agentic-commerce-routines	Scheduled routines: daily audit, weekly visibility reports, monthly causal experiments.
agentic-commerce-tools	CLI + SDK for the spec.
agentic-commerce-benchmarks	Open dataset of cross-agent shopping recommendations.

---

Contributing

See CONTRIBUTING.md. PRs welcome on:

• Additional verticals for the per-vertical ML models
• Localized scoring (bilingual + RTL support)
• Reference implementations in other languages (Python, Ruby, PHP, Go)
• Test vectors covering edge cases
• Examples and tutorials

We do not accept PRs that change methodology weights or dimension definitions without an RFC discussion — those affect every existing implementation.

---

FAQ

Q: Why open-source the methodology if there is a commercial app behind it? A closed scoring tool can never become a standard. Without a standard, every merchant has to migrate scores when they switch vendors. The commercial value is in the tooling around the score (audits, auto-fixes, causal A/B testing, performance pricing) — not in locking you into a proprietary number. This pattern made schema.org universal.

Q: How is this different from SEO scoring tools? SEO is for search engine crawlers. Agentic Commerce Spec is for AI agents that recommend products directly to buyers — ChatGPT shopping, Gemini, Perplexity, Mistral, DeepSeek. They use product structure very differently than a search engine ranks pages.

Q: Can I run the scorer offline? Yes — src/scorer.ts is pure TypeScript, no network calls, no telemetry. Run it locally, in your CI, on a Cloudflare Worker, anywhere.

Q: I found a bug. Open an issue with a failing test vector. We add it to the canonical test suite and fix in the next release.

Q: Will the spec change? v1.x is stable. Breaking changes go in v2.0 (no plans).

---

Maintained by the commerce-agentic GitHub organization. Governance is open: any organization shipping a conforming implementation gets an ADOPTERS.md row and a seat at the spec discussions.