◎ Discry Score
shopify.com
commerce · API
B
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 95 (A)
Discry your API →
COMMERCE · RANK #7 OF 21

Shopify is Good to agents.

Discry independently scored how well an AI agent can discover and understand the Shopify API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.

Discry your API — freeView the docs ↗

SCORED UNDER RUBRIC 1.2 · A full re-launch under Discry Score 2.5 — a new behavioral instrument, not comparable to these scores — is in progress.

Discovery

45% of score · 67/100
OpenAPI specA machine-readable OpenAPI/Swagger spec agents can parse.Partial
llms.txtAn llms.txt index that points agents to the docs that matter.Pass
llms.txt qualityThe llms.txt is focused, current, and well under the size budget.Partial
llms-full.txtA full-text bundle agents can load in one request.Fail
AGENTS.mdAn AGENTS.md that tells coding agents how to build on the API.Partial
.well-known/mcp.jsonA discoverable MCP manifest at a well-known path.Fail
MCP registryThe API is listed in a public MCP registry.Pass
robots.txt AI directivesrobots.txt allows (or explicitly guides) AI crawlers.Pass
SitemapA sitemap so agents can enumerate the docs surface.Pass

Comprehension

55% of score · 84/100
Task-oriented descriptionsEndpoints described by what they accomplish, not just their shape.Pass
Realistic examplesRunnable, real-world request/response examples.Partial
Multi-step workflowsDocs that chain calls into complete jobs an agent can follow.Pass
Error-recovery guidanceDocumented failure modes and how to recover from them.Partial
Answer-first formatThe answer leads; preamble does not bury it.Pass
Capability boundariesClear limits — what the API can and cannot do.Pass
Naming consistencyConsistent, predictable naming across endpoints.Pass
Heading hierarchyClean heading structure agents can navigate.Pass
Markdown docsDocs available as clean markdown, not JS-rendered HTML only.Pass
Token efficiencyDocs are concise enough to fit an agent context window.Partial

What we found

  • Shopify's llms.txt is comprehensive (94KB, 151 sections) but too large for the new llmsTxtQuality check — at nearly 2x the 50KB threshold, it reads more as a product documentation dump than an API-focused agent resource
  • An agent looking for multi-step workflow guidance would find it: app development guides, webhook setup tutorials, Hydrogen getting started, and Shopify CLI workflows cover end-to-end scenarios
  • Error recovery guidance is limited — error status codes are documented with descriptions (402: frozen shop, 423: locked shop) but few include actionable recovery steps for agents to self-correct
  • Official MCP servers (Dev MCP and Storefront MCP) are listed on registries and documented for Claude Code/Cursor setup, but .well-known/mcp.json is missing for automated discovery
  • The Shopify/agent-skills repo with AGENTS.md shows strong agent-first intent, but it focuses on Supabase-style skill definitions rather than API coding context

What to change

Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.

  1. 01Add .well-known/mcp.json to shopify.dev with tool declarations for the official Dev MCP and Storefront MCP servers
  2. 02Create a focused API-only llms.txt (<50KB) covering core Admin API operations, authentication, and GraphQL patterns — keep the current comprehensive version as llms-full.txt
  3. 03Add actionable error recovery guidance: for each common error (rate limit, frozen shop, invalid scope), document what an agent should DO to recover
  4. 04Add AGENTS.md to shopify-app-js or shopify-api-ruby repos with API-specific coding agent context: GraphQL vs REST, scope requirements, webhook patterns
  5. 05Publish an official OpenAPI spec or make GraphQL schema downloadable without authentication for agent tooling generation

Execution coverage · INFORMATIONAL, UNSCORED

Whether an agent can actually complete a call and recover from errors is the deeper Audit layer — documented here, but not part of the Discry Score.

oauth2session_tokenapi_key✓ Error format documented✓ Rate limits documented✓ Pagination documented✕ Idempotency documented

OAuth2 with token exchange for embedded apps, API keys for custom apps. Comprehensive error status codes (400-530). GraphQL Admin API uses calculated query cost rate limiting (100-2000 points/second by plan tier). Cursor-based pagination with PageInfo object. No idempotency key support documented.

See your own Discry Score.

Drop your API docs URL. See what an agent sees — in 60 seconds, free.

Discry your API — free