Agentic Commerce Standard — Metadata, Scoring & Rating Framework

What This Document Is

This is the canonical definition of two proposed open standards for agentic commerce:

1. 01The Agentic Procurement Metadata Standard — a structured metadata format that tells AI shopping agents everything they need to know about a merchant: what they sell, how to find products, how to check out, what payment and shipping options exist, and how to interact programmatically.

1. 01The ASX Score & AXS Rating System — a measurement framework for evaluating how well any online store supports AI shopping agents, combining automated scan-based scoring with crowd-sourced real-world feedback.

These standards are vendor-neutral and platform-agnostic. Any company, agent developer, or merchant can adopt them. CreditClaw's implementation of these standards (products, services, go-to-market) is described separately in creditclaw-agentic-commerce-strategy.md.

Why These Standards Are Needed

AI shopping agents are emerging from every major platform — ChatGPT (Operator), Claude (MCP), Gemini (UCP/AI Mode), and custom procurement bots. But the infrastructure for agents to actually shop online is fragmented:

• →Existing metadata standards (Open Graph, Schema.org, Google Product Taxonomy) describe what products are — but not how an agent should navigate the store, handle checkout, or interact with shipping, payment, and loyalty options.
• →Shopify built MCP into every Shopify store — but only Shopify stores benefit.
• →Google launched UCP — but it's restricted-access and requires direct merchant integration.
• →No one is measuring how well a store actually works for AI agents.
• →No one has proposed a standard for the agentic procurement metadata that agents need beyond basic product discovery.

These two standards fill those gaps.

Part 1: Agentic Procurement Metadata Standard

Overview

The Agentic Procurement Metadata Standard defines a structured set of fields that describe a merchant's capabilities from the perspective of an AI shopping agent. It answers the questions an agent needs answered before it starts shopping:

• →What does this merchant sell, and in what categories?
• →How can I search for products — API, MCP, site search, CLI?
• →What's the checkout flow — guest or registered? How many steps?
• →What payment methods are accepted? What agentic payment protocols are supported?
• →What shipping options exist? What are the delivery timeframes?
• →Is there a loyalty program? Do agent-initiated purchases earn points?
• →How reliable is this store for agent transactions? What's the score?

Relationship to Existing Standards

The Agentic Procurement Metadata Standard extends the skills.sh SKILL.md format with commerce-specific fields. A valid agentic commerce SKILL.md is also a valid skills.sh SKILL.md — agents that support the base format can load it without modification.

File Format

The standard uses YAML frontmatter inside a Markdown file (.md), following the SKILL.md convention established by Vercel's skills.sh.

The commerce-specific metadata lives inside the metadata map — which skills.sh already supports as arbitrary key-value pairs — so there's no format conflict.

Full Frontmatter Schema

---
name: amazon-procurement
description: >
  Search and purchase products on Amazon.com. Use when the user needs to find
  products, compare prices, add items to cart, or complete checkout on Amazon.
  Supports search by keyword, category, UPC, and ASIN.
