Skip to main content
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.

Guest Preferences

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]
}
DietDescription
VEGANNo animal products
VEGETARIANNo meat or fish (may include dairy/eggs)
PESCATARIANFish but no other meat

​
Allergen Exclusions

What allergens must be avoided? 
preferences: {
  excludeAllergens: [PEANUT, DAIRY, EGG, SHELLFISH]
}
AllergenDescription
DAIRYMilk and milk products
EGGEggs and egg products
FISHFish
SHELLFISHShrimp, crab, lobster, etc.
TREE_NUTAlmonds, walnuts, cashews, etc.
PEANUTPeanuts and peanut products
WHEATWheat and gluten-containing ingredients
SOYSoybeans and soy products
SESAMESesame 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:
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:
StatusMeaning
MATCHFully compatible with all preferences
ALMOST_MATCHPartial match with exceptions (e.g., removable ingredient)
NOT_MATCHContains 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:
Preferences UI
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