Sessions

Use the Boxpressd Sites SDK to display recent smoke session activity for the business associated with your API key. Sessions can be associated with venues, brands, cigars, and user activity depending on the data available in Boxpressd.

Server Function

Use getBoxpressdSessions when fetching sessions in server components, loaders, API routes, or other server-side code.

import { getBoxpressdSessions } from "@boxpressd/sites-sdk/sessions"

export default async function SessionsPage() {
  const sessions = await getBoxpressdSessions({
    limit: 10
  })

  return (
    <section>
      {sessions.map((session) => (
        <article key={session.id}>
          <p>{session.user.displayName} smoked {session.cigar?.name}</p>
          <p>{session.createdAt}</p>
        </article>
      ))}
    </section>
  )
}

Function Signature

getBoxpressdSessions(options?: GetBoxpressdSessionsOptions): Promise<BoxpressdSession[]>

Options

Option	Type	Description
`limit`	`number`	Limits the number of sessions returned.
`offset`	`number`	Skips a number of sessions for pagination.
`from`	`string`	ISO date string used to return sessions after a date.
`to`	`string`	ISO date string used to return sessions before a date.
`featured`	`boolean`	Returns only featured sessions when supported.

React Hook

Use useSessions when fetching sessions from client components.

"use client"

import { useSessions } from "@boxpressd/sites-sdk/sessions"

export function RecentSessions() {
  const {
    data: sessions,
    isLoading,
    error
  } = useSessions({
    limit: 10
  })

  if (isLoading) {
    return <p>Loading sessions...</p>
  }

  if (error) {
    return <p>Unable to load sessions.</p>
  }

  return (
    <section>
      {sessions?.map((session) => (
        <article key={session.id}>
          <p>{session.user.displayName} smoked {session.cigar?.name}</p>
          <p>{session.createdAt}</p>
        </article>
      ))}
    </section>
  )
}

Hook Signature

useSessions(options?: UseSessionsOptions): {
  data: BoxpressdSession[] | undefined
  isLoading: boolean
  error: Error | null
  refetch: () => void
}

useSessions is planned for the SDK and may not be available until a future release.

Session Object

type BoxpressdSession = {
  id: string
  createdAt: string
  startedAt?: string
  endedAt?: string
  durationSeconds?: number
  rating?: number
  note?: string
  user: {
    id?: string
    displayName: string
    avatarUrl?: string
  }
  cigar?: {
    id: string
    name: string
    brandName?: string
    imageUrl?: string
  }
  venue?: {
    id: string
    name: string
  }
}

Username Fallback

The SDK normalizes user display names when session data is returned. The display name is resolved in this order:

display_name → first_name + last initial → "Boxpressd User"

Example: Recent Sessions

const sessions = await getBoxpressdSessions({
  limit: 5
})

Example: Date Range

const sessions = await getBoxpressdSessions({
  from: "2026-07-01",
  to: "2026-07-31",
  limit: 20
})

Internally, this SDK helper calls the Boxpressd API endpoint for the resolved business:

GET /{businessType}s/{businessId}/sessions

For example:

GET /venues/stogies-chapin/sessions?limit=10

or:

GET /brands/dreamer-cigars/sessions?limit=10

Most SDK users should use getBoxpressdSessions or useSessions instead of calling the API directly.

Best Practices

Use sessions as social proof on venue or brand websites.
Keep public session feeds recent and concise.
Gracefully hide the section when no sessions are available.
Avoid exposing sensitive user details.
Use the SDK’s normalized display name instead of manually building user names.

Next Steps

Continue to:

Events
Check-ins
Components Overview
API Reference

Getting started

Core concepts

Components

Data fetching

Examples

Server Function

Function Signature

Options

React Hook

Hook Signature

Session Object

Username Fallback

Example: Recent Sessions

Example: Date Range

Best Practices

Next Steps

​Server Function

​Function Signature

​Options

​React Hook

​Hook Signature

​Session Object

​Username Fallback

​Example: Recent Sessions

​Example: Date Range

​Related API Endpoint

​Best Practices

​Next Steps

Server Function

Function Signature

Options

React Hook

Hook Signature

Session Object

Username Fallback

Example: Recent Sessions

Example: Date Range

Related API Endpoint

Best Practices

Next Steps