Skip to main content

API Endpoints Reference

The Cloudflare Workers expose several API endpoints for pixel ingestion, configuration, and analytics.

Base URLs​

EnvironmentURL
Productionhttps://events.storeshield.in
Developmenthttp://localhost:8787

Pixel Ingestion​

POST /api/pixels​

Receives all client-side tracking events.

Request:

POST /api/pixels
Content-Type: application/json

{
  "type": "session_init",
  "shop": "mystore.myshopify.com",
  "sessionId": "sess_abc123",
  "visitorId": "vis_xyz789",
  "timestamp": 1709424000000,
  "page": "/products/example",
  "userAgent": "Mozilla/5.0...",
  // Type-specific fields...
}

Response:

{ "success": true }

Pixel Types:

TypeRequired Fields
session_initfingerprint, deviceInfo
basic_securityevent (right_click_blocked, copy_blocked, etc.)
bot_detectionsignalType, confidence, details
spy_detectiontoolName, detectionMethod
ip_blockingreason
behavior_analyticssignalType, data
checkout_sessioncartValue, itemCount

Heartbeat​

POST /api/heartbeat​

Theme extension sends current protection configuration.

Request:

POST /api/heartbeat
Content-Type: application/json

{
  "shop": "mystore.myshopify.com",
  "protections": {
    "rightClick": true,
    "copy": true,
    "devTools": false,
    "viewSource": false,
    "imageProtection": true,
    "textSelection": false
  },
  "botDetection": {
    "enabled": true,
    "honeypot": true,
    "trapLinks": true
  },
  "spyDetection": true,
  "ipBlocking": true,
  "version": "1.0.0",
  "timestamp": 1709424000000
}

Response:

{ "success": true }

IP Blocking​

GET /api/check-ip-access​

Checks if a visitor's IP/country is allowed.

Request:

GET /api/check-ip-access?shop=mystore.myshopify.com

Headers used:

  • CF-Connecting-IP - Visitor's IP address
  • CF-IPCountry - Visitor's country code

Response (allowed):

{
  "allowed": true
}

Response (blocked):

{
  "allowed": false,
  "reason": "blocked_country",
  "country": "XX"
}

POST /api/sync-ip-blocking-config​

Syncs IP blocking rules from the app to the edge.

Request:

POST /api/sync-ip-blocking-config
Content-Type: application/json
Authorization: Bearer <API_SECRET>

{
  "shop": "mystore.myshopify.com",
  "config": {
    "enabled": true,
    "blockedIPs": ["1.2.3.4", "5.6.7.8"],
    "blockedCIDRs": ["192.168.0.0/24"],
    "blockedCountries": ["XX", "YY"],
    "allowedIPs": ["10.0.0.1"],
    "blockVPN": true,
    "blockDatacenter": true,
    "blockTor": false
  }
}

Response:

{ "success": true }

Analytics​

GET /api/analytics/summary​

Gets aggregated threat metrics for a date range.

Request:

GET /api/analytics/summary?shop=mystore.myshopify.com&start=2024-03-01&end=2024-03-07

Response:

{
  "totals": {
    "sessions": 15420,
    "uniqueVisitors": 8930,
    "protectionEvents": 342,
    "botEvents": 89,
    "spyEvents": 23,
    "ipBlockingEvents": 156
  },
  "period": {
    "start": "2024-03-01",
    "end": "2024-03-07"
  }
}

GET /api/analytics/trend​

Gets daily trend data.

Request:

GET /api/analytics/trend?shop=mystore.myshopify.com&start=2024-03-01&end=2024-03-07&metric=bot_events

Response:

{
  "data": [
    { "date": "2024-03-01", "value": 12 },
    { "date": "2024-03-02", "value": 8 },
    { "date": "2024-03-03", "value": 15 },
    { "date": "2024-03-04", "value": 10 },
    { "date": "2024-03-05", "value": 18 },
    { "date": "2024-03-06", "value": 14 },
    { "date": "2024-03-07", "value": 12 }
  ],
  "metric": "bot_events"
}

