Skip to main content

​
Why Sessions Matter

In e-commerce, understanding the customer journey transformed how businesses operate. Companies like Amazon don’t just track what you buy—they track every click, every search, every item you lingered on. This data powers personalization, recommendation engines, and targeted marketing that drives billions in revenue. EveryBite brings this same approach to dining—but with a critical difference. Traditional loyalty identifies guests after they purchase. EveryBite identifies them before they browse. Sessions are how we understand the guest across every touchpoint—your mobile app, your website, your kiosk, your POS, even voice ordering. When a guest opens your app on Monday, browses your kiosk on Wednesday, and orders through your website on Friday, sessions link all of that behavior into a unified profile. But we go further. When you create a session, we don’t just return a session ID—we return real-time intelligence about who this guest is:
  • Identity — Is this a known guest? A returning visitor? A loyalty member?
  • Segments — What are their dietary needs, preferences, and behavioral patterns?
  • History — What have they ordered before? What do they customize? What’s their average spend?
  • Recommendations — What should you show them first?
This is GuestIQ—our real-time guest intelligence platform that delivers actionable insights the moment a guest touches your menu. This foundation enables everything else:
  • Instant Personalization — Show relevant dishes from the first screen, not after login
  • Real-time Segmentation — Know their segments before they place an order
  • Predictive Insights — Anticipate what a guest wants before they search
  • Loyalty Enrichment — Feed behavioral data into your CRM in real-time
  • Cross-platform Continuity — Recognize the same guest across app, web, kiosk, and more
Every runtime API call requires a sessionId that binds this context to the request. Just include X-Session-ID in your headers, and we handle the rest.

​
What Sessions Capture

Each session captures context from the touchpoint and links it to everything else we know about this guest:
ContextWhat It Tells Us
PlatformWhere is this guest interacting? iOS, Android, web, kiosk, POS, voice?
Chain & LocationWhich restaurant and location are they browsing?
Guest IdentityGuest (inferred from device) or authenticated (known via Passport)?
Session BehaviorWhat are they searching for? What filters do they apply? What do they click?
Historical PatternsHow does this session connect to their past behavior across all platforms?
Enriched DataWhat do loyalty data and industry trends tell us about guests like this?
This is how we turn individual API calls into a complete understanding of the guest—and why consistent session tracking across all your touchpoints is essential.

​
Session Lifecycle

​
Starting a Session

Initialize a session when a guest begins browsing. Pass the chain, platform, and guest context—we generate a unique session ID and return real-time GuestIQ intelligence: 
mutation StartSession {
  startSession(input: {
    chainId: "honeygrow"
    restaurantId: "loc_philly_walnut"  # Optional: specific location
    guestId: "loyalty_12345"            # Your guest or loyalty ID
    passportId: "passport_abc"          # EveryBite Passport ID, if they have one
    platform: IOS                       # IOS, ANDROID, WEB, KIOSK, POS, VOICE
    appVersion: "3.2.1"
  }) {
    sessionId
    chainId
    restaurantId

    # GuestIQ: Real-time intelligence
    guestiq {
      identity {
        guestId
        identifiedVia
        confidence
        isReturning
      }
      segments {
        primary
        compound
      }
      cohorts
      history {
        lastVisit
        visitCount
        favoriteDishes
        avgOrderValue
        customizationRate
      }
      recommendations {
        type
        dishId
        reason
      }
    }
  }
}

