Falcon Ecommerce

Appearance

Placements API ​

Overview ​

Placements represent specific ad unit locations where promotional offers are displayed (e.g., thank you page, order status page). Placements define where and how ads are rendered on publisher websites.

Base Endpoint ​

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

Note: The endpoint is /api/placements (plural), not /api/placement (singular).

Authentication ​

All Placement API endpoints require PUBLISHER Token Authentication.

Authorization: Bearer <PUBLISHER_TOKEN>

Create Placement ​

Creates a new placement (ad unit).

Default behavior — test mode: Newly created placements default to test mode (isLiveMode: false). In test mode the OData endpoint returns non-production mock offers — they are not real offers from the Falcon network and will not generate revenue or attribution. This is the expected default on the staging environment and for initial UA / test stores you spin up in production while validating an integration. When you create real publishers in production that should serve actual offers, you must explicitly pass isLiveMode: true on the create request (or flip the flag later via the Update Placement endpoint).

Endpoint ​

POST /api/placements

Authentication: PUBLISHER Token

Request Body ​

json
{
  "name": "Thank You Page Placement",
  "siteId": "cm2a3b4c5d6e7f8g9h0i1j2k",
  "pageType": "THANK_YOU_PAGE",
  "isLiveMode": false,
  "template": 5,
  "data": {
    "customMessage": "Thanks for your purchase!",
    "showDiscount": true
  }
}

Required Fields:

  • name: Required, non-empty string
  • EITHER:
    • siteId: Optional, string (if site already exists)
    • OR:
    • storeName: Optional, string (required if no siteId provided)
    • storeUrl: Optional, valid URL or domain (required if no siteId provided)
  • shopifyUrl: Optional, valid URL or domain
  • pageType: Optional, must be valid PageType enum value
    • Valid values: THANK_YOU_PAGE, ORDER_PAGE
  • isLiveMode: Optional, boolean (defaults to false)
    • false (default): Placement is in test mode — OData returns non-production mock/test ads. Expected for staging and for initial UA/test stores in production.
    • true: Placement serves real offers from the Falcon network. Required for any real publisher in production that should generate impressions, clicks, and revenue.
  • template: Optional, integer between 1 and 21
  • data: Optional, custom data object for placement configuration

Validation Rules:

  • Either siteId OR both storeName and storeUrl must be provided
  • URLs must be valid format (https://example.com) or domain name (example.com)
  • Template must be integer between 1 and 21 if provided

Example Request (with existing site) ​

bash
curl -X POST https://pr-api.falconlabs.us/api/placements \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer falcon_sk_xyz789abc123def456ghi789jkl012mno345" \
  -d '{
    "name": "Thank You Page Placement",
    "siteId": "cm2a3b4c5d6e7f8g9h0i1j2k",
    "pageType": "THANK_YOU_PAGE",
    "template": 5,
    "isLiveMode": false
  }'

Example Request (with new store): ​

bash
curl -X POST https://pr-api.falconlabs.us/api/placements \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer falcon_sk_xyz789abc123def456ghi789jkl012mno345" \
  -d '{
    "name": "Order Confirmation Placement",
    "storeName": "Fashion Boutique Online",
    "storeUrl": "https://fashionboutique.com",
    "shopifyUrl": "https://fashionboutique.myshopify.com",
    "pageType": "ORDER_PAGE",
    "template": 3,
    "isLiveMode": true
  }'

Success Response (201 Created) ​

The create response contains only id and name. To read the full placement (site, type, mode, timestamps), call GET /api/placements/:id afterwards.

json
{
  "success": true,
  "data": {
    "id": "cm0j1k2l3m4n5o6p7q8r9s0t",
    "name": "Thank You Page Placement"
  },
  "message": "Placement created successfully"
}

Idempotent retries: If a matching placement already exists, the API responds with 200 OK and "message": "Placement already exists" instead of 201 Created. The data payload (id, name) is the same in both cases.

Key Response Fields:

  • id: Placement ID to use in OData requests and SDK initialization

Error Responses ​

400 Bad Request - Validation Error:

