Catalog API Documentation

Browse endpoints, parameters, and live request examples.

GET /sockets/{socket_id}/items/{catalog_item_id}

Get catalog item details

Retrieves detailed information for a specific catalog item including full specifications, pricing, and availability information.

Catalog

Parameters

socket_id required path (integer)

The catalog socket to query

catalog_item_id required path (integer)

The catalog item ID to retrieve

matched_entities query (boolean)

Include matched_entities with category, tag, and brand details for the item's IDs

Responses

200 Item details retrieved successfully
Gift card item details

Digital gift card item details 

{
  "catalog_item": {
    "availability": "in_stock",
    "brand": "Gift Card Express",
    "brand_id": 301,
    "catalog_item_id": 99001,
    "category_ids": [
      90
    ],
    "description": "Digital gift card delivered via email",
    "fulfillment_type": "digital",
    "images": [
      {
        "alt": "Gift Card",
        "is_primary": true,
        "order": 1,
        "urls": {
          "image_150_1_1": "https://cdn.example.com/img/150/gc-100",
          "image_150_3_2": "https://cdn.example.com/img/150c/gc-100",
          "image_300_1_1": "https://cdn.example.com/img/300/gc-100",
          "image_300_3_2": "https://cdn.example.com/img/300c/gc-100",
          "image_500_1_1": "https://cdn.example.com/img/500/gc-100",
          "image_500_3_2": "https://cdn.example.com/img/500c/gc-100",
          "image_75_1_1": "https://cdn.example.com/img/75/gc-100",
          "image_75_3_2": "https://cdn.example.com/img/75c/gc-100"
        }
      }
    ],
    "is_available": true,
    "is_explicit": false,
    "is_limited_stock": false,
    "is_primary": true,
    "is_taxable": false,
    "item_type_id": 300,
    "model": "GC-100",
    "name": "Gift Card - $100",
    "original_points": 10000,
    "original_price": "100.00",
    "points": 10000,
    "price": "100.00",
    "product_id": "GC-100",
    "product_options": {},
    "rank": 100,
    "required_fields": {
      "address_1": false,
      "address_2": false,
      "address_3": false,
      "address_4": false,
      "city": false,
      "country": false,
      "email": true,
      "given_name": true,
      "phone_number": false,
      "postal_code": false,
      "state_or_region": false,
      "surname": true
    },
    "retail_price": "100.00",
    "shipping_estimate": "0.00",
    "supplier_id": 3001,
    "supplier_reference_id": "GCE-100",
    "tag_ids": [
      15
    ],
    "upc": null
  },
  "success": true,
  "timestamp": "2025-08-08T12:00:00.000Z"
}
Standard item details

Detailed information for a catalog item 

{
  "catalog_item": {
    "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"
  },
  "success": true,
  "timestamp": "2025-08-08T12:00:00.000Z"
}
Out of stock item

Item currently unavailable 

{
  "catalog_item": {
    "availability": "out_of_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",
        "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": false,
    "is_explicit": false,
    "is_limited_stock": true,
    "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
    ]
  },
  "success": true,
  "timestamp": "2025-08-08T12:00:00.000Z"
}
Response Schema
Schema Reference:

Detailed information for a specific catalog item

Type: object
Required fields:
success timestamp catalog_item

Properties:

catalog_item ref: CatalogItem required
matched_entities
success required
timestamp required
404 Item not found
Example Response 
{
  "error_code": "ITEM_NOT_FOUND",
  "message": "Item with ID 99999 not found in socket 1",
  "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 Search service unavailable
Example Response 
{
  "error_code": "SERVICE_UNAVAILABLE",
  "message": "Search 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