{
  "data": {
    "startSession": {
      "sessionId": "sess_7f3a9c2e-8b1d-4e5f-a6c0-9d2e8f1a3b5c",
      "chainId": "honeygrow",
      "restaurantId": "loc_philly_walnut",
      "guestiq": {
        "identity": {
          "guestId": "guest_abc123",
          "identifiedVia": "LOYALTY_ID",
          "confidence": 0.98,
          "isReturning": true
        },
        "segments": {
          "primary": ["wheat-free", "high-protein", "frequent-visitor"],
          "compound": [
            "wheat-free+high-protein",
            "wheat-free+frequent-visitor"
          ]
        },
        "cohorts": ["health-conscious-regulars", "weekday-lunch-crowd"],
        "history": {
          "lastVisit": "2026-01-20T12:30:00Z",
          "visitCount": 12,
          "favoriteDishes": ["dish_stir_fry", "dish_power_bowl"],
          "avgOrderValue": 18.50,
          "customizationRate": 0.73
        },
        "recommendations": [
          {
            "type": "HIGHLIGHT",
            "dishId": "dish_new_bowl",
            "reason": "Matches wheat-free + high-protein preferences"
          }
        ]
      }
    }
  }
}
GuestIQ is optional but powerful. If you don’t need real-time intelligence, simply omit the guestiq fields from your query. But if you want to personalize from the first screen, it’s all there waiting for you.
The sessionId is a UUID we generate—guaranteed unique across all sessions. Store it and include it in your headers for all subsequent API calls: 
X-Session-ID: sess_7f3a9c2e-8b1d-4e5f-a6c0-9d2e8f1a3b5c
That’s it. Your session is now active, and all the context (chain, location, platform, guest) is bound to it.

​
Using Sessions in Queries

Once you’ve configured your headers, your GraphQL queries are clean—just the data you want: 
query SearchDishes {
  search(filters: {
    diets: [VEGETARIAN]
  }) {
    matches {
      dish { name }
    }
  }
}

{
  "data": {
    "search": {
      "matches": [
        { "dish": { "name": "Garden Salad" } },
        { "dish": { "name": "Mediterranean Quinoa Bowl" } },
        { "dish": { "name": "Veggie Wrap" } },
        { "dish": { "name": "Roasted Vegetable Plate" } }
      ]
    }
  }
}
The session context (chain, location, guest identity) comes from your headers, not the query. This keeps your queries focused on what you’re asking for, not repeating context on every call.

​
Guest vs Authenticated Sessions

Sessions work differently depending on whether the user is authenticated:

Guest Sessions

No Passport token provided
  • Sessions tracked by device/browser fingerprint
  • Multiple sessions compiled into inferred profile
  • Behavioral patterns used for personalization
  • Limited cross-device continuity

Authenticated Sessions

Passport token provided
  • Sessions tied to verified user identity
  • Complete history preserved
  • Cross-device continuity
  • Loyalty program integration

​
Guest Session Intelligence

Even without authentication, we compile sessions to understand guest patterns:

​
Authenticated Session Benefits

When you include passportId in startSession, the session unlocks additional capabilities. Your queries stay the same—the personalization comes from the session context: 
query AuthenticatedSearch {
  search(filters: {
    diets: [VEGETARIAN]
  }) {
    matches {
      dish { name }
      matchStatus  # Now based on Passport preferences
    }
  }
}

{
  "data": {
    "search": {
      "matches": [
        { "dish": { "name": "Garden Salad" }, "matchStatus": "MATCH" },
        { "dish": { "name": "Mediterranean Quinoa Bowl" }, "matchStatus": "MATCH" },
        { "dish": { "name": "Grilled Veggie Wrap" }, "matchStatus": "ALMOST_MATCH" }
      ]
    }
  }
}

​
Runtime Headers

Once you have a session, your runtime API calls only need three headers: 
Authorization: pk_your_api_key
Content-Type: application/json
X-Session-ID: sess_7f3a9c2e-8b1d-4e5f-a6c0-9d2e8f1a3b5c
HeaderRequiredDescription
AuthorizationYesYour API key
Content-TypeYesapplication/json
X-Session-IDYesSession identifier from startSession
All other context—chain, platform, guest identity, passport—is already bound to your session. You don’t need to pass it on every call.
Why so simple? You passed all the context when you created the session. Now every API call just needs the session ID—we handle the rest.

​
When to Start a New Session

Start a new session when:
  • User opens your app/website
  • User begins a new ordering flow
  • Previous session has timed out (30 minutes inactivity)
  • User switches to a different restaurant chain

​
Best Practices

One Session Per Flow

Start a new session when the user begins ordering, not on every page view.

Persist Guest ID

Store the guest ID locally and reuse it across sessions for better personalization.

Handle Timeout Gracefully

If a session expires, start a new one transparently - don’t interrupt the user.

Include Location When Known

Pass restaurantId if the user has selected a specific location for better analytics.