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: $AGENTSHIELD_API_KEY"

Updating Settings

curl -X PUT https://kya.vouched.id/api/v1/shopify/projects/{projectId} \
  -H "X-API-Key: $AGENTSHIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enforcement_mode": "monitor",
    "notification_email": "alerts@example.com"
  }'

Available settings:

Field	Type	Description
`enforcement_mode`	`string`	Detection mode for the store
`notification_email`	`string`	Email for threat notifications
`custom_block_page`	`string`	Custom HTML for blocked agent responses

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: $AGENTSHIELD_API_KEY"

The stats response includes:

Field	Type	Description
`totalSessions`	`number`	Total visitor sessions in the period
`aiSessions`	`number`	Sessions identified as AI agents
`aiSessionsPercentage`	`number`	Percentage of traffic from AI agents
`threatLevel`	`string`	Calculated threat level: `low`, `medium`, `high`
`topThreats`	`array`	Most active agent types with session counts

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

API Reference

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

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

Next Steps

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