json
{
  "error": "Request validation failed",
  "code": "VALIDATION_FAILED",
  "details": ["name: Name is required"],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

400 Bad Request - Site/Store Validation:

json
{
  "error": "Request validation failed",
  "code": "VALIDATION_FAILED",
  "details": [
    "siteId: Either siteId or both storeName and storeUrl are required"
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

400 Bad Request - URL Validation:

json
{
  "error": "Request validation failed",
  "code": "VALIDATION_FAILED",
  "details": [
    "storeUrl: Must be a valid URL (e.g., https://example.com) or domain name (e.g., example.com)"
  ],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

400 Bad Request - Template Validation:

json
{
  "error": "Request validation failed",
  "code": "VALIDATION_FAILED",
  "details": ["template: Template must be an integer between 1 and 21"],
  "timestamp": "2024-01-15T10:30:00.000Z"
}

400 Bad Request - Site Not Found:

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

Get Placement by ID ​

Retrieves a single placement by ID.

Endpoint ​

GET /api/placements/: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/placements/clx4d5e6f7g8h9i0j1k2l3m4n \
  -H "Authorization: Bearer priv_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

Success Response (200 OK) ​

json
{
  "success": true,
  "data": {
    "id": "cm0j1k2l3m4n5o6p7q8r9s0t",
    "name": "Thank You Page Placement",
    "site": {
      "id": "cm2a3b4c5d6e7f8g9h0i1j2k",
      "name": "My Store"
    },
    "type": "THANK_YOU_PAGE",
    "pageTarget": "BLOCK",
    "isLiveMode": false,
    "createdAt": "2024-01-15T10:40:00.000Z",
    "updatedAt": "2024-01-15T10:40:00.000Z"
  }
}

List Placements ​

Retrieves all placements for a publisher or site.

Endpoint ​

GET /api/placements

Authentication ​

Use the publisher’s Private Key:

Authorization: Bearer PUBLISHER_PRIVATE_KEY

Query Parameters ​

  • siteId (string): Filter by specific site
  • skip (number, default: 0): Number of records to skip
  • take (number, default: 50, max: 100): Number of records to return
  • pageType (string): Filter by page type (THANK_YOU_PAGE, ORDER_PAGE)
  • isLiveMode (boolean): Filter by mode (true or false)

Example Request ​

bash
curl -X GET "https://pr-api.falconlabs.us/api/placements?siteId=clx3c4d5e6f7g8h9i0j1k2l3m&isLiveMode=false&skip=0&take=50" \
  -H "Authorization: Bearer priv_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

Success Response (200 OK) ​

json
{
  "success": true,
  "data": [
    {
      "id": "clx4d5e6f7g8h9i0j1k2l3m4n",
      "name": "Thank You Page Placement",
      "site": {
        "id": "clx3c4d5e6f7g8h9i0j1k2l3m",
        "name": "My Store"
      },
      "type": "THANK_YOU_PAGE",
      "pageTarget": "BLOCK",
      "isLiveMode": false,
      "createdAt": "2024-01-15T10:40:00.000Z",
      "updatedAt": "2024-01-15T10:40:00.000Z"
    },
    {
      "id": "clx5e6f7g8h9i0j1k2l3m4n5o",
      "name": "Order Status Page Placement",
      "site": {
        "id": "clx3c4d5e6f7g8h9i0j1k2l3m",
        "name": "My Store"
      },
      "type": "ORDER_PAGE",
      "pageTarget": "BLOCK",
      "isLiveMode": false,
      "createdAt": "2024-01-15T11:00:00.000Z",
      "updatedAt": "2024-01-15T11:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 2,
    "skip": 0,
    "take": 50,
    "hasMore": false
  }
}

Update Placement ​

Updates an existing placement’s configuration.

Endpoint ​

PUT /api/placements/:id

Authentication ​

Use the publisher’s Private Key:

Authorization: Bearer PUBLISHER_PRIVATE_KEY

Request Body ​

All fields are optional:

json
{
  "name": "Updated Placement Name",
  "isLiveMode": true,
  "pageType": "ORDER_PAGE",
  "pageTarget": "ANNOUNCEMENT_BAR",
  "data": {
    "brandName": "Updated Brand Name"
  }
}

Example Request ​

bash
curl -X PUT https://pr-api.falconlabs.us/api/placements/clx4d5e6f7g8h9i0j1k2l3m4n \
  -H "Authorization: Bearer priv_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "isLiveMode": true
  }'

Success Response (200 OK) ​

json
{
  "success": true,
  "data": {
    "id": "clx4d5e6f7g8h9i0j1k2l3m4n",
    "name": "Thank You Page Placement",
    "isLiveMode": true,
    "updatedAt": "2024-01-15T12:00:00.000Z"
  },
  "message": "Placement updated successfully"
}

Delete Placement ​

Deletes a placement.

Endpoint ​

DELETE /api/placements/: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/placements/clx4d5e6f7g8h9i0j1k2l3m4n \
  -H "Authorization: Bearer priv_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"

Success Response (200 OK) ​

json
{
  "success": true,
  "message": "Placement deleted successfully"
}