Shopify

This guide covers two ways to connect your Shopify or Shopify Plus store to Inception Agents: the Shopify App (recommended) or a theme script tag. The app generates llms.txt, enriches product structured data, and tracks AI agent referrals; the script tag tracks referrals only.

What to Expect

After install, the dashboard shows agent visits, llms.txt requests, and referral attribution as they arrive. When the first agent traffic appears depends on how actively AI platforms crawl your store.

Timeframe	What Happens
0-1 hour	Initial product catalog crawl completes. Existing pages are indexed and scored for agent readability.
1-6 hours	`llms.txt` and `agent.json` are generated and served. Product structured data gaps are identified.
6-24 hours	First optimization pass runs. Product JSON-LD is enriched with competitive positioning, review summaries, and availability signals.
Ongoing	Agent referral tracking runs. The dashboard shows which AI platforms are sending traffic and which products they reference.

Prerequisites

A Shopify or Shopify Plus store
An Inception Agents account with an API key (sign up)
Your Tenant ID (found in Settings > API Keys in the Inception Agents dashboard)

Option 1: Shopify App (Recommended)

The app handles everything automatically — no code changes, no theme edits, no DNS configuration.

Step 1: Install from Your Install Link

The Inception Agents app is not listed in the Shopify App Store. We provision a direct install link for your store: book a call to get one. Open the link, click Install, and authorize the required permissions when prompted.

Step 2: Enter Your API Key

After installation, navigate to Apps > Inception Agents in your Shopify admin. Enter your API key from the Inception Agents dashboard.

API Key: ia_live_xxxxxxxxxxxxxxxxxxxx

Step 3: Confirm Activation

The app will:

Auto-generate /llms.txt and /.well-known/agent.json for your store
Enrich product structured data with JSON-LD (competitive positioning, feature comparisons, availability signals, review summaries)
Begin tracking AI agent referral traffic
Register Shopify webhooks for product create/update/delete events to keep data in sync

No further action is required. The app runs at the edge and does not modify your theme files.

Option 2: Theme Script Tag

If you prefer not to install the app, add the beacon script directly to your theme.

Step 1: Open Your Theme Code

In your Shopify admin, go to Online Store > Themes > Actions > Edit Code.

Step 2: Edit `theme.liquid`

Open theme.liquid (or your layout file) and add the following script tag immediately before the closing </head> tag:

<script
  src="https://cdn.inceptionagents.com/beacon.js"
  data-api-key="YOUR_API_KEY"
  data-tenant-id="YOUR_TENANT_ID"
  defer
></script>

Replace YOUR_API_KEY and YOUR_TENANT_ID with values from your Inception Agents dashboard (Settings > API Keys).

Step 3: Save and Publish

Click Save. The beacon will activate on your next page load.

Note: The script tag method provides agent detection and referral tracking but does not generate llms.txt or enrich product structured data. For full functionality, use the Shopify App.

What Gets Optimized

Asset	Description	Auto-Generated
Product catalog (JSON-LD)	Product, Offer, and AggregateRating structured data enriched with competitive positioning, feature comparisons, availability signals, and review summaries	Yes
`/llms.txt`	Machine-readable site description with product categories, brand positioning, and shipping/return policies	Yes
`/.well-known/agent.json`	Agent card declaring your store’s capabilities, endpoints, and protocols	Yes
*`/agent/` endpoints**	Query-able endpoints for product comparisons, pricing, and availability	Yes
Referral tracking	Attribution for purchases originating from AI agent recommendations	Yes

Product Structured Data

The Shopify integration enriches your product JSON-LD beyond what Shopify generates natively:

Competitive positioning — how your product compares to alternatives an agent might be evaluating
Feature comparisons — structured feature lists optimized for agent consumption
Availability signals — real-time stock status, shipping estimates, fulfillment options
Review summaries — aggregated review sentiment and key themes (not just star counts)
Pricing context — price relative to category averages, bundle options, subscription pricing

This data is served to AI agents alongside your existing product pages. Human visitors see no changes.

AI Referral Tracking

Inception Agents identifies and attributes traffic from these AI platforms:

