Skip to main content

​
GET /products/catalogs/:userId

Retrieve a user’s product catalog with optional category filtering.
Requires authentication. Returns products specific to a user’s inventory.

​
Path Parameters

​
userId
string
required
ID of the user whose catalog to retrieve

​
Query Parameters

​
category
string
Filter products by category ID

​
Response

​
products
array
Array of products in the user’s catalog
​
totalProducts
number
Total count of products in catalog
​
userId
string
User ID for this catalog
curl -X GET https://api.yourdomain.com/products/catalogs/usr_123456 \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "userId": "usr_123456",
  "totalProducts": 125,
  "products": [
    {
      "id": "prod_789",
      "name": "Laptop Dell XPS 15",
      "price": 1299.99,
      "stock": 15,
      "category": {
        "id": "cat_electronics",
        "name": "Electronics"
      },
      "variants": [
        {
          "id": "var_001",
          "size": "15 inch",
          "color": "Silver",
          "price": 1299.99,
          "stock": 10
        },
        {
          "id": "var_002",
          "size": "15 inch",
          "color": "Black",
          "price": 1299.99,
          "stock": 5
        }
      ],
      "image": "https://cdn.example.com/laptop-xps15.jpg",
      "description": "High-performance laptop with latest Intel processor",
      "createdAt": "2026-02-15T10:00:00Z",
      "updatedAt": "2026-03-05T14:30:00Z"
    },
    {
      "id": "prod_790",
      "name": "Wireless Keyboard",
      "price": 49.99,
      "stock": 30,
      "category": {
        "id": "cat_accessories",
        "name": "Accessories"
      },
      "variants": [],
      "image": "https://cdn.example.com/keyboard.jpg",
      "description": "Ergonomic wireless keyboard with backlight",
      "createdAt": "2026-02-20T12:00:00Z",
      "updatedAt": "2026-03-01T09:15:00Z"
    }
  ]
}

​
Use Cases

​
Display User’s Entire Catalog

const loadUserCatalog = async (userId) => {
  try {
    const catalog = await fetchCatalogByUser(userId);
    
    console.log(`Total Products: ${catalog.totalProducts}`);
    catalog.products.forEach(product => {
      console.log(`${product.name} - $${product.price} (Stock: ${product.stock})`);
    });
    
    return catalog;
  } catch (error) {
    console.error('Failed to load catalog:', error);
  }
};

​
Filter Catalog by Category

const loadCategoryProducts = async (userId, categoryId) => {
  try {
    const catalog = await fetchCatalogByUser(userId, categoryId);
    
    console.log(`Found ${catalog.totalProducts} products in category`);
    return catalog.products;
  } catch (error) {
    console.error('Failed to load category products:', error);
  }
};

// Usage
const electronics = await loadCategoryProducts('usr_123456', 'cat_electronics');

​
Display Products with Variants

const displayProductsWithVariants = async (userId) => {
  const catalog = await fetchCatalogByUser(userId);
  
  catalog.products.forEach(product => {
    console.log(`Product: ${product.name}`);
    
    if (product.variants && product.variants.length > 0) {
      console.log('  Variants:');
      product.variants.forEach(variant => {
        console.log(`    - ${variant.size} ${variant.color}: $${variant.price} (${variant.stock} in stock)`);
      });
    } else {
      console.log(`  Price: $${product.price} (${product.stock} in stock)`);
    }
  });
};

​
Dynamic Category Filter Component

const CatalogFilter = () => {
  const [userId] = useState('usr_123456');
  const [selectedCategory, setSelectedCategory] = useState(null);
  const [catalog, setCatalog] = useState(null);
  
  useEffect(() => {
    const loadCatalog = async () => {
      const data = await fetchCatalogByUser(userId, selectedCategory);
      setCatalog(data);
    };
    
    loadCatalog();
  }, [userId, selectedCategory]);
  
  return (
    <div>
      <CategoryFilter 
        onSelect={(categoryId) => setSelectedCategory(categoryId)}
      />
      <ProductList products={catalog?.products || []} />
    </div>
  );
};

​
Catalog Response Structure

​
Product Object Fields

FieldTypeDescription
idstringUnique product identifier
namestringProduct name
pricenumberBase product price
stocknumberAvailable inventory
categoryobjectCategory information
variantsarrayProduct variations (size, color, etc.)
imagestringProduct image URL
descriptionstringProduct description
createdAtstringCreation timestamp
updatedAtstringLast update timestamp

​
Variant Object Fields

FieldTypeDescription
idstringUnique variant identifier
sizestringVariant size
colorstringVariant color
pricenumberVariant-specific price
stocknumberVariant-specific stock

​
Integration with Redux

// Redux Action
export const fetchCatalogByUser = (userId, category = null) => async (dispatch) => {
  try {
    dispatch({ type: "CATALOG_REQUEST" });
    
    const url = category
      ? `/products/catalogs/${userId}?category=${category}`
      : `/products/catalogs/${userId}`;
    
    const { data } = await api.get(url);
    
    dispatch({
      type: "CATALOG_SUCCESS",
      payload: data,
    });
  } catch (error) {
    dispatch({
      type: "CATALOG_FAILURE",
      payload: error.response?.data?.message || error.message,
    });
  }
};

// Redux Reducer
const catalogReducer = (state = initialState, action) => {
  switch (action.type) {
    case "CATALOG_REQUEST":
      return { ...state, loading: true, error: null };
    
    case "CATALOG_SUCCESS":
      return {
        ...state,
        loading: false,
        products: action.payload.products,
        totalProducts: action.payload.totalProducts,
        userId: action.payload.userId,
      };
    
    case "CATALOG_FAILURE":
      return { ...state, loading: false, error: action.payload };
    
    default:
      return state;
  }
};

​
Error Codes

StatusDescription
200Success - Catalog retrieved
400Bad Request - Invalid parameters
401Unauthorized - Missing/invalid token
404Not Found - User or category not found
500Server Error - Internal error occurred

​
Performance Tips

Cache catalog responses on the frontend to reduce API calls. Invalidate cache when products are updated.
When displaying large catalogs, use category filtering to reduce response size and improve load times.
For very large catalogs, consider implementing pagination to load products in batches.

Build docs developers (and LLMs) love

Get started for freeTalk to us