Catalog API Documentation

Browse endpoints, parameters, and live request examples.

POST /sockets/{socket_id}/items/search

Search catalog items with Filter DSL

Search for catalog items using a Filter DSL for complex boolean queries. This endpoint accepts a JSON body with the filter parameter for advanced filtering.

Filter DSL

The filter parameter supports:

  • Comparison operators: eq, ne, in, not_in, gt, gte, lt, lte, between
  • Boolean operators: and, or (with nesting up to 5 levels)

Allowed Fields

  • brand_id, category_id, tag_id, item_type_id, catalog_item_id (integers)
  • fulfillment_type (string: “physical”, “digital”)
  • price (number), points (integer)

Example Filter

{
  "filter": {
    "and": [
      {"eq": {"category_id": 10493}},
      {"or": [
        {"eq": {"brand_id": 5984}},
        {"eq": {"brand_id": 114}}
      ]},
      {"between": {"price": [50, 200]}}
    ]
  }
}
Catalog

Parameters

socket_id required path (integer)

The catalog socket to search

Request Body

Items search request

Properties

Field Type Required Description
brand string No Filter by brand name (exact match). Use this for brand name search; use filter.eq.brand_id for ID-based filtering.
brand_faceting string
top full
No Include brand facets in response. 'top' returns top brands, 'full' returns all brands with counts.
filter No
is_primary boolean No When true, returns only primary items (excludes variant items). Default: returns all items.
page integer No Page number for pagination. First page is 1.
per_page integer No Number of items per page. Minimum: 1, Maximum: 100, Default: 25.
search string No Full-text search query. Searches item names and descriptions. Combined with filter using AND logic.
sort string
rank asc rank desc price asc price desc points asc points desc name asc name desc
No Sort order for results. Format: 'field direction' where direction is 'asc' or 'desc'.
tag_faceting string
top full
No Include tag facets in response. 'top' returns top tags, 'full' returns all tags with counts.

Example

{
  "brand_faceting": "top",
  "filter": {
    "and": [
      {
        "eq": {
          "fulfillment_type": "physical"
        }
      },
      {
        "between": {
          "price": [
            50,
            200
          ]
        }
      },
      {
        "or": [
          {
            "eq": {
              "brand_id": 5984
            }
          },
          {
            "eq": {
              "brand_id": 114
            }
          }
        ]
      }
    ]
  },
  "is_primary": true,
  "page": 1,
  "per_page": 25,
  "search": "headphones",
  "sort": "price asc",
  "tag_faceting": "top"
}

Responses

