Catalog API Documentation

Browse endpoints, parameters, and live request examples.

GET /sockets/{socket_id}/marketing

Get marketing content

Retrieves featured marketing content and promotional items for the catalog. This endpoint returns specially curated items for marketing and promotional purposes.

Catalog

Parameters

socket_id required path (integer)

The catalog socket to query

category_id query (integer)

Filter marketing by category ID

brand_id query (integer)

Filter marketing by brand ID

tag_id query (integer)

Filter marketing by tag ID

item_id query (integer)

Get marketing for specific item

key query (string)

Custom marketing key

Responses

200 Marketing content retrieved successfully
Category-specific marketing

Marketing blocks for a specific category page 

{
  "blocks": [
    {
      "copy": "Electronics Deals - Limited Time",
      "image": "https://cdn.example.com/banners/electronics-deals.jpg",
      "type": "banner",
      "uri": "/search?category=electronics&tag=sale"
    },
    {
      "carousel": "1",
      "items": [
        20001,
        20002,
        20003,
        20004
      ],
      "limit": 4,
      "title": "Top Rated Electronics",
      "type": "item_list"
    }
  ],
  "load_items": [
    20001,
    20002,
    20003,
    20004
  ],
  "success": true,
  "timestamp": "2025-08-08T11:15:00.000Z"
}
No marketing content

Response when no marketing content is configured 

{
  "blocks": [],
  "load_items": [],
  "success": true,
  "timestamp": "2025-08-08T11:15:00.000Z"
}
Homepage marketing blocks

Typical homepage with banners and featured items 

{
  "blocks": [
    {
      "copy": "Summer Sale - Save up to 40%!",
      "image": "https://cdn.example.com/banners/summer-sale-2025.jpg",
      "type": "banner",
      "uri": "/search?tag=summer-sale"
    },
    {
      "carousel": "1",
      "items": [
        12345,
        12346,
        12347,
        12348,
        12349,
        12350
      ],
      "limit": 6,
      "title": "Best Sellers",
      "type": "item_list"
    },
    {
      "copy": "New Arrivals - Shop the Latest",
      "image": "https://cdn.example.com/banners/new-arrivals.jpg",
      "type": "banner",
      "uri": "/search?tag=new"
    },
    {
      "carousel": "0",
      "items": [
        12351,
        12352,
        12353,
        12354
      ],
      "limit": 4,
      "title": "Trending Now",
      "type": "item_list"
    }
  ],
  "load_items": [
    12345,
    12346,
    12347,
    12348,
    12349,
    12350,
    12351,
    12352,
    12353,
    12354
  ],
  "success": true,
  "timestamp": "2025-08-08T11:15:00.000Z"
}
Minimal marketing content

Simple marketing with single banner 

{
  "blocks": [
    {
      "copy": "Welcome to Our Store",
      "image": "https://cdn.example.com/banners/welcome.jpg",
      "type": "banner",
      "uri": "/browse"
    }
  ],
  "load_items": [],
  "success": true,
  "timestamp": "2025-08-08T11:15:00.000Z"
}
Response Schema
Schema Reference:

Marketing content blocks and preload items

Type: object
Required fields:
success timestamp blocks load_items

Properties:

blocks required
load_items required
success required
timestamp required
404 Socket not found
Example Response 
{
  "error_code": "SOCKET_NOT_FOUND",
  "message": "Socket with ID 999 not found for this customer",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Standard error response format

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required
503 Marketing service unavailable
Example Response 
{
  "error_code": "SERVICE_UNAVAILABLE",
  "message": "Marketing service is temporarily unavailable",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Standard error response format

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required