Skip to main content

​
How to verify your integration

Use View Source (Ctrl+U / Cmd+Option+U), not the DevTools Elements panel. DevTools shows the hydrated DOM after JavaScript runs; crawlers see the initial HTML, which is exactly what View Source shows. Then validate structured data with the Google Rich Results Test or validator.schema.org.

​
Common issues

In order of likelihood:
  1. Environment variables not set. A missing AGENTSHOP_SEO_URL logs a single warning to your server console ([@agentshop/seo] Missing base URL…) and skips tags. Check both AGENTSHOP_SEO_URL and AGENTSHOP_API_KEY. (A missing AGENTSHOP_API_KEY doesn’t warn — it just silently yields no tags.)
  2. Wrong or expired key. An invalid, missing, or rotated-out key returns 401, which the SDK treats as “no bundle” — silently. Copy the key again from Settings → API Keys and test the endpoint directly: curl -H "Authorization: Bearer $AGENTSHOP_API_KEY" $AGENTSHOP_SEO_URL/product/{handle}. If you rotated the key more than 24h ago, the old one has stopped working — update the env var.
  3. Timeout too low. The default is 3 seconds — fine for the warm endpoint, but a cold or local backend can exceed it. Pass { timeoutMs: 15000 } while testing.
  4. Rate limited. Sustained bursts above 300 requests/min (per store) return 429. This is usually a caching gap — make sure the framework cache is on (Next.js ISR is by default).
Remember the design: any failure means missing tags, never an error page. Your page rendering fine with no tags is the failure signature.
By design. Next’s typed Metadata union doesn’t accept "product" and throws at runtime, so the App Router adapter omits og:type while rendering every other Open Graph tag. The Pages Router, Remix, and Hydrogen adapters do emit og:type=product.
Your deploy platform doesn’t have the environment variables. Set AGENTSHOP_SEO_URL and AGENTSHOP_API_KEY in the platform’s environment settings (Vercel project settings, Netlify, etc.) and redeploy.On Hydrogen/Oxygen there’s an extra trap: Oxygen has no process.env — env only exists on context.env. Set the variables on the Hydrogen storefront environment and make sure custom code never reads process.env. See the Hydrogen guide.
The 502 means the SDK couldn’t fetch the sitemap from the endpoint — misconfigured or unreachable. Check the same things as “no tags appear”: env vars, API key, timeout. Test directly: curl -H "Authorization: Bearer $AGENTSHOP_API_KEY" $AGENTSHOP_SEO_URL/sitemap.xml.
You’re looking at the hydrated DOM. If tags exist in DevTools but not in View Source, they’re being injected client-side (perhaps by another SEO library) and crawlers won’t see them. The SDK’s helpers are server-rendered — make sure you’re using them in server components/loaders, not client effects.

​
FAQ

As a schema.org ProductGroup with each variant a Product under hasVariant, each carrying its own Offer. Single-variant products are a plain Product.
Ratings and reviews aren’t wired into the SEO bundle yet. Emitting fabricated or placeholder rating data would violate Google’s structured-data guidelines, so the field is omitted until real review data is connected.
Deliberately omitted: there’s currently no merchant data source for social profiles, shipping policies, or return policies. Structured data is only emitted where real data exists — nothing is synthesized.
Next.js App Router (full: product, collection, site, sitemap); Next.js Pages Router, Remix v2, and Hydrogen/Oxygen (product + sitemap). Any other server-rendered stack can use the core fetch helpers directly — see the Core API.
No. Every helper returns null/renders nothing on any failure — your page ships without SEO tags rather than erroring. The one deliberate exception is the sitemap route, which returns 502 (a sitemap must be real XML or an error).
Still stuck? Test the endpoint directly with your API key — the endpoint reference documents the exact URLs, auth header, and status codes.