This guide explains the structure of responses from the Catalog API. All successful API calls return responses with a consistent format to make integration straightforward for your AI shopping agents.

​
Success Response Format

When your API request is successful, you’ll receive a 200 OK response with a JSON body containing:

{
  "products": [ ... ],  // Array of product objects
  "meta": { ... }       // Metadata about the results
}

​
The products Array

The products array contains a list of product objects matching your search and filter criteria. Each product has a comprehensive structure with flattened attributes:

{
  "id": "813",
  "title": "Giuseppa Dress",
  "description": "Long dress with thin straps. Fluid silk fabric. V-neckline at the front. Lined. Length from the shoulder: 119 cm / 46.8 in (size EU36/UK8). Made in China. Care instructions: Hand wash in cold water.",
  "vendor": "Sezane",
  "url": "https://www.sezane.com/us/product/giuseppa-dress/ecru-polka-dots-on-chocolate-print",
  "is_available": true,
  "image_url": "https://media.sezane.com/image/upload/c_fill,d_placeholder_dark.png,fl_progressive:semi,h_816,q_auto:best,w_582/cbwis0utxwljhi2nxbx4.jpg",
  "attributes.aesthetic": "feminine",
  "attributes.age_group": "adult",
  "attributes.color_family": "brown",
  "attributes.fit": "fluid",
  "attributes.gender": "women",
  "attributes.material": "silk",
  "attributes.mood": "romantic",
  "attributes.occasion": "everyday",
  "attributes.pattern": "polka dots on chocolate print",
  "attributes.season": "spring",
  "attributes.size_type": "EU/UK",
  "attributes.style": "long dress",
  "attributes.trend": "classic",
  "created_at": 1745119358,
  "updated_at": 1745882098,
  "price_currency": "USD",
  "price_display": 295,
  "price_value": 295,
  "variants_in_stock": [true, true, true, true, true, true, true],
  "variants_price_display": [295, 295, 295, 295, 295, 295, 295],
  "variants_size": ["2", "4", "6", "8", "10", "12", "14"],
  "variants_title": ["Us Product Giuseppa Dress Ecru Polka Dots On Chocolate Print"]
}

​
Product Object Fields

​
id
string

Unique identifier for the product

​
title
string

Product title or name

​
description
string

Detailed product description

​
vendor
string

Brand or vendor name

​
url
string

URL to the product detail page

​
is_available
boolean

Whether the product is currently available

​
image_url
string

URL to the main product image

​
attributes.*
varies

Flattened product attributes using dot notation. Common attributes include:

​
created_at
integer

Unix timestamp when the product was created

​
updated_at
integer

Unix timestamp when the product was last updated

​
price_currency
string

Currency code for the product’s price (e.g., “USD”)

​
price_display
number

Display price for the product

​
price_value
number

Numeric value of the product price

​
variants_in_stock
array

Array of boolean values indicating if each size variant is in stock

​
variants_price_display
array

Array of price values for each variant

​
variants_size
array

Array of available size options

​
variants_title
array

Array of titles for each variant

​
The meta Object

The meta object contains metadata about the results:

"meta": {
  "totalItems": 50,
  "totalPages": 15,
  "currentPage": 1,
  "pageSize": 10
}
​
totalItems
integer

Total number of products matching the search and filter criteria across all pages. Note: This value is capped at 50 regardless of the actual total.

​
totalPages
integer

Total number of pages available based on totalItems and pageSize.

​
currentPage
integer

The current page number (matches the page parameter from the request).

​
pageSize
integer

Number of items per page.

​
Empty Results

If your query doesn’t match any products, you’ll still get a successful response (200 OK), but with an empty products array:

{
  "products": [],
  "meta": {
    "totalItems": 0,
    "totalPages": 0,
    "currentPage": 1,
    "pageSize": 10
  }
}

​
Error Responses

When an error occurs, the API returns an appropriate HTTP status code and a JSON body with error details:

​
Authentication Error (401 Unauthorized)

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key"
}

​
Validation Error (400 Bad Request)

{
  "error": "Bad Request",
  "message": "Invalid request parameters",
  "details": {
    "price_min": "Must be a positive number"
  }
}

​
Rate Limiting Error (429 Too Many Requests)

{
  "error": "Rate Limit Exceeded",
  "message": "You have exceeded your rate limit",
  "retry_after": 60
}

​
Server Error (500 Internal Server Error)

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

​
Working with Responses

​
Handling Pagination

Use the meta object to implement pagination controls:

const totalPages = response.meta.totalPages;
const currentPage = response.meta.currentPage;

// Check if there are more pages
const hasNextPage = currentPage < totalPages;
const hasPrevPage = currentPage > 1;

// Calculate next/prev page numbers
const nextPage = hasNextPage ? currentPage + 1 : null;
const prevPage = hasPrevPage ? currentPage - 1 : null;

​
Displaying Products

The flattened structure makes it straightforward to display product information:

// Example: Rendering basic product info
response.products.forEach(product => {
  console.log(`${product.title} - $${product.price_display} ${product.price_currency}`);
  console.log(`  Vendor: ${product.vendor}`);
  console.log(`  Color: ${product["attributes.color_family"]}`);
  console.log(`  Available: ${product.is_available ? 'Yes' : 'No'}`);
  
  // Display the main image URL
  const mainImageUrl = product.image_url || 'no-image.jpg';
  
  // Get available sizes
  const availableSizes = product.variants_size
    .filter((_, index) => product.variants_in_stock[index])
    .join(', ');
  
  console.log(`  Available sizes: ${availableSizes}`);
});