Falcon Ecommerce

Sites API

Overview

Sites represent individual stores or websites within a publisher's account. Each site contains demographic and business information and serves as a container for placements (ad units).

Base Endpoint

https://pr-api.falconlabs.us/api/site

Authentication

All Site API endpoints require PUBLISHER Token Authentication.

Authorization: Bearer <PUBLISHER_TOKEN>

Create Site

Creates a new site under a publisher account.

Endpoint

POST /api/site

Request Body

json

{
  "name": "Mobile E-commerce Store",
  "description": "Dedicated mobile shopping experience",
  "orderVolume": 800,
  "averageOrder": 65.5,
  "ageDemographics": "AGE_25_34",
  "genderDemographics": "MIXED",
  "domain": "mobile.acme-ecommerce.com",
  "status": "active",
  "createEpomZone": true,
  "categoryName": "Fashion & Apparel"
}

Required Fields:

name: Required, non-empty string, trimmed
description: Optional, non-empty string if provided, trimmed
orderVolume: Optional, non-negative integer (monthly order volume)
averageOrder: Optional, non-negative number (average order value in USD)
ageDemographics: Optional, must be valid AgeDemo enum value
- Valid values: AGE_18_24, AGE_25_34, AGE_35_44, AGE_45_54, AGE_55_64, AGE_65_PLUS
genderDemographics: Optional, must be valid GenderDemo enum value
- Valid values: MALE, FEMALE, MIXED
domain: Optional, trimmed (use actual domain, avoid myshopify.com when possible)
status: Optional, must be "active" or "inactive" (defaults to "pending")
createEpomZone: Optional, boolean (defaults to true)
categoryName: Optional, must exactly match existing category name (case-sensitive)

Important for Ad Optimization: Providing accurate demographic and business data (orderVolume, averageOrder, ageDemographics, genderDemographics, categoryName) is critical for delivering relevant offers and maximizing revenue.

Category Name Options (153 Categories)

Category matching is case-sensitive and must use exact format Major Vertical > Sub-Vertical:

Example Request

bash

curl -X POST https://pr-api.falconlabs.us/api/site \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer falcon_sk_xyz789abc123def456ghi789jkl012mno345" \
  -d '{
    "name": "Mobile E-commerce Store",
    "description": "Dedicated mobile shopping experience",
    "orderVolume": 800,
    "averageOrder": 65.50,
    "ageDemographics": "AGE_25_34",
    "genderDemographics": "MIXED",
    "domain": "mobile.acme-ecommerce.com",
    "status": "active",
    "createEpomZone": true,
    "categoryName": "Fashion & Apparel"
  }'

Success Response (201 Created)

json

{
  "success": true,
  "data": {
    "id": "cm5e6f7g8h9i0j1k2l3m4n5o",
    "name": "Mobile E-commerce Store",
    "description": "Dedicated mobile shopping experience",
    "orderVolume": 800,
    "averageOrder": 65.5,
    "ageDemographics": "AGE_25_34",
    "genderDemographics": "MIXED",
    "domain": "mobile.acme-ecommerce.com",
    "status": "active",
    "adsEnabled": true,
    "createdAt": "2024-01-16T09:15:00.000Z",
    "updatedAt": "2024-01-16T09:15:00.000Z",
    "category": {
      "id": "cm6f7g8h9i0j1k2l3m4n5o6p",
      "name": "Apparel and Fashion > Clothing and Apparel",
      "path": "Apparel and Fashion > Clothing and Apparel",
      "taxonomyId": "falcon_tax_fashion_001"
    }
  },
  "message": "Site created successfully"
}

Idempotent Behavior - Existing Site Returned

Important Behavioral Note: If a site with the same name already exists for this publisher, the API returns the existing site (200 OK) instead of throwing a conflict error. This is intentional to support idempotent site creation.

json

