Shopify

This guide covers three ways to connect your Shopify or Shopify Plus store to Inception Agents: the Shopify App (recommended), a theme script tag, or a Cloudflare proxy. Each method auto-generates llms.txt, enriches product structured data, and tracks AI agent referrals.

What to Expect

After install, first agent traffic typically appears within 24-48 hours. The dashboard will show agent visits, llms.txt requests, and referral attribution. Content optimization begins automatically — no manual intervention required.

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 the Shopify App Store

Search for Inception Agents in the Shopify App Store and click Install. 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:

1. Auto-generate /llms.txt and /.well-known/agent.json for your store
2. Enrich product structured data with JSON-LD (competitive positioning, feature comparisons, availability signals, review summaries)
3. Begin tracking AI agent referral traffic
4. 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 auto-generate llms.txt or enrich product structured data at the edge. For full functionality, use the Shopify App or Cloudflare Proxy.

Option 3: Cloudflare Proxy

Route your Shopify store through a Cloudflare Worker to get full edge-level interception without installing the Shopify app.

Step 1: Install the Package

npm install @inception-agents/cloudflare

Step 2: Configure the Worker

// src/index.ts
import { createInceptionHandler } from '@inception-agents/cloudflare';

export interface Env {
  INCEPTION_API_KEY: string;
  INCEPTION_CACHE: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const handler = createInceptionHandler({
      apiKey: env.INCEPTION_API_KEY,
      originUrl: 'https://your-store.myshopify.com',
      kvCache: env.INCEPTION_CACHE,
      kvCacheTtl: 3600,
    });

    return handler(request);
  },
};

Step 3: Deploy

npx wrangler secret put INCEPTION_API_KEY
npx wrangler deploy

Point your custom domain’s DNS to the Cloudflare Worker. Human traffic passes through to Shopify unmodified. Agent traffic receives optimized content at the edge.

See the full Cloudflare Worker guide for KV namespace setup, wrangler.toml configuration, and troubleshooting.

What Gets Optimized

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:

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.

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 or Cloudflare Proxy instead.
• Cloudflare Proxy: Verify your Worker is deployed and the custom domain DNS is pointing to the Worker.

No agent traffic in the dashboard

• Agent traffic depends on AI platforms crawling your store. This typically begins within 24-48 hours of activation.
• 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

1. In your Shopify admin, go to Apps
2. Find Inception Agents and click Delete
3. 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

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

Cloudflare Proxy

1. Remove or disable the Cloudflare Worker
2. Point your custom domain DNS back to Shopify directly
3. Uninstall the package:

npm uninstall @inception-agents/cloudflare