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

# List Perks

> Returns all published perks for the current location, grouped by category.

# List Perks

Returns all published perks available at the current location. Perks are grouped by their `GroupName` and include full-text descriptions suitable for rendering in a perks catalogue.

<Note>
  A **perk** is a benefit or discount offered by a partner business (restaurant, gym, etc.) to coworking members. Operators configure perks in the
  admin dashboard and members can claim them from the portal.
</Note>

## Authentication

Requires a valid customer bearer token.

## Query Parameters

<ParamField query="_shape" type="string">
  Comma-separated list of field paths to include in the response. When provided, only the
  specified fields are returned — useful for reducing payload size. Supports nested paths
  using dot notation.
</ParamField>

## Response

### Core Fields

<ResponseField name="Groups" type="string[]" required>
  List of unique group names across all perks — use to build category tabs or filter UI.
</ResponseField>

<ResponseField name="Perks" type="Perk[]" required>
  Array of all published perks.
</ResponseField>

<ResponseField name="Perks[].Id" type="number" required>
  Unique identifier for the perk. Use as `{perkId}` in the claim endpoint.
</ResponseField>

<ResponseField name="Perks[].Title" type="string" required>
  Display title of the perk.
</ResponseField>

<ResponseField name="Perks[].GroupName" type="string">
  Category group this perk belongs to. Matches one of the values in the `Groups` array.
</ResponseField>

<ResponseField name="Perks[].FullText" type="string" required>
  Full description of the perk. May contain HTML.
</ResponseField>

<ResponseField name="Perks[].SummaryText" type="string">
  Short summary shown in perk cards.
</ResponseField>

## Examples

### Fetch all perks

```http theme={null}
GET /api/public/perks
Authorization: Bearer {token}
```

```json theme={null}
{
  "Groups": ["Food & Drink", "Fitness"],
  "Perks": [
    {
      "Id": 101,
      "Title": "15% off at Corner Café",
      "GroupName": "Food & Drink",
      "FullText": "<p>Show your member badge at Corner Café for 15% off any order.</p>",
      "SummaryText": "15% off any order"
    }
  ]
}
```

## TypeScript Integration

```typescript theme={null}
import endpoints from '@/api/endpoints'

const { resource: perks } = useTypedData(httpClient, endpoints.perks.list())
// perks.Groups, perks.Perks
```