200 Search results
Example Response 
{
  "facets": [
    {
      "count": 45,
      "id": "567",
      "name": "AudioTech",
      "type": "brand"
    },
    {
      "count": 120,
      "id": "35",
      "name": "5% Off!",
      "type": "tag"
    }
  ],
  "items": [
    {
      "availability": "In stock",
      "brand": "AudioTech",
      "brand_id": 567,
      "catalog_item_id": 12345,
      "category_ids": [
        10,
        25,
        45
      ],
      "description": "Premium noise-canceling wireless headphones",
      "fulfillment_type": "physical",
      "images": [
        {
          "alt": "Wireless Headphones",
          "is_primary": true,
          "order": 1,
          "urls": {
            "image_150_1_1": "https://cdn.example.com/img/150/12345.jpg",
            "image_150_3_2": "https://cdn.example.com/img/150c/12345.jpg",
            "image_300_1_1": "https://cdn.example.com/img/300/12345.jpg",
            "image_300_3_2": "https://cdn.example.com/img/300c/12345.jpg",
            "image_500_1_1": "https://cdn.example.com/img/500/12345.jpg",
            "image_500_3_2": "https://cdn.example.com/img/500c/12345.jpg",
            "image_75_1_1": "https://cdn.example.com/img/75/12345.jpg",
            "image_75_3_2": "https://cdn.example.com/img/75c/12345.jpg"
          }
        }
      ],
      "is_available": true,
      "is_explicit": false,
      "is_limited_stock": false,
      "is_primary": false,
      "is_taxable": true,
      "item_type_id": 200,
      "model": "AT-WH500",
      "name": "Wireless Bluetooth Headphones",
      "original_points": 2000,
      "original_price": "199.99",
      "points": 1500,
      "price": "149.99",
      "product_id": "prod-567-890",
      "product_options": {},
      "rank": 295,
      "required_fields": {
        "address_1": true,
        "address_2": false,
        "address_3": false,
        "address_4": false,
        "city": true,
        "country": true,
        "email": false,
        "given_name": true,
        "phone_number": false,
        "postal_code": true,
        "state_or_region": true,
        "surname": true
      },
      "retail_price": "249.99",
      "shipping_estimate": "9.99",
      "supplier_id": 2001,
      "supplier_reference_id": "SUP-AT-WH500",
      "tag_ids": [
        35,
        78
      ]
    },
    {
      "availability": "Limited stock",
      "brand": "SoundWave",
      "brand_id": 890,
      "catalog_item_id": 12346,
      "category_ids": [
        10,
        28
      ],
      "description": "Waterproof portable speaker with 12-hour battery",
      "fulfillment_type": "physical",
      "images": [
        {
          "alt": "Portable Speaker",
          "is_primary": true,
          "order": 1,
          "urls": {
            "image_150_1_1": "https://cdn.example.com/img/150/12346.jpg",
            "image_150_3_2": "https://cdn.example.com/img/150c/12346.jpg",
            "image_300_1_1": "https://cdn.example.com/img/300/12346.jpg",
            "image_300_3_2": "https://cdn.example.com/img/300c/12346.jpg",
            "image_500_1_1": "https://cdn.example.com/img/500/12346.jpg",
            "image_500_3_2": "https://cdn.example.com/img/500c/12346.jpg",
            "image_75_1_1": "https://cdn.example.com/img/75/12346.jpg",
            "image_75_3_2": "https://cdn.example.com/img/75c/12346.jpg"
          }
        }
      ],
      "is_available": true,
      "is_explicit": false,
      "is_limited_stock": true,
      "is_primary": false,
      "is_taxable": true,
      "item_type_id": 201,
      "model": "SW-P120",
      "name": "Portable Bluetooth Speaker",
      "original_points": 900,
      "original_price": "89.99",
      "points": 800,
      "price": "79.99",
      "product_id": "prod-890-123",
      "product_options": {},
      "rank": 150,
      "required_fields": {
        "address_1": true,
        "address_2": false,
        "address_3": false,
        "address_4": false,
        "city": true,
        "country": true,
        "email": false,
        "given_name": true,
        "phone_number": false,
        "postal_code": true,
        "state_or_region": true,
        "surname": true
      },
      "retail_price": "119.99",
      "shipping_estimate": "6.99",
      "supplier_id": 2002,
      "supplier_reference_id": "SUP-SW-P120",
      "tag_ids": [
        35
      ]
    }
  ],
  "matched_entities": [
    {
      "discount_percent": null,
      "id": 567,
      "name": "AudioTech",
      "type": "brand"
    },
    {
      "discount_percent": null,
      "id": 890,
      "name": "SoundWave",
      "type": "brand"
    },
    {
      "discount_percent": null,
      "id": 10,
      "name": "Electronics",
      "type": "category"
    },
    {
      "discount_percent": null,
      "id": 25,
      "name": "Audio",
      "type": "category"
    },
    {
      "discount_percent": null,
      "id": 28,
      "name": "Speakers",
      "type": "category"
    },
    {
      "discount_percent": null,
      "id": 45,
      "name": "Headphones",
      "type": "category"
    },
    {
      "discount_percent": "5.00",
      "id": 35,
      "name": "Best Sellers",
      "type": "tag"
    },
    {
      "discount_percent": null,
      "id": 78,
      "name": "Premium Audio",
      "type": "tag"
    }
  ],
  "page": 1,
  "per_page": 25,
  "search_keys": {
    "brand": [
      "AudioTech"
    ],
    "category": "Electronics"
  },
  "searched_entities": [
    {
      "discount_percent": null,
      "id": 567,
      "name": "AudioTech",
      "type": "brand"
    },
    {
      "discount_percent": null,
      "id": 10,
      "name": "Electronics",
      "type": "category"
    }
  ],
  "success": true,
  "timestamp": "2025-08-02T14:28:41.605Z",
  "total_count": 150
}
Response Schema
Schema Reference:

Search results for catalog items with pagination

Type: object
Required fields:
success timestamp total_count page per_page items

Properties:

facets
items required
matched_entities
page required
per_page required
search_keys
searched_entities
success required
timestamp required
total_count required
400 Invalid filter
Invalid field in filter 
{
  "error_code": "INVALID_FILTER_FIELD",
  "message": "Invalid field in filter",
  "success": false,
  "timestamp": "2025-08-05T00:44:25.846238Z"
}
Invalid filter JSON 
{
  "error_code": "INVALID_FILTER_JSON",
  "message": "Invalid filter JSON format",
  "success": false,
  "timestamp": "2025-08-05T00:44:25.846238Z"
}
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
404 Socket not found
Example Response 
{
  "error_code": "ERROR",
  "message": "Search service unavailable",
  "success": false,
  "timestamp": "2025-08-02T14:28:41.605Z"
}
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 Search service unavailable
Example Response 
{
  "error_code": "ERROR",
  "message": "Search service unavailable",
  "success": false,
  "timestamp": "2025-08-02T14:28:41.605Z"
}
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