How it works

Getting the most from Agentic Commerce

Everything you need to audit your catalog, fix data gaps, and get your products recommended by AI shopping agents.

Why this matters

AI shopping assistants — Claude, Google Gemini, ChatGPT Shopping, Perplexity — are changing how people discover products. Instead of browsing search results, shoppers increasingly ask an AI: "What's a good light roast from Ethiopia for pour-over?" The AI reads product data and decides which products to recommend.

Most Shopify stores are technically discoverable by these agents. The problem is that being discoverable and being recommended are completely different things. An agent won't confidently recommend a product it can't fully understand — and vague titles, missing attributes, and no structured data make products hard to understand.

The difference between discoverable and recommended

Discoverable but not recommended

  • Title: "House Blend Coffee 250g"
  • No roast level, origin, or tasting notes
  • No structured data on the product page
  • Agent can find it, but can't describe it

Discoverable and recommended

  • Title: "Ethiopia Yirgacheffe Light Roast — Washed"
  • Roast: Light · Notes: Jasmine, peach, lemon
  • Brew methods: Pour-over, AeroPress
  • Structured data on product page — agent can describe it precisely

Agentic Commerce closes that gap. It audits every product in your store, identifies exactly what's missing, and uses AI to fill in the details — so your products give agents everything they need to recommend them with confidence.

Getting set up

1

Install the app from the Shopify App Store

Click Install and approve the permissions. The app needs read and write access to your products so it can run the audit and save the enriched attributes back to your catalog. You'll be taken directly to the dashboard after installation.

2

Run your first audit

Hit Run Audit on the dashboard. This takes a minute or two depending on your catalog size. The app scans every product and scores it across several dimensions. You don't need to do anything — just wait for the results to appear.

3

Activate the Product Schema extension

This is a one-time setup that adds hidden structured data to your product pages, making them readable by AI shopping tools and Google's Rich Results system. Go to Online Store → Themes → Customize, open a product template, click Add block → Apps → Coffee Product JSON-LD, and save. It takes about two minutes and doesn't change anything your customers can see.

That's it for setup

After installation, your first audit, and activating the schema extension, the app is fully operational. Everything from here is about reviewing your scores and using Auto-Fix to close any gaps.

Running an audit

An audit scans your entire product catalog and produces a score for every product. You can run a fresh audit at any time — for example, after adding new products or making changes to your catalog. The dashboard always shows results from the most recent audit.

What the audit checks

Product details — Title quality, description length, product type — the basics that help agents understand what you sell.
Coffee attributes — Roast level, origin, processing method, flavour notes, and ideal brew methods. These are the specific details AI shopping agents use to match products to what shoppers are looking for.
Product images — Whether you have product photos and whether they have descriptive alt text — both matter for AI recommendations.
Product schema on your live store — Whether the structured data is actually live on your product pages. This is what allows Google and AI agents to read your product details directly from your storefront.
Store trust signals — Return policy, shipping information, and product barcodes (GTINs). These affect whether Google's Shopping feed — and therefore AI shopping tools — treats your store as trustworthy.

Re-run any time

After using Auto-Fix on a product, the app rescores that product immediately — you don't need to run a full audit again. Run a full audit when you want to refresh scores for your whole catalog at once, or after adding new products.

Your score explained

Every product gets an AI Readiness score from 0 to 100. This tells you how well-positioned that product is to be recommended by AI shopping agents. Your dashboard also shows an overall store score — the average across all your products.

80–100

Agent Ready

This product has the attributes, structure, and schema that AI agents need to recommend it confidently. Keep it maintained as you update pricing or add variants.

50–79

Needs Work

This product has some of the key details but is missing things that limit how well agents can understand it. Auto-Fix can usually close most of these gaps in seconds.

0–49

Not Ready

This product has significant gaps — missing attributes, no schema, or other critical issues. It's unlikely to be recommended by AI agents in its current state. Start with Auto-Fix.

What affects your score most

Coffee-specific attributes have the biggest impact on your score — they carry 35% of the total weight. This reflects how critical they are for AI agent recommendations: an agent can't recommend the right coffee without knowing roast level, origin, and flavour profile.

Coffee attributes35%

Roast, origin, processing, flavour notes, brew methods

Product details20%

Title quality, description completeness

Images15%

Photo presence, alt text

Variants & GTINs10%

Pricing, barcodes

Catalogue tags10%

Collections, product type, tags

Availability10%

Stock status, inventory policy

Auto-Fix

Auto-Fix uses AI to read your existing product title and description and suggest values for any missing attributes. You review the suggestions before anything is saved — nothing changes in your store without your approval.

How it works, step by step

1

Click the Auto-Fix icon on any product

You'll see the wand icon in the product list next to products with gaps. Click it and the app immediately starts analysing that product.

2

Review the suggestions

A panel opens showing the AI's suggested values — things like roast level, origin country, flavour notes, and ideal brew methods. Review each one. If something doesn't look right, you can edit it before saving.

3

Apply to your store

Click Apply to Shopify. The values are saved directly to your product's attributes in Shopify Admin. Your product is immediately rescored and the dashboard updates in real-time.