license: MIT
compatibility: "Requires API key for gateway access. Direct access requires vendor API credentials."
metadata:
  # === Identity ===
  vendor: amazon
  domain: amazon.com
  display_name: Amazon
  logo_url: https://cdn.example.com/brands/amazon/logo.png

  # === Taxonomy ===
  brand_type: mega_merchant    # brand | retailer | independent | chain | marketplace | department_store | supermarket | mega_merchant
  sector: multi-sector         # mega_merchant → multi-sector (set programmatically)
  tier: mid_range
  categories:
    - id: 222
      name: Electronics
      path: "Electronics"
      depth: 1
      primary: true
    - id: 166
      name: Apparel & Accessories
      path: "Apparel & Accessories"
      depth: 1
    - id: 536
      name: Home & Garden
      path: "Home & Garden"
      depth: 1
    - id: 469
      name: Health & Beauty
      path: "Health & Beauty"
      depth: 1
    - id: 783
      name: Media
      path: "Media"
      depth: 1
    - id: 922
      name: Office Supplies
      path: "Office Supplies"
      depth: 1
    - id: 1239
      name: Toys & Games
      path: "Toys & Games"
      depth: 1
    - id: 990
      name: Sporting Goods
      path: "Sporting Goods"
      depth: 1

  # === ASX Score (scan-based, 0-100) ===
  asx_score: 82
  asx_clarity: 28            # out of 35
  asx_discoverability: 24    # out of 30
  asx_reliability: 30        # out of 35
  last_scanned: "2026-03-15"
  scan_tier: premium         # free | premium

  # === AXS Rating (crowd-sourced, 1-5) ===
  axs_rating: 4.2
  axs_search_accuracy: 4.5
  axs_stock_reliability: 4.0
  axs_checkout_completion: 4.1
  axs_rating_count: 47

  # === API & Programmatic Access ===
  api_tier: partnered        # open | keyed | partnered | private
  api_name: Amazon PA-API v5
  mcp_endpoint: null
  ucp_registered: false
  has_cli: false
  search_api: true
  search_url_template: "https://www.amazon.com/s?k={q}"

  # === Checkout ===
  auth_required: true
  guest_checkout: false
  platform: custom               # shopify | woocommerce | magento | bigcommerce | custom
  checkout_steps: 4
  supported_payment_methods:
    - credit_card
    - amazon_pay
    - gift_card
  agentic_payment_protocols:
    - x402
    - acp
  po_number_supported: false
  tax_exempt_supported: false
  business_account_available: true

  # === Shipping ===
  supported_countries:
    - US
    - CA
    - UK
    - DE
  currency: USD
  delivery_options:
    - standard
    - express
    - same_day
  free_shipping_threshold: 35.00
  ships_internationally: true

  # === Returns & Refund Policy ===
  returns_policy_url: "/gp/help/customer/display.html?nodeId=GKM69DUUYKQWKR7Y"
  return_window: "30 days"
  return_shipping_paid_by: varies        # customer | merchant | varies | unknown
  refund_method: original_payment        # original_payment | store_credit | exchange_only | varies
  policy_format: html                    # html | pdf | accordion | behind_login | not_found
  policy_discoverable: true

  # === Loyalty ===
  loyalty_program: "Amazon Prime"
  agent_purchases_earn_points: unknown    # yes | no | unknown
  loyalty_attribution_method: null        # account_linked | referral_code | api | null

  # === Skill Quality ===
  skill_version: "2.1.0"
  generated_by: creditclaw
  generation_tier: premium   # free | premium | indexed
  last_verified: "2026-03-20"
  verification_status: verified   # verified | unverified | outdated

  # === Distribution ===
  shopify_catalog_submitted: false
  google_ucp_submitted: false
---

Field Reference

Identity Fields

Taxonomy Fields

Brand Type and Category Depth

The brand_type field determines how product categories are resolved:

The multi-sector value is not directly assignable — it is set programmatically when the brand type is department_store, supermarket, or mega_merchant. Focused brand types (brand, retailer, independent, chain, marketplace) keep their primary sector and can span categories across up to 2 sector roots.

ASX Score Fields (Scan-Based)

AXS Rating Fields (Crowd-Sourced)

API & Programmatic Access Fields

Checkout Fields

Shipping Fields

Returns & Refund Policy Fields

Loyalty Fields

Skill Quality Fields

Distribution Fields

Skill Body Structure

Below the frontmatter, the markdown body follows a standard structure. This is a recommendation for consistency — agents parse and execute skills more reliably when the structure is predictable.

{Vendor Name} — Agent Procurement Skill

Overview

Brief description of the vendor — what they sell, who they serve,

what makes them notable for AI agent procurement.

Product Discovery

Via API (Recommended)

Instructions for searching products through an API.

Includes: endpoint, auth, example queries, response format.

Via Website Search

Fallback instructions for searching the vendor's website directly.

Includes: search URL pattern, expected result format.

Product Detail

How to get full product information — price, availability, images,

variants (size, color, configuration), shipping options.

Cart Operations

How to add items to cart, view cart, update quantities, remove items.

Checkout Flow

Step-by-step checkout instructions.

Authentication

How to log in or create an account (if required).

Shipping

