Categories

Return dish category names and counts for your chain, optionally scoped to a single restaurant. Use this to build category navigation in your menu UI (for example, “Breakfast (12)”, “Lunch (24)”).

Query

query SmartMenuCategories {
  categories {
    name
    count
    ordinal
  }
}

This query requires an API key scoped to your chain in the Authorization header. Optionally include X-Session-ID for analytics and personalization; you do not need to pass chain or session in the GraphQL query itself.

Parameters

Parameter	Type	Required	Description
`restaurantId`	ID	No	If provided, categories are aggregated for this restaurant only. If omitted, categories are aggregated for the chain’s widget (all widget dishes).

Response

type WidgetCategory {
  name: String!   # Category name
  count: Int!     # Number of dishes in this category
  ordinal: Int!   # 1-based display order after alphabetical sort
}

Example

query {
  categories {
    name
    count
    ordinal
  }
}

{
  "data": {
    "categories": [
      { "name": "Specials", "count": 5, "ordinal": 0 },
      { "name": "Appetizers", "count": 12, "ordinal": 1 },
      { "name": "Salads", "count": 8, "ordinal": 2 },
      { "name": "Bowls", "count": 6, "ordinal": 3 },
      { "name": "Entrees", "count": 15, "ordinal": 4 },
      { "name": "Sides", "count": 10, "ordinal": 5 },
      { "name": "Desserts", "count": 4, "ordinal": 6 },
      { "name": "Beverages", "count": 8, "ordinal": 7 }
    ]
  }
}

Filtering by Category

Use the category parameter in the search query to filter dishes:

query SaladDishes {
  search(
    category: "Salads"
    preferences: {
      diets: [VEGETARIAN]
    }
  ) {
    matches {
      dish {
        id
        name
        category
      }
    }
    counts { matches, total }
  }
}

Category Counts with Preferences

Category counts returned by categories represent total dishes, not dishes matching any preference filters. For filtered counts, use the search query with a category filter.

To get counts that respect preferences, query each category:

query CategoryCounts {
  salads: search(
    category: "Salads"
    preferences: { diets: [VEGETARIAN] }
  ) {
    counts { matches }
  }

  bowls: search(
    category: "Bowls"
    preferences: { diets: [VEGETARIAN] }
  ) {
    counts { matches }
  }
}

Display Recommendations

Use Ordinal for Order

Display categories in ordinal order to match the restaurant’s intended menu layout.

Show Match Counts

Consider showing “X matches” next to each category when filters are active.

Hide Empty Categories

Optionally hide categories with 0 matches when dietary filters are applied.

Sticky Navigation

For long menus, consider a sticky category bar for easy navigation.

Overview

Core Concepts

SmartMenu API

GuestIQ

Atlas

Query

Parameters

Response

Example

Filtering by Category

Category Counts with Preferences

Display Recommendations

Use Ordinal for Order

Show Match Counts

Hide Empty Categories

Sticky Navigation

​Query

​Parameters

​Response

​Example

​Filtering by Category

​Category Counts with Preferences

​Display Recommendations

Use Ordinal for Order

Show Match Counts

Hide Empty Categories

Sticky Navigation

Query

Parameters

Response

Example

Filtering by Category

Category Counts with Preferences

Display Recommendations