> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxpressd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Fetch and display Boxpressd events using SDK server functions and React hooks.

Use the Boxpressd Sites SDK to fetch and display events for the business associated with your API key.

Events are automatically scoped to the resolved business context, so you do not need to manually provide a venue ID, brand ID, or business ID.

## Server Function

Use `getBoxpressdEvents` when fetching events in server components, loaders, API routes, or other server-side code.

```tsx theme={null}
import { getBoxpressdEvents } from "@boxpressd/sites-sdk/events"

export default async function EventsPage() {
  const events = await getBoxpressdEvents({
    status: "upcoming",
    limit: 6
  })

  return (
    <section>
      {events.map((event) => (
        <article key={event.id}>
          <h2>{event.title}</h2>
          <p>{event.description}</p>
        </article>
      ))}
    </section>
  )
}
```

## Function Signature

```ts theme={null}
getBoxpressdEvents(options?: GetBoxpressdEventsOptions): Promise<BoxpressdEvent[]>
```

## Options

| Option | Type | Description |
| - | - | - |
| `status` | `"upcoming" \| "past" \| "all"` | Filters events by status. |
| `limit` | `number` | Limits the number of events returned. |
| `offset` | `number` | Skips a number of events for pagination. |
| `featured` | `boolean` | Returns only featured events when supported. |
| `from` | `string` | ISO date string used to return events after a date. |
| `to` | `string` | ISO date string used to return events before a date. |

## React Hook

Use `useEvents` when fetching events from client components.

```tsx theme={null}
"use client"

import { useEvents } from "@boxpressd/sites-sdk/events"

export function UpcomingEvents() {
  const {
    data: events,
    isLoading,
    error
  } = useEvents({
    status: "upcoming",
    limit: 6
  })

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

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

  return (
    <section>
      {events?.map((event) => (
        <article key={event.id}>
          <h2>{event.title}</h2>
          <p>{event.description}</p>
        </article>
      ))}
    </section>
  )
}
```

## Hook Signature

```ts theme={null}
useEvents(options?: UseEventsOptions): {
  data: BoxpressdEvent[] | undefined
  isLoading: boolean
  error: Error | null
  refetch: () => void
}
```

<Note>
  `useEvents` is planned for the SDK and may not be available until a future release.
</Note>

## Event Object

```ts theme={null}
type BoxpressdEvent = {
  id: string
  title: string
  description?: string
  startsAt: string
  endsAt?: string
  timezone?: string
  locationName?: string
  address?: string
  imageUrl?: string
  featured?: boolean
  externalUrl?: string
  ticketUrl?: string
}
```

## Example: Featured Events

```tsx theme={null}
const events = await getBoxpressdEvents({
  status: "upcoming",
  featured: true,
  limit: 3
})
```

## Example: Calendar Range

```tsx theme={null}
const events = await getBoxpressdEvents({
  from: "2026-07-01",
  to: "2026-07-31"
})
```

## Related API Endpoint

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

```txt theme={null}
GET /{businessType}s/{businessId}/events
```

For example:

```txt theme={null}
GET /venues/stogies-chapin/events?status=upcoming&limit=6
```

Most SDK users should use `getBoxpressdEvents` or `useEvents` instead of calling the API directly.