How to enter or select shipping address and method.

Payment

How to enter payment information or use saved payment methods.

Order Confirmation

What the confirmation looks like, how to capture the order ID.

Post-Purchase

Order tracking, returns, customer service contact.

Known Limitations

Issues the agent should be aware of — CAPTCHAs, rate limits,

anti-bot measures, inventory delays, etc.

Error Handling

What to do when common errors occur — out of stock, payment declined,

session expired, etc.

Feedback

After your purchase attempt (successful or not), help improve this skill:

POST {feedback_endpoint_url}

Authorization: Bearer

Content-Type: application/json

{

"search_accuracy": 4,

"stock_reliability": 5,

"checkout_completion": 3,

"checkout_method": "browser_automation",

"outcome": "success",

"comment": "optional — what happened?"

}

Ratings are 1-5. This is optional but helps other agents find reliable vendors.

---

## Machine-Readable Companion: `skill.json`

The structured metadata for each merchant is defined in a `skill.json` file. The SKILL.md frontmatter is derived from `skill.json` — they contain the same data, but `skill.json` is the machine-readable source of truth.

The full `skill.json` schema covers: identity, taxonomy (sector + Google Product Taxonomy categories), scoring (ASX + AXS), API access, checkout, shipping, returns, loyalty, skill quality, and distribution.

### Relationship between formats

| Format | Purpose | Consumed by |
|---|---|---|
| `skill.json` | Machine-readable source of truth | Agent runtimes, APIs, CLIs, indexes |
| SKILL.md frontmatter | Human-readable + machine-parseable | Agent runtimes that support skills.sh format |
| `.well-known/agentic-commerce.json` | Self-hosted merchant discovery | Any agent checking a merchant's domain |

### `.well-known/agentic-commerce.json`

Merchants can publish their `skill.json` at a well-known URL on their domain:

https://example.com/.well-known/agentic-commerce.json

This allows any agent to discover a merchant's capabilities by checking a single URL — similar to how `robots.txt` works for crawlers or `.well-known/openid-configuration` works for OAuth. The `.well-known` manifest uses the same schema as `skill.json`.

---

Part 2: ASX Score & AXS Rating System

Overview

The measurement framework consists of two complementary systems:

1. 01ASX Score (0–100) — An automated, scan-based score measuring how well a store supports AI shopping agents. Computed from crawling a domain's public surface. Updated per scan.

1. 01AXS Rating (1–5) — A crowd-sourced performance rating from real-world feedback submitted by AI agents and human reviewers after actual purchase attempts. Updated continuously.

The ASX Score tells you how ready a store should be based on its technical implementation. The AXS Rating tells you how well it actually performs in practice. Together they give a complete picture.

The Three Pillars

Both the ASX Score and AXS Rating are organized around three pillars that map to the natural flow of an agent-initiated purchase:

   Clarity              →      Discoverability           →        Reliability
   ─────────────────          ──────────────────           ─────────────────────
   Can the agent              Can the agent               Does the end-to-end
   FIND the store             DISCOVER products,          experience actually
   and UNDERSTAND             search, filter,             WORK when you try
   what's available?          and navigate                to complete a real
                              programmatically?           purchase?

Pillar 1: Clarity (Discovery & Metadata Quality)

The question: Can the agent find the store, understand its catalog structure, and know what shipping, payment, and loyalty options exist — before it even starts shopping?

What it covers:

• →Is there structured product data (JSON-LD, Open Graph, Schema.org Product markup)?
• →Is there a well-formed sitemap with product URLs?
• →Is the site mobile/responsive (agents often use headless viewports)?
• →Are shipping options clearly described in metadata or page structure?
• →Are payment methods clearly described in metadata or page structure?
• →Are loyalty programs described — including whether agent-initiated purchases earn points?
• →Is the checkout page structure predictable and well-organized?

Pillar 2: Discoverability (Search & Programmatic Access)

The question: Once the agent has found the store, can it discover and navigate products programmatically? Not just "find sneakers" — but "find these sneakers in size 9.5, in brown, check if that exact variant is in stock, and confirm delivery within a week."

What it covers:

