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

OptionTypeDescription
limitnumberLimits the number of sessions returned.
offsetnumberSkips a number of sessions for pagination.
fromstringISO date string used to return sessions after a date.
tostringISO date string used to return sessions before a date.
featuredbooleanReturns 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