Overview

The Checkpoint Shopify integration lets you detect and monitor AI agent traffic on your Shopify store. Once connected, Checkpoint tracks agent sessions, calculates threat levels, and provides stats through both the dashboard and API.

Connecting Your Store

The Shopify integration uses OAuth to connect your store to a Checkpoint project:

Start the connection flow from the Checkpoint dashboard or the Shopify App Store
Authorize Checkpoint to access your Shopify store
Checkpoint provisions a project linked to your store automatically

The OAuth callback at /api/internal/shopify/callback handles token exchange and project provisioning.

Each Shopify store is linked to a Checkpoint project. The integration provisions the project automatically during the OAuth flow.

Project Configuration

Once connected, you can configure detection settings for your Shopify project via API:

# Get project details
curl https://kya.vouched.id/api/v1/shopify/projects/{projectId} \
  -H "X-API-Key: $CHECKPOINT_API_KEY"

Updating Settings

curl -X PATCH https://kya.vouched.id/api/v1/shopify/projects/{projectId} \
  -H "X-API-Key: $CHECKPOINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "blockOnHighConfidence": true,
      "confidenceThreshold": 0.8
    }
  }'

Updates require an API key with write permission. The fields you send are merged into the project's existing settings — include only what you want to change. All fields are optional:

Field	Type	Default	Description
`blockOnHighConfidence`	`boolean`	`false`	Block detected agents whose confidence meets the threshold
`confidenceThreshold`	`number`	`0.8`	Confidence required to trigger blocking (`0.0`–`1.0`)
`enableSessionTracking`	`boolean`	`true`	Track agent sessions across requests
`enableWasm`	`boolean`	`true`	Use the WASM detection engine

Stats and Monitoring

Retrieve detection statistics for your Shopify store:

curl https://kya.vouched.id/api/v1/shopify/projects/{projectId}/stats \
  -H "X-API-Key: $CHECKPOINT_API_KEY"

Optional query parameters: startDate and endDate (ISO 8601, default: the last 24 hours), plus page (default 1) and limit (default 100, max 100) for paginating recentThreats.

The response is a { "success": true, "data": { ... } } envelope. The data object includes:

Field	Type	Description
`totalRequests`	`number`	Total visitor sessions in the period
`blockedBots`	`number`	Sessions identified as AI agents
`allowedRequests`	`number`	`totalRequests` minus `blockedBots`
`threatLevel`	`string`	Calculated threat level: `low`, `medium`, `high`
`recentThreats`	`array`	Recent AI agent sessions — `sessionId`, `timestamp`, `type`, `ip`, `userAgent`, `action`, `pagesVisited`
`pagination`	`object`	`page`, `limit`, `total`, `hasMore` for the `recentThreats` list

Threat Levels

Level	AI Sessions %	Meaning
low	< 1%	Minimal AI agent activity
medium	1–5%	Moderate AI agent activity
high	> 5%	Significant AI agent traffic detected

Shopify API

Endpoint	Method	Auth	Description
`/api/v1/shopify/projects/{projectId}`	`GET`	API Key (read)	Get project details
`/api/v1/shopify/projects/{projectId}`	`PATCH`	API Key (write)	Update project settings
`/api/v1/shopify/projects/{projectId}/stats`	`GET`	API Key (read)	Get detection statistics

All API endpoints require a valid API key via the X-API-Key header.

This OAuth-connected app covers project provisioning, settings, and stats. To also detect AI agents directly on your storefront via the Marketing Pixel (adding the loader snippet to theme.liquid), see the Shopify tab in Detect: Pixel Quick Start.

Next Steps

Detect: Pixel Quick Start — Add the Marketing Pixel to your Shopify theme
Dashboard Analytics — View detection data across all projects
Detection Methods — Understand how Checkpoint detects AI agents
Enforcement Policies — Configure what happens when agents are detected

Shopify Integration