Platform	Detection Method
ChatGPT	User-Agent, referrer header, behavioral signals
Perplexity	User-Agent (`PerplexityBot`, `Perplexity-User`)
Claude	User-Agent (`ClaudeBot`, `anthropic-ai`)
Gemini	User-Agent (`Google-Extended`), referrer
Copilot	User-Agent (`CopilotBot`, `Microsoft-Copilot`)
Grok	User-Agent (`Grok`, `Harper`, `xAI`)

Referral data appears in the dashboard under Analytics > Agent Referrals. Purchase attribution is tracked when a visitor arrives from an AI agent recommendation and completes checkout.

Verification

After setup, verify that the integration is working:

Check `llms.txt`

curl -s https://your-store.com/llms.txt

Expected: a markdown document describing your store, product categories, and key policies.

Check Agent Detection

curl -s \
  -H "User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.0" \
  https://your-store.com/products/your-product

Expected: the response includes enriched JSON-LD structured data and the X-Inception-Agent: detected header.

Check Agent Card

curl -s https://your-store.com/.well-known/agent.json

Expected: a JSON object declaring your store’s agent capabilities and endpoints.

Configuration Options

These settings are available in the Shopify app under Apps > Inception Agents > Settings, or via environment variables for the Cloudflare Proxy method.

Option	Default	Description
`syncProducts`	`true`	Automatically sync product catalog on create/update/delete
`enrichJsonLd`	`true`	Add competitive positioning and review summaries to product JSON-LD
`generateLlmsTxt`	`true`	Auto-generate and serve `/llms.txt`
`trackReferrals`	`true`	Track AI agent referral traffic and purchase attribution
`excludeCollections`	`[]`	Collection handles to exclude from agent optimization
`excludeProducts`	`[]`	Product handles to exclude from agent optimization
`cacheTtl`	`3600`	Cache TTL in seconds for optimized content

Troubleshooting

`llms.txt` returns 404

Shopify App: Confirm the app is installed and activated in Apps > Inception Agents. Check that your API key is valid.
Script Tag: The script tag method does not generate llms.txt. Use the Shopify App instead.

No agent traffic in the dashboard

Agent traffic depends on AI platforms crawling your store, and how soon that starts varies.
Verify detection is working using the curl commands in the Verification section.
Ensure your store is publicly accessible (not password-protected).

Product data not syncing

Confirm Shopify webhooks are registered: in your Shopify admin, go to Settings > Notifications > Webhooks and look for Inception Agents entries.
Trigger a manual sync from the app: Apps > Inception Agents > Settings > Sync Products.

Slow page loads after installation

The Shopify App runs at the edge and should add zero latency to human page loads. If you experience slowdowns, check that no other apps are conflicting.
The Script Tag adds ~5KB to initial page load. It loads asynchronously (defer) and does not block rendering.

Theme conflicts

The app does not modify your theme files. If you see rendering issues after installation, the cause is likely unrelated.
For Script Tag installs, verify the tag is placed before </head> and not inside a conditional block.

Uninstall

Shopify App

In your Shopify admin, go to Apps
Find Inception Agents and click Delete
The app will remove its webhooks and stop serving optimized content

Your store reverts to its default behavior immediately. No residual code remains.

Theme Script Tag

Go to Online Store > Themes > Actions > Edit Code
Open theme.liquid
Remove the <script> tag you added
Click Save

Shopify

Shopify

What to Expect

Prerequisites

Option 1: Shopify App (Recommended)

Step 1: Install from Your Install Link

Step 2: Enter Your API Key

Step 3: Confirm Activation

Option 2: Theme Script Tag

Step 1: Open Your Theme Code

Step 2: Edit theme.liquid

Step 3: Save and Publish

What Gets Optimized

Product Structured Data

AI Referral Tracking

Verification

Check llms.txt

Check Agent Detection

Check Agent Card

Configuration Options

Troubleshooting

llms.txt returns 404

No agent traffic in the dashboard

Product data not syncing

Slow page loads after installation

Theme conflicts

Uninstall

Shopify App

Theme Script Tag

Step 2: Edit `theme.liquid`

Check `llms.txt`

`llms.txt` returns 404