Catalog API Documentation

Browse endpoints, parameters, and live request examples.

GET /sockets/{socket_id}/items

Search catalog items

Search for catalog items within a specific socket with filtering, sorting, and pagination options. Supports full-text search, category filtering, brand filtering, and price range filtering.

Catalog

Parameters

socket_id required path (integer)

The catalog socket to search

search query (string)

Search query for item names and descriptions

category_id query (integer)

Filter by category ID

brand query (string)

Filter by brand name

brand_id query (integer)

Filter by brand ID

brand_ids query (array)

Filter by multiple brand IDs

item_ids query (array)

Filter by multiple item IDs

tag_id query (integer)

Filter by tag ID

item_type_id query (integer)

Filter by item type ID

fulfillment_type query (string)

Filter by fulfillment type

is_primary query (boolean)

Filter by primary items only

min_price query (string)

Minimum price filter

max_price query (string)

Maximum price filter

min_points query (integer)

Minimum points filter

max_points query (integer)

Maximum points filter

page query (integer)

Page number for pagination

per_page query (integer)

Number of items per page (default: 25, max: 100)

sort query (string)

Sort order (default: 'rank asc')

brand_faceting query (string)

Include brand facets (top/full)

tag_faceting query (string)

Include tag facets (top/full)

filter query

Filter DSL for complex queries. Pass as JSON-encoded string.

Responses

200 Items search response
No items found

Search returned no matching items 

{
  "items": [],
  "page": 1,
  "per_page": 25,
  "success": true,
  "timestamp": "2025-08-05T00:44:25.846238Z",
  "total_count": 0
}
Search results with multiple items

Typical search response with pagination and items 

{
  "items": [
    {
      "availability": "in_stock",
      "brand": "AudioTech",
      "brand_id": 101,
      "catalog_item_id": 12345,
      "category_ids": [
        5,
        12
      ],
      "description": "High-quality noise-canceling headphones with 30-hour battery life",
      "fulfillment_type": "direct",
      "images": [
        {
          "alt": "Premium Wireless Headphones",
          "is_primary": true,
          "order": 1,
          "urls": {
            "image_150_1_1": "https://cdn.example.com/img/150/12345",
            "image_150_3_2": "https://cdn.example.com/img/150c/12345",
            "image_300_1_1": "https://cdn.example.com/img/300/12345",
            "image_300_3_2": "https://cdn.example.com/img/300c/12345",
            "image_500_1_1": "https://cdn.example.com/img/500/12345",
            "image_500_3_2": "https://cdn.example.com/img/500c/12345",
            "image_75_1_1": "https://cdn.example.com/img/75/12345",
            "image_75_3_2": "https://cdn.example.com/img/75c/12345"
          }
        }
      ],
      "is_available": true,
      "is_explicit": false,
      "is_limited_stock": false,
      "is_primary": true,
      "is_taxable": true,
      "item_type_id": 200,
      "model": "AT-WH1000",
      "name": "Premium Wireless Headphones",
      "original_points": 29999,
      "original_price": "299.99",
      "points": 24999,
      "price": "249.99",
      "product_id": "PROD-001",
      "product_options": {},
      "rank": 300,
      "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": "299.99",
      "shipping_estimate": "5.99",
      "supplier_id": 2001,
      "supplier_reference_id": "SUP-AT-WH1000",
      "tag_ids": [
        1,
        3,
        7
      ],
      "upc": "123456789012"
    },
    {
      "availability": "in_stock",
      "brand": "AudioTech",
      "brand_id": 101,
      "catalog_item_id": 12346,
      "category_ids": [
        5,
        13
      ],
      "description": "Portable waterproof speaker with 360-degree sound",
      "fulfillment_type": "direct",
      "images": [
        {
          "alt": "Bluetooth Speaker - Action Image",
          "is_primary": true,
          "order": 1,
          "urls": {
            "image_150_1_1": "https://cdn.example.com/img/150/12346",
            "image_150_3_2": "https://cdn.example.com/img/150c/12346",
            "image_300_1_1": "https://cdn.example.com/img/300/12346",
            "image_300_3_2": "https://cdn.example.com/img/300c/12346",
            "image_500_1_1": "https://cdn.example.com/img/500/12346",
            "image_500_3_2": "https://cdn.example.com/img/500c/12346",
            "image_75_1_1": "https://cdn.example.com/img/75/12346",
            "image_75_3_2": "https://cdn.example.com/img/75c/12346"
          }
        }
      ],
      "is_available": true,
      "is_explicit": false,
      "is_limited_stock": false,
      "is_primary": true,
      "is_taxable": true,
      "item_type_id": 201,
      "model": "AT-BS500",
      "name": "Bluetooth Speaker",
      "original_points": 14999,
      "original_price": "149.99",
      "points": 11999,
      "price": "119.99",
      "product_id": "PROD-002",
      "product_options": {},
      "rank": 300,
      "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": "149.99",
      "shipping_estimate": "3.99",
      "supplier_id": 2002,
      "supplier_reference_id": "SUP-AT-BS500",
      "tag_ids": [
        1,
        8
      ]
    }
  ],
  "page": 1,
  "per_page": 25,
  "success": true,
  "timestamp": "2025-08-05T00:44:25.846238Z",
  "total_count": 150
}
Search results with facets

