Catalog Integration

The Commerce API uses a Pull Model for catalog synchronization. This ensures reliability and scalability when handling large menu files.

The Sync Flow

1. You Host the Data: Generate the CatalogSet JSON and host it on a publicly accessible URL (e.g., S3, CloudFront).
2. Notify Us: Send a notification to the Commerce API with the callback URL.
3. We Pull: Gett's servers verify the notification and asynchronously download the data.

The CatalogSet Structure

A CatalogSet is a relational, normalized representation of a menu. Instead of a deep tree, it uses dictionaries (Maps) of entities linked by IDs. This reduces duplication (e.g., the same "Choice of sides" modifier group used by 50 items).

Top Level

{
  "catalogSetId": "uuid",
  "storeId": "your-store-id",
  "catalogs": { ... },
  "sections": { ... },
  "items": { ... },
  "modifierGroups": { ... }
}

Entities

1. Catalogs

The high-level menus (e.g., "Lunch", "Dinner", "All Day").

• Contains a list of sectionIds.
• Can have availability schedules.

2. Sections

Categories like "Appetizers", "Entrees", "Drinks".

• Contains a list of itemIds.
• Can contain nested sectionIds (sub-sections).

3. Items

The sellable products.

• basePrice: The starting price.
• modifierGroupIds: Options available for this item.

4. ModifierGroups

Collections of choices (e.g., "Pizza Toppings", "Size").

• minimumAllowed / maximumAllowed: Constraints.
• itemIds: The choices (which are themselves Items).

Best Practices

• Immutability: Treat every CatalogSet push as a full replacement. We do not support partial patches via this API yet.
• Stable IDs: Try to keep GUIDs consistent for the same items across updates to preserve analytics and user favorites.
• Validation: Ensure your JSON adheres to the Schema. Invalid references (e.g., an Item ID that doesn't exist in the items dictionary) will cause the ingestion to fail.