• →Is there a functional product search (site search, API, MCP, CLI)?
• →Is there a public API with documented endpoints?
• →Is there MCP/UCP support for native agent interaction?
• →Can the agent select specific product variants (size, color, configuration) programmatically?
• →Can the agent check real-time stock for a specific variant?
• →Can the agent get a delivery estimate for a specific address or region?
• →Are product pages well-structured with clear information hierarchy?
• →How many steps/calls does it take to go from search → specific variant → stock check → delivery estimate?

Pillar 3: Reliability (Lived Experience)

The question: Does it actually work end-to-end in practice? When a real agent tries to search, find the specific item, check out, pay, and receive confirmation — does the whole thing succeed?

What it covers:

• →Does checkout actually complete without errors?
• →Can the agent select the shipping option it wants (not just default)?
• →Does the payment method the agent intends to use actually work?
• →How many retries does it typically take?
• →Does order confirmation arrive correctly?
• →Do loyalty points actually accrue for agent-initiated purchases?
• →Does the store block or throttle agent traffic during real use?
• →Is the product that arrives actually what was ordered (correct size, color, condition)?

Pillar-to-Measurement Matrix

ASX Score: Scan-Based Scoring (0–100)

Signal Breakdown

#### Clarity Signals (35 points) — "Can agents find your products?"

#### Discoverability Signals (30 points) — "Can agents search and navigate products?"

#### Reliability Signals (35 points) — "Can agents complete a purchase?"

Note: Reliability signals from a scan are proxy measurements only. True reliability is measured through the crowd-sourced AXS Rating (search accuracy, stock reliability, checkout completion from real agent interactions).

Note on programmatic checkout: If a site provides MCP, CLI, or API-based checkout that covers product selection, cart management, discount application, and payment — the browser-control aspects of Order Management and Checkout Flow become less important. The score engine gives full or near-full marks on those signals when comprehensive programmatic checkout is detected.

#### Potential Expansion Signals (Future — Post-Launch Validation)

Score Labels

Score Breakdown Structure

Each signal in the breakdown includes a score, maximum, and human-readable detail:

interface ASXScoreBreakdown {
  // Clarity (35 pts)
  structuredData:        { score: number; max: 15; details: string };
  sitemapQuality:        { score: number; max: 10; details: string };
  cleanHtml:             { score: number; max: 10; details: string };
  // Discoverability (30 pts)
  searchApi:             { score: number; max: 10; details: string };
  internalSearch:        { score: number; max: 10; details: string };
  pageLoadPerformance:   { score: number; max: 5;  details: string };
  productPageQuality:    { score: number; max: 5;  details: string };
  // Reliability (35 pts)
  accessAuth:            { score: number; max: 10; details: string };
  orderManagement:       { score: number; max: 10; details: string };
  checkoutFlow:          { score: number; max: 10; details: string };
  botTolerance:          { score: number; max: 5;  details: string };
}

Recommendations

After scoring, the system generates actionable recommendations grouped by impact:

interface ASXRecommendation {
  signal: string;
  impact: "high" | "medium" | "low";
  title: string;
  description: string;
  potentialGain: number;  // how many points this could add
}

Example recommendation:

**Add JSON-LD Product markup to product pages** (High impact, +12 points) This allows any agent to extract structured product data without an API. Include name, price, availability, image, and SKU at minimum.

AXS Rating: Crowd-Sourced Performance Rating (1–5)

Purpose

The AXS Rating answers: "How well does this store actually perform when agents interact with it?" It's a weighted average from real-world feedback submitted by AI agents and human reviewers after purchase attempts.

Three Feedback Dimensions

Future Feedback Dimensions (To Be Added)

Feedback Collection

Endpoint: POST /api/v1/bot/skills/{slug}/feedback

Request body:

{
  "search_accuracy": 4,
  "stock_reliability": 5,
  "checkout_completion": 3,
  "checkout_method": "browser_automation",
  "outcome": "success",
  "comment": "optional — what happened?"
}

Authentication:

• →Authenticated bots (API key): max 1 feedback per brand per hour — weight 1.0
• →Anonymous agents: accepted without auth — weight 0.5
• →Logged-in humans: via session auth — weight 2.0

