Documentation

Everything you need to know to make your e-commerce products readable by AI shopping agents.

Getting Started

MerchantStamp works in three steps: first, run a free audit on your store URL to get your Agent-Readiness Score. Then review the detailed recommendations we provide for each issue found. Finally, upgrade to Silver or Gold to have MerchantStamp automatically generate and publish structured data for your store.

Run your free audit →

What We Scan

Our scanner checks your store for: JSON-LD Product markup (name, price, availability, GTIN/SKU, images, reviews), OpenGraph and meta tags, machine-readable shipping and return policies, robots.txt and AI crawler access rules, sitemap.xml completeness, page load performance, and mobile-friendliness. Each check contributes to your overall Agent-Readiness Score.

Understanding Your Score

Your Agent-Readiness Score ranges from 0 to 100. A score above 80 means your store is well-optimized for AI shopping agents. Between 50-80 means there are significant improvements to make. Below 50 means AI agents likely cannot read your product data at all.

Plans & Features

Bronze (free): run audits and view recommendations. Silver: automated JSON-LD generation, product feed creation, policy page structuring, and one-click publishing via a JavaScript snippet. Gold: everything in Silver plus continuous monitoring, hourly updates, drift detection alerts, and priority support.

Score Breakdown

Your Agent-Readiness Score is calculated from these weighted categories:

Structured Data (40%)

JSON-LD Product schema presence, completeness, and validity. Includes required fields like name, price, availability, images, and identifiers (GTIN, SKU).

Discoverability (20%)

Robots.txt rules for AI crawlers, sitemap.xml coverage, and meta tags (title, description, canonical URLs).

Policies (15%)

Machine-readable shipping, return, and privacy policies that AI agents can parse and present to users.

Technical (15%)

Page speed, mobile-friendliness, HTTPS, and proper HTTP status codes.

Rich Content (10%)

Product reviews, FAQ sections, and additional structured content that AI agents can leverage.

Silver Snippet Security

The Silver plan delivers structured data to your store via a lightweight JavaScript loader. Here is how we secure the supply chain from our servers to your visitors' browsers.

Subresource Integrity (SRI)

The loader is served as a versioned external file (silver-loader.v1.js), identical for every merchant. Your embed snippet includes an integrity attribute with a SHA-384 hash. The browser verifies that the file received matches the expected hash byte-for-byte before executing it. If the file has been altered in transit (CDN compromise, MITM), the browser blocks execution entirely.

<script src="https://merchantstamp.com/js/silver-loader.v1.js"
        data-merchant="your-slug"
        integrity="sha384-BGNRv9+DlJq1VVvXfI8nN2wKglv3uuGV9xMpS7sXvD8aYw2Sabwpv6l3EsELyOSX"
        crossorigin="anonymous"
        defer></script>

Content Security Policy (CSP)

If your site enforces a strict CSP, do not rely on a simple domain allowlist — those are often bypassable. Instead, use the loader's SRI hash combined with strict-dynamic. This tells the browser: "only execute the script whose content matches this exact hash, and allow any scripts it loads dynamically." This follows the model recommended by web.dev for a truly strict CSP.

Content-Security-Policy:
  script-src 'strict-dynamic' 'sha384-BGNRv9+DlJq1VVvXfI8nN2wKglv3uuGV9xMpS7sXvD8aYw2Sabwpv6l3EsELyOSX';
  connect-src 'self' https://merchantstamp.com;
  object-src 'none';
  base-uri 'none';

Data Injection Safety

The loader fetches JSON-LD blocks from our API and injects them using textContent only — never innerHTML. Each block is wrapped in a <script type="application/ld+json"> tag, which browsers treat as a data block (not executable code). Even if the API returned a malicious payload, it would not be executed by the browser. The residual risk is limited to SEO data integrity, not cross-site scripting (XSS).

Versioned Loader

The loader filename includes a version number (v1). When we release a new version, existing merchants stay on their current version with a stable SRI hash — no cache surprise, no breakage. You upgrade on your own schedule by updating the snippet and hash together.

CORS & Network

The JSON-LD API endpoint returns Access-Control-Allow-Origin: * so your store can fetch data cross-origin. The loader uses the defer attribute to avoid blocking HTML parsing — it executes after the DOM is ready, which is the optimal pattern for a non-critical enhancement script.

Remaining Boundary

SRI protects the loader file, not the JSON-LD API response at runtime. The API payload is served over HTTPS and cached at the edge (1-hour TTL) but is not hash-verified by the browser. This is a standard trade-off for any dynamic data feed. If your threat model requires signed API responses, contact us to discuss HMAC-based payload verification.

Frequently Asked Questions

Do I need to install anything?

For Bronze (free audit), no installation is needed — just enter your URL. For Silver and Gold, you add a small JavaScript snippet to your site that loads the generated structured data automatically.

Which platforms are supported?

MerchantStamp works with any e-commerce platform accessible via a public URL: Shopify, WooCommerce, PrestaShop, Magento, BigCommerce, custom stores, and more.

How often is my store re-scanned?

Bronze: manual scans only. Silver: weekly re-scans. Gold: hourly monitoring with real-time alerts for any data drift.

What AI agents does this help with?

MerchantStamp optimizes your store for ChatGPT (with browsing/shopping), Google Gemini, Perplexity, Claude, Microsoft Copilot, and any future AI agent that reads structured web data.