Guest Preferences

Guest Preferences represent an individual user’s dietary needs, restrictions, and nutritional goals. Pass these with your queries to get personalized results and match status calculations.

The Two-Layer Model

EveryBite uses a two-layer approach to personalization:

Chain & API Key

App-level, staticIdentifies which restaurant chain’s menu data your app can access via the Authorization API key header.

User-level, dynamicThe individual guest’s dietary needs. Passed per-request as preferences or loaded from their profile.

Preference Types

Dietary Preferences (Diets)

What type of diet does the guest follow?

preferences: {
  diets: [VEGETARIAN]
}

Diet	Description
`VEGAN`	No animal products
`VEGETARIAN`	No meat or fish (may include dairy/eggs)
`PESCATARIAN`	Fish but no other meat

Allergen Exclusions

What allergens must be avoided?

preferences: {
  excludeAllergens: [PEANUT, DAIRY, EGG, SHELLFISH]
}

Allergen	Description
`DAIRY`	Milk and milk products
`EGG`	Eggs and egg products
`FISH`	Fish
`SHELLFISH`	Shrimp, crab, lobster, etc.
`TREE_NUT`	Almonds, walnuts, cashews, etc.
`PEANUT`	Peanuts and peanut products
`WHEAT`	Wheat and gluten-containing ingredients
`SOY`	Soybeans and soy products
`SESAME`	Sesame seeds and sesame oil

Allergen exclusion is critical for guest safety. Our system flags allergens with a confidence score. Always display appropriate warnings and encourage guests to verify with restaurant staff.

Nutrient Targets

What nutritional goals does the guest have?

preferences: {
  calorieRange: { min: 300, max: 600 },
  nutrientRanges: {
    protein: { min: 20 },        # At least 20g protein
    carbohydrates: { max: 50 },  # No more than 50g carbs
    fatTotal: { max: 30 }        # No more than 30g total fat
  }
}

Session Tracking

Every API call can include an X-Session-ID header that enables analytics and personalization tracking. Sessions bind guest identity and behavioral context to every request; chain context comes from your API key, and restaurant context is provided via query arguments like restaurantId. See Sessions for details. How session data is used depends on whether the user is anonymous or authenticated:

Authenticated User
Anonymous User

Sessions are directly tied to the known guest via authentication token. Complete history preserved.

Passing Preferences

Option 1: Per-Request (Anonymous Users)

Pass preferences directly with each query. For anonymous users, we track sessions and use behavioral patterns to build an inferred profile over time.

query {
  search(
    preferences: {
      diets: [VEGETARIAN]
      excludeAllergens: [PEANUT, DAIRY]
      calorieRange: { max: 600 }
    }
  ) {
    matches {
      dish { name }
      matchStatus
    }
  }
}

Session intelligence: Even without authentication, we compile sessions from the same device/browser to understand preference patterns. A guest who consistently excludes dairy across multiple sessions may see dairy-free options surfaced more prominently.

Option 2: From Profile (Authenticated Users)

When you include a stable identifier like guestId in startSession, preferences are loaded from the guest’s saved profile. All sessions are tied directly to this known user, enabling:

Persistent preferences across devices
Complete dining history
Loyalty program integration

# Session started with guestId - preferences loaded automatically
query {
  search {
    matches {
      dish { name }
      matchStatus  # Based on their saved preferences
    }
  }
}

With GuestIQ, preferences are set once and work everywhere. A guest sets “I’m allergic to peanuts” in their profile, and it’s applied at every participating restaurant. All session data is associated with their verified identity.

Option 3: Combined (Profile + Overrides)

Start with saved preferences but add request-specific filters. The authenticated user’s session still tracks these temporary overrides for analytics.

# Session started with guestId - add per-request overrides
query {
  search(
    preferences: {
      # These override/extend saved preferences for this request
      calorieRange: { max: 400 }  # Stricter than usual today
    }
  ) {
    matches {
      dish { name }
      matchStatus
    }
  }
}

How Preferences Affect Results

When you pass preferences, two things happen:

1. Filtering

Dishes that don’t meet criteria are filtered out or flagged:

# With excludeAllergens: [PEANUT]
# Dishes containing peanuts are marked as NOT_MATCH

2. Match Status Calculation

Every dish gets a matchStatus based on how well it fits the preferences:

Status	Meaning
`MATCH`	Fully compatible with all preferences
`ALMOST_MATCH`	Partial match with exceptions (e.g., removable ingredient)
`NOT_MATCH`	Contains excluded allergens or is otherwise incompatible

See Match Status for details.

Building a Preferences UI

Use the filterOptions query to build your preferences UI dynamically:

query {
  filterOptions {
    diets {
      type
      displayName
      description
      isEnabled  # Is this filter available for this chain's SmartMenu widget?
    }
    allergens {
      type
      displayName
      icon       # Icon or emoji identifier for UI
      isEnabled
    }
    nutrients {
      type
      displayName
      unit           # e.g. "kcal", "g", "mg"
      defaultMin
      defaultMax
    }
  }
}

Example UI Pattern

Based on our SmartMenu implementation:

Components:

Diet toggles - Buttons for Vegan, Vegetarian, etc.
Allergen checkboxes - Multi-select for allergens to exclude
Nutrient sliders - Range inputs for calories, protein, etc.
Active filter chips - Show selected filters with remove buttons

Getting Started

Core Concepts

Guides

Guest Preferences

The Two-Layer Model

Chain & API Key