Auto-Fix All

You can also run Auto-Fix across multiple products at once using the Auto-Fix All button on the dashboard. It works through your products sequentially, with a short pause between each. Useful when you've just added a batch of new products.

What Auto-Fix can and can't do

Can do

  • Infer roast level from description ("bold, dark chocolate" → dark roast)
  • Identify origin from product name ("Yirgacheffe" → Ethiopia)
  • Suggest flavour notes from tasting language in your copy
  • Determine coffee type (blend vs. single origin)
  • Recommend likely brew methods from product context

Can't do

  • Add product photos or write product copy
  • Add GTINs / barcodes (these must come from your supplier)
  • Fix issues with your store's return policy or shipping setup
  • Infer details that aren't present anywhere in your existing product info

Product Schema

Product Schema (technically called JSON-LD) is a block of structured data that lives invisibly inside your product pages. Your customers never see it — but Google, Gemini, and other AI shopping tools read it to understand your products in detail.

What it includes

  • Product name, description, and brand
  • Current price and availability — always accurate, pulled live from your store
  • Product images
  • Coffee-specific attributes: roast level, origin, processing method, flavour notes
  • Product barcode (GTIN) if available — improves Google Shopping eligibility

One-time activation required

The schema is generated automatically, but you need to activate the Theme Extension once in your Shopify Theme Editor for it to appear on your product pages. Go to Online Store → Themes → Customize → product template → Add block → Apps → Coffee Product JSON-LD → Save. After that it works on every product automatically.

How to verify it's working

1

Open any product page on your live store

Pick a product that has been audited and has a good score.

2

Run Google's Rich Results Test

Go to search.google.com/test/rich-results, paste your product page URL, and run the test. You should see a Product result detected with no errors.

3

Check your score

After activating the extension and verifying it works, run a fresh audit. Products with working schema will see their score improve — schema contributes to the SEO layer of the readiness score.

Frequently asked questions

Quickstart

Five minutes from zero to a confirmed test order. You'll connect the Buyer MCP endpoint to Claude Desktop, search live inventory, and execute a purchase — without writing any code.

1

Get a buyer account

Create an AGC account at /buyer/settings. Vault your card via the Stripe-hosted form — this is the only time you'll touch a payment screen. AGC never sees the card number.

2

Connect the Buyer MCP endpoint to Claude Desktop

Add the following to your claude_desktop_config.json:

claude_desktop_config.json
// Claude Desktop — claude_desktop_config.json
{
"mcpServers": {
"agc-buyer": {
"command": "npx",
"args": [
"-y", "@modelcontextprotocol/sdk",
"--server-url", "https://useao.ai/mcp/buyer"
]
}
}
}
3

Authorise the connection

Claude will prompt you to authorise AGC via the standard OAuth flow. Approve it. Your buyer profile and Stripe vault are now accessible to the agent.

4

Place a test order

Tell Claude: "Find me an Ethiopian light roast under £20 and order it."The agent will call search_products, quote the total, wait for your confirmation, then call execute_purchase.

what the agent calls
// 1. Search products
const results = await search_products({
query: "Ethiopian light roast",
limit: 3,
})
// 2. Quote
const quote = await get_checkout_quote({
cartItems: [{ variantId: results[0].variantId, quantity: 1 }],
shopDomain: results[0].shopDomain,
})
// → { quoteId, total: "£17.00", expiresAt }
// 3. Execute — only after buyer says yes
const order = await execute_purchase({
quoteId: quote.quoteId,
shopDomain: results[0].shopDomain,
})
// → { success: true, orderId, orderName: "AGC-4A3C9FB6" }

Quote TTL is 15 minutes

get_checkout_quote locks live inventory and price for 15 minutes. If the buyer doesn't confirm within that window, the quote expires and the agent must fetch a fresh one. Nothing is charged until execute_purchase is called.

Buyer MCP

The Buyer MCP endpoint gives any MCP-compatible agent access to the full AGC buyer network — live inventory across every merchant, confirmed pricing, and payment execution.

Endpoint: useao.ai/mcp/buyer

Tool reference

buyer MCP tools
// Tool: search_products
// Find products across all AGC merchants
search_products({
query: string, // "Ethiopian light roast"
originCountry: string?, // "Ethiopia"
roastLevel: string?, // "light" | "medium" | "dark"
processingMethod: string?,
maxPrice: number?,
currency: string?, // "GBP" | "USD" | "EUR"
shopDomain: string?, // filter to one merchant
limit: number?, // default 10
})
// → Product[] { variantId, title, price, shopDomain, score }
// Tool: get_checkout_quote
// Confirmed total — product + shipping + tax
get_checkout_quote({
cartItems: Array<{ variantId: string; quantity: number }>,
shopDomain: string,
})
// → { quoteId, total, currency, breakdown, expiresAt }
// Quote is valid for 15 minutes. Nothing is charged.
// Tool: execute_purchase
// Call only after explicit buyer confirmation
execute_purchase({
quoteId: string,
shopDomain: string,
})
// → { success, orderId, orderName, estimatedDelivery? }