{
  "success": true,
  "data": {
    "id": "cm5e6f7g8h9i0j1k2l3m4n5o",
    "name": "Mobile E-commerce Store",
    "description": "Dedicated mobile shopping experience",
    "orderVolume": 800,
    "averageOrder": 65.5,
    "ageDemographics": "AGE_25_34",
    "genderDemographics": "MIXED",
    "domain": "mobile.acme-ecommerce.com",
    "status": "active",
    "adsEnabled": true,
    "createdAt": "2024-01-15T09:15:00.000Z",
    "updatedAt": "2024-01-15T09:15:00.000Z",
    "category": {
      "id": "cm6f7g8h9i0j1k2l3m4n5o6p",
      "name": "Apparel and Fashion > Clothing and Apparel",
      "path": "Apparel and Fashion > Clothing and Apparel",
      "taxonomyId": "falcon_tax_fashion_001"
    }
  },
  "message": "Site created successfully"
}

Note: You can distinguish between a newly created site and an existing site by comparing the createdAt timestamp. If the site was just created, createdAt will be very recent. For existing sites, createdAt may be older.

Error Responses

400 Bad Request - Validation Failed

json

{
  "error": "Request validation failed",
  "code": "VALIDATION_FAILED",
  "details": ["name: name is required and must be a non-empty string"],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

400 Bad Request - Category Not Found:

json

{
  "error": "Invalid value for field: categoryName",
  "code": "INVALID_FIELD_VALUE",
  "details": {
    "field": "categoryName",
    "value": "Invalid Category",
    "expectedType": "valid category name from list"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

401 Unauthorized

json

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication token"
  }
}

Get Site by ID

Retrieves a single site by ID.

Endpoint

GET /api/site/:id

Authentication

Use the publisher’s Private Key:

Authorization: Bearer PUBLISHER_PRIVATE_KEY

Example Request

bash

curl -X GET https://pr-api.falconlabs.us/api/site/clx3c4d5e6f7g8h9i0j1k2l3m \
  -H "Authorization: Bearer priv_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

Success Response (200 OK)

json

{
  "success": true,
  "data": {
    "id": "cm5e6f7g8h9i0j1k2l3m4n5o",
    "name": "Fashion Boutique Store",
    "description": "Premium women's fashion",
    "domain": "fashionboutique.com",
    "orderVolume": 500,
    "averageOrder": 75.5,
    "ageDemographics": "AGE_25_34",
    "genderDemographics": "FEMALE",
    "status": "active",
    "adsEnabled": true,
    "createdAt": "2024-01-15T10:35:00.000Z",
    "updatedAt": "2024-01-15T10:35:00.000Z",
    "category": {
      "id": "cm6f7g8h9i0j1k2l3m4n5o6p",
      "name": "Apparel and Fashion > Clothing and Apparel",
      "path": "Apparel and Fashion > Clothing and Apparel",
      "taxonomyId": "falcon_tax_fashion_001"
    }
  }
}

Error Responses

404 Not Found

json

{
  "error": "Site not found",
  "code": "RESOURCE_NOT_FOUND",
  "details": {
    "resourceType": "Site",
    "id": "clx3c4d5e6f7g8h9i0j1k2l3m"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

List Sites

Retrieves all sites for a publisher.

Endpoint

GET /api/site

Authentication

Use the publisher’s Private Key:

Authorization: Bearer PUBLISHER_PRIVATE_KEY

Query Parameters

skip (number, default: 0): Number of records to skip
take (number, default: 50, max: 100): Number of records to return
include (string): Set to "relations" to include related data
stats (boolean): Set to true to include site statistics

Example Request

bash

curl -X GET "https://pr-api.falconlabs.us/api/site?skip=0&take=20" \
  -H "Authorization: Bearer priv_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

Success Response (200 OK)

json

{
  "success": true,
  "data": [
    {
      "id": "clx3c4d5e6f7g8h9i0j1k2l3m",
      "name": "Fashion Boutique Store",
      "domain": "fashionboutique.com",
      "status": "active",
      "createdAt": "2024-01-15T10:35:00.000Z"
    },
    {
      "id": "clx4d5e6f7g8h9i0j1k2l3m4n",
      "name": "Tech Gadgets Shop",
      "domain": "techgadgets.com",
      "status": "active",
      "createdAt": "2024-01-14T09:20:00.000Z"
    }
  ],
  "pagination": {
    "total": 12,
    "skip": 0,
    "take": 20,
    "hasMore": false
  }
}

Update Site

Updates an existing site’s information.

Endpoint

PUT /api/site/:id

Authentication

Use the publisher’s Private Key:

Authorization: Bearer PUBLISHER_PRIVATE_KEY

Request Body

All fields are optional:

json

{
  "name": "Updated Store Name",
  "description": "Updated description",
  "domain": "newdomain.com",
  "orderVolume": 750,
  "averageOrder": 85.0,
  "status": "active"
}

Example Request

bash

curl -X PUT https://pr-api.falconlabs.us/api/site/clx3c4d5e6f7g8h9i0j1k2l3m \
  -H "Authorization: Bearer priv_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "orderVolume": 750,
    "averageOrder": 85.00
  }'

Success Response (200 OK)

json

{
  "success": true,
  "data": {
    "id": "clx3c4d5e6f7g8h9i0j1k2l3m",
    "name": "Fashion Boutique Store",
    "orderVolume": 750,
    "averageOrder": 85.0,
    "updatedAt": "2024-01-15T12:00:00.000Z"
  },
  "message": "Site updated successfully"
}

Update Site Status (Lifecycle Management)

Updates the operational status of a site (active/inactive). Use this endpoint to activate or deactivate sites based on store lifecycle events.

Endpoint:

PATCH /api/site/:id/status

Authentication: PUBLISHER Token

Rate Limit: 50 req/min (elevated: 150 req/min)

Path Parameters:

id: Site ID (required, non-empty string)

Request Body:

json

{
  "status": "active",
  "reason": "Store activated after verification"
}

Field Requirements:

status: Required, must be "active" or "inactive"
reason: Optional, string describing the reason for the status change

Example Request:

bash

curl -X PATCH https://pr-api.falconlabs.us/api/site/cm2a3b4c5d6e7f8g9h0i1j2k/status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer falcon_sk_xyz789abc123def456ghi789jkl012mno345" \
  -d '{
    "status": "active",
    "reason": "Store activated after verification"
  }'

Success Response (200 OK):

json

{
  "success": true,
  "data": {
    "id": "cm2a3b4c5d6e7f8g9h0i1j2k",
    "name": "Main E-commerce Store",
    "status": "active",
    "adsEnabled": true
  },
  "message": "Site status updated to active"
}

Use Cases:

Store Installation: Set status to "active" when a store is first installed
Store Uninstallation: Set status to "inactive" when a store is uninstalled
Store Suspension: Set status to "inactive" when a store violates policies
Store Reactivation: Set status to "active" when a suspended store is reinstated

Webhook Logging: This operation creates a WebhookLog entry with:

source: "publisher:{publisherId}"
eventType: "site_status_change"
payload:
siteId: The affected site ID
publisherId: The publisher making the change
callerIpAddress: IP address of the caller

Error Response (400 Bad Request):

json

{
  "error": "Invalid value for field: status",
  "code": "INVALID_FIELD_VALUE",
  "details": {
    "field": "status",
    "value": "invalid_value",
    "expectedType": "\"active\" or \"inactive\""
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Update Site Ads Status (Lifecycle Management)

Updates the ad serving status for a site independently from site status.

Endpoint:

PATCH /api/site/:id/ads

Authentication: PUBLISHER Token

Rate Limit: 50 req/min (elevated: 150 req/min)

Path Parameters:

id: Site ID (required, non-empty string)

Request Body:

json

{
  "adsEnabled": true,
  "reason": "Ads enabled after payment verification"
}

Field Requirements:

adsEnabled: Required, boolean (true to enable ads, false to disable)
reason: Optional, string describing the reason for the change

Example Request:

bash

curl -X PATCH https://pr-api.falconlabs.us/api/site/cm2a3b4c5d6e7f8g9h0i1j2k/ads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer falcon_sk_xyz789abc123def456ghi789jkl012mno345" \
  -d '{
    "adsEnabled": true,
    "reason": "Subscription payment confirmed"
  }'

Success Response (200 OK):

json

{
  "success": true,
  "data": {
    "id": "cm2a3b4c5d6e7f8g9h0i1j2k",
    "name": "Main E-commerce Store",
    "status": "active",
    "adsEnabled": true
  },
  "message": "Site ads enabled"
}

Use Cases:

Free Trial: Disable ads during free trial period, enable after subscription
Payment Failure: Temporarily disable ads when payment fails
Publisher Request: Enable/disable ads based on publisher preferences
Policy Violation: Disable ads temporarily during investigation
Testing: Disable ads during site testing or maintenance

Webhook Logging: This operation creates a WebhookLog entry with:

source: "publisher:{publisherId}"
eventType: "site_ads_toggle"
payload:
siteId: The affected site ID
publisherId: The publisher making the change
callerIpAddress: IP address of the caller

Error Response (400 Bad Request):

json

{
  "error": "Invalid value for field: adsEnabled",
  "code": "INVALID_FIELD_VALUE",
  "details": {
    "field": "adsEnabled",
    "value": "invalid_value",
    "expectedType": "boolean"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Site Lifecycle Management Notes

Status vs Ads Enabled:

status controls overall site activation
adsEnabled specifically controls ad serving
Both must be active/true for ads to display

Lifecycle Endpoints Features:

Separate rate limits (50 req/min standard, 150 elevated)
Automatic webhook logging for audit trail
IP address tracking for security
Optional reason field for documentation

Integration Benefits:

Automated store lifecycle management
Audit trail for compliance
Fine-grained control over ad serving
Support for free trials and payment workflows

Delete Site

Deletes a site and all associated placements.

Warning: This action is irreversible. All placements and historical data will be permanently deleted.

Endpoint

DELETE /api/site/:id

Authentication

Use the publisher’s Private Key:

Authorization: Bearer PUBLISHER_PRIVATE_KEY

Example Request

bash

curl -X DELETE https://pr-api.falconlabs.us/api/site/clx3c4d5e6f7g8h9i0j1k2l3m \
  -H "Authorization: Bearer priv_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

Success Response (200 OK)

json

{
  "success": true,
  "message": "Site deleted successfully"
}

Error Responses

403 Forbidden - Active Placements

json

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Cannot delete site with active placements",
    "details": {
      "activePlacements": 2
    }
  }
}

Sites API ​

Overview ​

Base Endpoint ​

Authentication ​

Create Site ​

Endpoint ​

Request Body ​

Category Name Options (153 Categories) ​

Category ​

Example Request ​

Success Response (201 Created) ​

Idempotent Behavior - Existing Site Returned ​

Error Responses ​

Get Site by ID ​

Endpoint ​

Authentication ​

Example Request ​

Success Response (200 OK) ​

Error Responses ​

List Sites ​

Endpoint ​

Authentication ​

Query Parameters ​

Example Request ​

Success Response (200 OK) ​

Update Site ​

Endpoint ​

Authentication ​

Request Body ​

Example Request ​

Success Response (200 OK) ​

Update Site Status (Lifecycle Management) ​

Update Site Ads Status (Lifecycle Management) ​

Site Lifecycle Management Notes ​

Delete Site ​

Endpoint ​

Authentication ​

Example Request ​

Success Response (200 OK) ​

Error Responses ​

Sites API

Overview

Base Endpoint

Authentication

Create Site

Endpoint

Request Body

Category Name Options (153 Categories)

Category

Example Request

Success Response (201 Created)

Idempotent Behavior - Existing Site Returned

Error Responses

Get Site by ID

Endpoint

Authentication

Example Request

Success Response (200 OK)

Error Responses

List Sites

Endpoint

Authentication

Query Parameters

Example Request

Success Response (200 OK)

Update Site

Endpoint

Authentication

Request Body

Example Request

Success Response (200 OK)

Update Site Status (Lifecycle Management)

Update Site Ads Status (Lifecycle Management)

Site Lifecycle Management Notes

Delete Site

Endpoint

Authentication

Example Request

Success Response (200 OK)

Error Responses