GET /api/analytics/top-ips​

Gets top threat IPs.

Request:

GET /api/analytics/top-ips?shop=mystore.myshopify.com&start=2024-03-01&end=2024-03-07&limit=10

Response:

{
  "data": [
    { "ip": "1.2.3.4", "count": 45, "country": "US" },
    { "ip": "5.6.7.8", "count": 32, "country": "CN" },
    { "ip": "9.10.11.12", "count": 28, "country": "RU" }
  ]
}

GET /api/analytics/top-pages​

Gets most targeted pages.

Request:

GET /api/analytics/top-pages?shop=mystore.myshopify.com&start=2024-03-01&end=2024-03-07&limit=10

Response:

{
  "data": [
    { "page": "/products/popular-item", "count": 89 },
    { "page": "/collections/all", "count": 67 },
    { "page": "/", "count": 45 }
  ]
}

GET /api/analytics/top-countries​

Gets threat distribution by country.

Request:

GET /api/analytics/top-countries?shop=mystore.myshopify.com&start=2024-03-01&end=2024-03-07&limit=10

Response:

{
  "data": [
    { "country": "US", "count": 120 },
    { "country": "CN", "count": 89 },
    { "country": "RU", "count": 45 }
  ]
}

Activity Feeds​

GET /api/bot-activity​

Gets recent bot detection events.

Request:

GET /api/bot-activity?shop=mystore.myshopify.com&limit=50&offset=0

Response:

{
  "data": [
    {
      "id": "bot_123",
      "signalType": "selenium",
      "confidence": 95,
      "ip": "1.2.3.4",
      "page": "/products/example",
      "createdAt": 1709424000000
    }
  ],
  "total": 89,
  "limit": 50,
  "offset": 0
}

GET /api/spy-activity​

Gets recent spy tool detections.

Request:

GET /api/spy-activity?shop=mystore.myshopify.com&limit=50&offset=0

Response:

{
  "data": [
    {
      "id": "spy_456",
      "toolName": "ppspy",
      "detectionMethod": "global_object",
      "ip": "5.6.7.8",
      "page": "/",
      "createdAt": 1709424000000
    }
  ],
  "total": 23,
  "limit": 50,
  "offset": 0
}

GET /api/ip-blocking-activity​

Gets recent IP blocking events.

Request:

GET /api/ip-blocking-activity?shop=mystore.myshopify.com&limit=50&offset=0

Response:

{
  "data": [
    {
      "id": "ipb_789",
      "ip": "9.10.11.12",
      "country": "XX",
      "reason": "blocked_country",
      "page": "/checkout",
      "createdAt": 1709424000000
    }
  ],
  "total": 156,
  "limit": 50,
  "offset": 0
}

Billing​

GET /api/billing/visitor-count​

Gets unique visitor count for billing period.

Request:

GET /api/billing/visitor-count?shop=mystore.myshopify.com&start=2024-03-01&end=2024-03-31

Response:

{
  "count": 4532,
  "period": {
    "start": "2024-03-01",
    "end": "2024-03-31"
  }
}

Protection Config​

GET /api/protection-config​

Gets current protection configuration for a shop.

Request:

GET /api/protection-config?shop=mystore.myshopify.com

Response:

{
  "protections": {
    "rightClick": true,
    "copy": true,
    "devTools": false,
    "viewSource": false,
    "imageProtection": true,
    "textSelection": false
  },
  "botDetection": {
    "enabled": true,
    "honeypot": true,
    "trapLinks": true
  },
  "spyDetection": true,
  "ipBlocking": true
}

Error Responses​

All endpoints return standard error format:

{
  "error": true,
  "message": "Description of the error",
  "code": "ERROR_CODE"
}

Common Error Codes:

CodeHTTP StatusDescription
INVALID_REQUEST400Missing or invalid parameters
UNAUTHORIZED401Missing or invalid authorization
NOT_FOUND404Resource not found
RATE_LIMITED429Too many requests
INTERNAL_ERROR500Server error