execute_purchase requires explicit buyer confirmation

The agent must present the quote total and wait for an affirmative response before calling execute_purchase. Any tool call made without buyer confirmation is a misuse of the API and may result in access revocation.

Scopes

buyer:readsearch_products, get_checkout_quote
buyer:executeexecute_purchase — requires buyer:read

Merchant MCP

The Merchant MCP endpoint gives a merchant's AI assistant full catalog operator access — audit readiness scores, enrich products with Gemini, push attributes to Shopify, and publish products to the buyer network.

Endpoint: useao.ai/mcp

Tool reference

merchant MCP tools
// Tool: get_audit_summary
get_audit_summary()
// → { overallScore, avgProductScore, totalProducts,
// agentReady: number, needsWork: number, notReady: number }
// Tool: get_product_scores
get_product_scores()
// → Product[] sorted by score ascending (worst first)
// Tool: get_product_detail
get_product_detail({ productId: string })
// → { score, issues: Issue[], attributes: Record<string, string> }
// Tool: enrich_product
enrich_product({ productId: string })
// → { structuredTitle, roastLevel, originCountry, processingMethod,
// flavorNotes[], brewMethods[], confidence: number }
// Tool: audit_draft_products
audit_draft_products()
// → { scored: Product[], avgScore: number }
// Synchronous — no polling required
// Tool: publish_product
publish_product({ productId: string })
// → { status: "published" }

Scopes

merchant:readget_audit_summary, get_product_scores, get_product_detail
merchant:writeenrich_product, audit_draft_products, publish_product — requires merchant:read

Authentication

Both MCP endpoints use OAuth 2.0 with PKCE. Token scopes are endpoint-specific — a buyer token cannot call merchant tools and vice versa. Merchant tokens are scoped per merchant: one token cannot act on behalf of another merchant.

OAuth discovery + PKCE flow
1// OAuth discovery
2GET https://useao.ai/.well-known/oauth-authorization-server
3
4// → {
5// authorization_endpoint: "https://useao.ai/oauth/authorize",
6// token_endpoint: "https://useao.ai/oauth/token",
7// scopes_supported: ["buyer:read", "buyer:execute",
8// "merchant:read", "merchant:write"],
9// }
10
11// PKCE flow — your agent initiates
12const verifier = crypto.randomBytes(32).toString('base64url');
13const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
14
15// Redirect to authorize
16GET /oauth/authorize?
17 client_id=YOUR_CLIENT_ID
18 &redirect_uri=https://yourapp.com/callback
19 &scope=buyer:read buyer:execute
20 &code_challenge=YOUR_CODE_CHALLENGE
21 &code_challenge_method=S256
22
23// Exchange code for token
24POST /oauth/token
25 { code, code_verifier: verifier, redirect_uri }
26// → { access_token, refresh_token, expires_in, scope }

Token handling

  • Access tokens expire in 1 hour. Use the refresh token to obtain a new one.
  • The Shippo SDK handles token refresh automatically via the StorageAdapter.
  • Revoking a token immediately invalidates all outstanding calls using it.
  • 3D Secure challenges surface a secure redirect link — the agent never handles bank authentication directly.

Webhooks

Shippo fires webhooks for tracking updates and label creation. The Shippo SDK handles signature verification and dispatch automatically. If you're integrating the Buyer or Merchant MCP endpoints directly, you don't need to handle webhooks — AGC manages them and advances order status internally.

Registration happens at OAuth connect time

The Shippo SDK registers track_updated and transaction_created webhooks during the OAuth callback — not when a label is purchased. If merchants connected before you mounted the webhook handler, call shippo.syncWebhooks(merchantId) to backfill.

Signature verification

HMAC verification — done automatically by the SDK
// Verify Shippo signature (done automatically by the Shippo SDK)
import crypto from 'crypto';
function verifyShippoSignature(
payload: string,
signature: string,
secret: string,
): boolean {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature),
);
}
// Event types AGC/Shippo sends
type WebhookEvent =
| { event: 'track_updated'; data: TrackingEvent }
| { event: 'transaction_created'; data: TransactionEvent };

Retry policy

Shippo retries failed webhook deliveries with exponential backoff over 24 hours. Your handlers should be idempotent — the same event may be delivered more than once. Use the event's objectId as an idempotency key.

  • Return HTTP 200 quickly — do heavy work asynchronously.
  • Do not use webhook delivery as your only order state mechanism.
  • The Shippo SDK returns 400 on invalid signatures — Shippo will retry.

Shippo SDK

@agenticcommerce/shippo-mcp is a standalone package that adds Shippo Gray Label to any MCP server — multi-tenant OAuth, token management, webhook routing, and the full label lifecycle. It has no dependency on AGC's buyer network or enrichment pipeline.

Full SDK documentation

StorageAdapter interface, tool reference, OAuth flow, webhook handling, and early access.

SDK docs

Early access

The SDK is in active conversations with Shippo's MCP team. Register interest at /developers/shippo-sdk#early-access or email developers@agenticcommerce.com.

Ready to improve your scores?

Open the dashboard, run an audit, and see where your products stand.