Search response including facet data for filtering 

{
  "facets": [
    {
      "count": 25,
      "id": "101",
      "name": "AudioTech",
      "type": "brand"
    },
    {
      "count": 18,
      "id": "102",
      "name": "TechGear",
      "type": "brand"
    },
    {
      "count": 45,
      "id": "1",
      "name": "Electronics",
      "type": "tag"
    },
    {
      "count": 30,
      "id": "15",
      "name": "Gift Cards",
      "type": "tag"
    }
  ],
  "items": [
    {
      "availability": "in_stock",
      "brand": "AudioTech",
      "brand_id": 101,
      "catalog_item_id": 12345,
      "category_ids": [
        5,
        12
      ],
      "description": "High-quality noise-canceling headphones with 30-hour battery life",
      "fulfillment_type": "direct",
      "images": [
        {
          "alt": "Premium Wireless Headphones",
          "is_primary": true,
          "order": 1,
          "urls": {
            "image_150_1_1": "https://cdn.example.com/img/150/12345",
            "image_150_3_2": "https://cdn.example.com/img/150c/12345",
            "image_300_1_1": "https://cdn.example.com/img/300/12345",
            "image_300_3_2": "https://cdn.example.com/img/300c/12345",
            "image_500_1_1": "https://cdn.example.com/img/500/12345",
            "image_500_3_2": "https://cdn.example.com/img/500c/12345",
            "image_75_1_1": "https://cdn.example.com/img/75/12345",
            "image_75_3_2": "https://cdn.example.com/img/75c/12345"
          }
        }
      ],
      "is_available": true,
      "is_explicit": false,
      "is_limited_stock": false,
      "is_primary": true,
      "is_taxable": true,
      "item_type_id": 200,
      "model": "AT-WH1000",
      "name": "Premium Wireless Headphones",
      "original_points": 29999,
      "original_price": "299.99",
      "points": 24999,
      "price": "249.99",
      "product_id": "PROD-001",
      "product_options": {},
      "rank": 300,
      "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": "299.99",
      "shipping_estimate": "5.99",
      "supplier_id": 2001,
      "supplier_reference_id": "SUP-AT-WH1000",
      "tag_ids": [
        1,
        3,
        7
      ],
      "upc": "123456789012"
    }
  ],
  "page": 1,
  "per_page": 25,
  "success": true,
  "timestamp": "2025-08-05T00:44:25.846238Z",
  "total_count": 75
}
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
404 Socket not found
Socket doesn't exist or not accessible 
{
  "error_code": "NOT_FOUND",
  "message": "The requested resource was not found.",
  "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
503 Search service unavailable
Search service is down 
{
  "error_code": "SERVICE_UNAVAILABLE",
  "message": "Search service unavailable",
  "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