CatalogSets

The CatalogSets endpoint returns a store's complete menu structure. Unlike store results, CatalogSets are immutable - once created, they never change. This makes them perfect candidates for aggressive caching.

Key Concepts

CatalogSets Are Immutable

A CatalogSet represents a specific version of a store's menu at a point in time. When a restaurant updates their menu, a new CatalogSet is created with a new ID. The old CatalogSet remains valid and unchanged.

This immutability means:

• Cache aggressively - A CatalogSet will never change
• ETags for validation - Use conditional requests to avoid re-downloading unchanged data
• No stale data concerns - If you have the CatalogSet, it's valid

CatalogSet Structure

A CatalogSet uses dictionaries (key-value maps) rather than nested arrays:

interface CatalogSet {
  catalogSetId: string;
  storeId: string;
  catalogs: Record<string, Catalog>;      // Individual menus (Lunch, Dinner, etc.)
  sections: Record<string, Section>;       // Categories (Appetizers, Entrees)
  items: Record<string, Item>;             // Menu items
  modifierGroups: Record<string, ModifierGroup>;  // Customization options
}

This structure enables:

• O(1) lookups - Find any item instantly by ID
• No duplication - Items shared across sections exist once
• Flexible relationships - Modifiers can reference any item

Navigating the Structure

To build a menu from a CatalogSet:

1. Select a Catalog from catalogs (e.g., "Lunch Menu")
2. Iterate through catalog.sectionIds to get sections
3. For each section, iterate through section.itemIds to get items
4. For items with modifiers, use item.modifierGroupIds to get modifier groups

Key insight: Modifier options are also Item objects. This enables pricing on modifiers and nested customization (modifiers that have their own modifiers).

Caching

ETag-Based Caching

The CatalogSets endpoint supports conditional requests:

1. On first request, save the ETag response header
2. On subsequent requests, send If-None-Match: <etag>
3. If unchanged, receive 304 Not Modified (use cached version)

Cache Invalidation

When the catalogSetId from the Stores endpoint changes, the store has updated their menu. Fetch the new CatalogSet using the new ID.

Multiple Catalogs Within a CatalogSet

A CatalogSet may contain multiple Catalogs for different times (Breakfast, Lunch, Dinner). Each Catalog has an availability property indicating when it's active:

interface CatalogAvailability {
  type: 'ALWAYS' | 'SCHEDULED';
  schedule?: ScheduleWindow[];
}

interface ScheduleWindow {
  dayOfWeek: string;    // "MONDAY", "TUESDAY", etc.
  startTime: string;    // "HH:mm"
  endTime: string;      // "HH:mm"
}

Working with Modifiers

ModifierGroups define customization options for menu items:

Property	Description
minimumAllowed	Minimum selections required
maximumAllowed	Maximum selections allowed
enableDuplicateItems	Can select same option multiple times
itemIds	Available modifier options (references to items)

Selection rules:

• min=1, max=1 → Required single choice (e.g., size)
• min=0, max=1 → Optional single choice
• min=0, max=N → Optional multi-select (e.g., toppings)

API Reference

For complete request/response schemas, see the Get CatalogSet endpoint in the API Reference.

Related

• Types - Complete type definitions