Catalog API Documentation
Browse endpoints, parameters, and live request examples.
Catalog Management
Understanding sockets, categories, tags, brands, and how to search the catalog effectively
Understanding Catalog Sockets
A socket is a specific catalog configuration that determines what products are available, their pricing, and how they're organized. Think of it as a customized product catalog tailored for specific use cases, regions, or customer segments.
First Step: List your available sockets using GET /sockets to find the socket_id you'll use for all catalog operations.
Each socket has its own product selection and availability, pricing and currency configuration, category and tag organization, brand partnerships and exclusions, and search and filter capabilities. This allows you to serve different customer segments, regions, or use cases with tailored product catalogs while maintaining a single API integration.
Categories, Tags, and Brands
Categories
Categories are hierarchical groupings of products. Each category has:
-
category_id- Unique identifier for filtering -
parent_id- Links to parent category for hierarchy -
name- Display name for UI
Get all categories: GET /sockets/{socket_id}/categories
Tags
Tags are flexible labels for cross-category product attributes like "New Arrival", "On Sale", or "Eco-Friendly". Tags are particularly useful for finding discounted items, discount tags often include the percentage off in the tag name (e.g., "20% Off", "Sale - 50% Discount"). Each tag has:
-
tag_id- Unique identifier for filtering -
tag_category_id- Groups related tags together -
name- Display name for UI (may include discount percentages) -
discount_percent- Items with this tag will be on sale at this percentage discount.
Get all tags: GET /sockets/{socket_id}/tags
Brands
Brands represent product manufacturers or vendors. Each brand has:
-
brand_id- Unique identifier for filtering -
name- Brand name for display
Get all brands: GET /sockets/{socket_id}/brands
Searching the Catalog
The GET /sockets/{socket_id}/items endpoint provides search and filtering capabilities:
Search Parameters
-
search: - Free-text search across product names, descriptions, and SKUs
-
category_id: - Filter by specific category (includes subcategories)
-
tag_id: - Filter by specific tag
-
brand_id: - Filter by specific brand
-
item_type_id: - Filter by item type (e.g., physical products, gift cards)
-
is_primary: - Filter for primary items only (true/false)
-
min_price/max_price: - Price range filtering
-
min_points/max_points: - Point range filtering
-
sort: - Sort by: relevance, price_asc, price_desc, name_asc, name_desc
-
offset/limit: - Pagination (default limit: 20, max: 100)
"https://api.catalogapi.com/sandbox/api/v2/sockets/1/items?
search=electronics&
category_id=123&
brand_id=67&
max_price=500&
sort=price_asc&
limit=50"
Getting Complete Lists
To build filter UIs or understand the complete catalog structure, retrieve full lists of:
Try the Live Demo
Visit the "Catalog Sockets" section from your dashboard to explore a live, interactive catalog with real data. This demo provides visual product browsing with images and descriptions, interactive filters for categories, tags, and brands, live API request/response logging in the developer panel, and real-time search with all the parameters documented above. The developer panel shows the exact API calls being made, so you can see how all these concepts work together in a real application.