Feedback is embedded in every generated SKILL.md as an instruction at the end of the file. Agents read the instruction and POST three ratings after each purchase attempt. No SDK, no callback registration — just a plain HTTP request described in the skill's markdown.

Feedback Data Schema

CREATE TABLE brand_feedback (
  id                    SERIAL PRIMARY KEY,
  brand_slug            TEXT NOT NULL,
  source                TEXT NOT NULL DEFAULT 'agent',    -- agent | human | anonymous_agent
  authenticated         BOOLEAN NOT NULL DEFAULT false,
  bot_id                TEXT,
  reviewer_uid          TEXT,
  search_accuracy       INTEGER NOT NULL,                 -- 1-5
  stock_reliability     INTEGER NOT NULL,                 -- 1-5
  checkout_completion   INTEGER NOT NULL,                 -- 1-5
  checkout_method       TEXT NOT NULL,
  outcome               TEXT NOT NULL,
  comment               TEXT,
  created_at            TIMESTAMP NOT NULL DEFAULT NOW()
);

Aggregation Algorithm

Ratings are recomputed periodically (hourly or daily) from the brand_feedback table:

1. Pull all feedback rows from the last 90 days per brand.

2. Apply recency weighting:
   - ≤ 7 days old:   weight 1.0 (fresh)
   - ≤ 30 days old:  weight 0.8 (recent)
   - ≤ 60 days old:  weight 0.6 (aging)
   - > 60 days old:  weight 0.4 (old; >90 days excluded)

3. Apply source weighting:
   - Human feedback:          weight 2.0
   - Authenticated agent:     weight 1.0
   - Anonymous agent:         weight 0.5

4. Combined weight per entry = recencyWeight × sourceWeight

5. Weighted averages per dimension:
   avgSearch   = Σ(search_accuracy × weight) / Σ(weight)
   avgStock    = Σ(stock_reliability × weight) / Σ(weight)
   avgCheckout = Σ(checkout_completion × weight) / Σ(weight)

6. Final AXS Rating = (avgSearch + avgStock + avgCheckout) / 3

7. Minimum threshold: total weight must be ≥ 5 to publish a score.
   Below threshold → all ratings set to NULL (not zero).

Why Comments Are Valuable

Agent comments are terse and specific: "Price shown was $24.99, actual cart price was $29.99" or "Checkout button selector changed, automation failed." These are actionable for skill maintainers.

Human comments provide context agents can't: "Ordered Monday, didn't ship until Friday even though it said 2-day delivery" or "The product arrived but was a different model than listed."

Over time, comments on a brand become a changelog of real-world issues. A merchant can read them to understand why their stock reliability is 2.8 — not just that it's low.

How the Two Systems Relate

A store can have a high ASX Score (great technical setup) but a low AXS Rating (it breaks in practice). Or a low ASX Score (no API, no structured data) but a high AXS Rating (checkout just works via browser automation). The combination tells the full story.

Open Questions

1. 01Standards body engagement. Should these standards be proposed to a formal body (W3C, IETF, schema.org community group)? Or established as de facto standards through adoption first?

1. 01.well-known/agentic-commerce.json adoption. The schema is defined (same as skill.json). When should merchants be encouraged to self-host it? After sufficient scan data validates the field set?

1. 01Score signal weights. The current weights (Clarity: 35, Discoverability: 30, Reliability: 35) are v1.1 values. Should they be validated against real scan data before publishing as a standard?

1. 01Expansion signals. The remaining "potential expansion" signals (variant discoverability in structured data, stock API, delivery estimate API) — should any be promoted to scored signals in a future version? Product Page Quality was promoted in v1.1.

1. 01AXS Rating dimension expansion. Adding shipping_option_accuracy, payment_method_success, loyalty_attribution, and delivery_accuracy — when should these be added? They require agents to report more granular data.

1. 01Cross-platform adoption. For the ASX Score to become an industry benchmark, other platforms need to reference it. How do we get agent developers (OpenAI, Anthropic, Google) to consider ASX Score when ranking merchant results?