> ## 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.

# Get Customer Benefits

> Retrieve the plan benefits available to the current customer profile, including booking credits, extra services, and time passes.

# Get Customer Benefits

Returns all plan benefits currently available to the active customer profile. Benefits are granted through active plan (tariff) subscriptions and include booking credits, extra services (such as printing), and time passes. The portal uses this to display the benefits panel on the My Plans page and to gate access to credit-based features.

## 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

The response is split into `Personal` benefits (belonging to the individual profile) and `Team` benefits (shared across the customer's team).

<ResponseField name="Personal" type="object">
  Benefits belonging to the individual customer profile.
</ResponseField>

<ResponseField name="Personal.BookingCredits" type="array">
  Booking credit allowances granted by active plans.
</ResponseField>

<ResponseField name="Personal.BookingCredits[].Id" type="number">
  Unique identifier for the booking credit record.
</ResponseField>

<ResponseField name="Personal.BookingCredits[].Name" type="string">
  Display name of the booking credit allowance.
</ResponseField>

<ResponseField name="Personal.BookingCredits[].TotalCredit" type="number">
  Total credit amount granted (in the location's currency).
</ResponseField>

<ResponseField name="Personal.BookingCredits[].RemainingCredit" type="number">
  Remaining credit balance available to spend.
</ResponseField>

<ResponseField name="Personal.BookingCredits[].CaneBeUsedForBookings" type="boolean">
  `true` when this credit can be applied to room and desk bookings.
</ResponseField>

<ResponseField name="Personal.BookingCredits[].CaneBeUsedForEvents" type="boolean">
  `true` when this credit can be applied to event ticket purchases.
</ResponseField>

<ResponseField name="Personal.BookingCredits[].IsUniversalCredit" type="boolean">
  `true` when this credit applies to all resource types.
</ResponseField>

<ResponseField name="Personal.BookingCredits[].IsFromTariff" type="boolean">
  `true` when this credit was granted by an active plan subscription rather than manually assigned.
</ResponseField>

<ResponseField name="Personal.BookingCredits[].ExpireDate" type="string | null">
  ISO 8601 datetime when this credit expires. `null` if it does not expire.
</ResponseField>

<ResponseField name="Personal.ExtraServices" type="array">
  Extra service allowances (e.g. printing credits) granted by active plans.
</ResponseField>

<ResponseField name="Personal.ExtraServices[].Id" type="number">
  Unique identifier for the extra service record.
</ResponseField>

<ResponseField name="Personal.ExtraServices[].ExtraService.Id" type="number">
  Identifier of the extra service type.
</ResponseField>

<ResponseField name="Personal.ExtraServices[].ExtraService.Name" type="string">
  Display name of the extra service.
</ResponseField>

<ResponseField name="Personal.ExtraServices[].ExtraService.IsPrintingCredit" type="boolean">
  `true` when this service is a printing credit (e.g. PaperCut integration).
</ResponseField>

<ResponseField name="Personal.ExtraServices[].TotalUses" type="number">
  Total number of uses granted.
</ResponseField>

<ResponseField name="Personal.ExtraServices[].RemainingUses" type="number">
  Remaining uses available.
</ResponseField>

<ResponseField name="Personal.ExtraServices[].ChargePeriod" type="string">
  How uses are measured: `"Minutes"`, `"Days"`, `"Weeks"`, `"Months"`, `"Uses"`, or `"FourWeekMonths"`.
</ResponseField>

<ResponseField name="Personal.ExtraServices[].IsFromTariff" type="boolean">
  `true` when granted by an active plan subscription.
</ResponseField>

<ResponseField name="Personal.ExtraServices[].ExpireDate" type="string | null">
  ISO 8601 expiry datetime. `null` if it does not expire.
</ResponseField>

<ResponseField name="Personal.TimePasses" type="array">
  Time pass allowances granted by active plans.
</ResponseField>

<ResponseField name="Personal.TimePasses[].Id" type="number">
  Unique identifier for the time pass record.
</ResponseField>

<ResponseField name="Personal.TimePasses[].TimePass.Id" type="number">
  Identifier of the time pass type.
</ResponseField>

<ResponseField name="Personal.TimePasses[].TimePass.Name" type="string">
  Display name of the time pass.
</ResponseField>

<ResponseField name="Personal.TimePasses[].TotalUses" type="number | null">
  Total number of uses granted. `null` for unlimited passes.
</ResponseField>

<ResponseField name="Personal.TimePasses[].RemainingUses" type="number | null">
  Remaining uses. `null` for unlimited passes.
</ResponseField>

<ResponseField name="Personal.TimePasses[].Used" type="boolean">
  `true` when this specific time pass instance has been used.
</ResponseField>

<ResponseField name="Personal.TimePasses[].IsFromTariff" type="boolean">
  `true` when granted by an active plan subscription.
</ResponseField>

<ResponseField name="Personal.TimePasses[].ExpireDate" type="string | null">
  ISO 8601 expiry datetime. `null` if it does not expire.
</ResponseField>

<ResponseField name="Team" type="object">
  Benefits shared with the customer's team. Contains the same structure as `Personal` (`BookingCredits`, `ExtraServices`, `TimePasses`).
</ResponseField>

## Example Response

```json theme={null}
{
  "Personal": {
    "BookingCredits": [
      {
        "Id": 5,
        "Name": "Monthly Booking Allowance",
        "TotalCredit": 200.0,
        "RemainingCredit": 145.5,
        "CaneBeUsedForBookings": true,
        "CaneBeUsedForEvents": false,
        "IsUniversalCredit": false,
        "IsFromTariff": true,
        "ExpireDate": "2026-04-30T23:59:59Z"
      }
    ],
    "ExtraServices": [],
    "TimePasses": [
      {
        "Id": 12,
        "TimePass": { "Id": 3, "Name": "Day Pass" },
        "TotalUses": 5,
        "RemainingUses": 3,
        "Used": false,
        "IsFromTariff": true,
        "ExpireDate": null
      }
    ]
  },
  "Team": {
    "BookingCredits": [],
    "ExtraServices": [],
    "TimePasses": []
  }
}
```

## TypeScript Integration

```typescript theme={null}
import endpoints from '@/api/endpoints'
import { MyBenefits } from '@/types/public/billing/MyBenefits'
import { useData } from '@/api/fetchData'
import { createShape } from '@/helpers/shape-helper'

const shape = createShape<MyBenefits>()([
  'Personal.BookingCredits.Id',
  'Personal.BookingCredits.Name',
  'Personal.BookingCredits.RemainingCredit',
  'Personal.TimePasses.Id',
  'Personal.TimePasses.TimePass.Name',
  'Personal.TimePasses.RemainingUses',
])

const { resource: benefits } = useData<MyBenefits>(httpClient, endpoints.coworkers.benefits, {
  shape: shape.fields,
})
```

## Usage in Portal

| Context                        | Source file                                             |
| ------------------------------ | ------------------------------------------------------- |
| My Plans page — benefits panel | `src/views/user/plans/useMyBenefitsData.ts`             |
| Benefits display component     | `src/views/user/plans/components/MyBenefitsSection.tsx` |

## Error Responses

<ResponseField name="401 Unauthorized" type="error">
  The bearer token is missing, expired, or invalid.
</ResponseField>

## Related Endpoints

| Method | Endpoint                                 | Description                                |
| ------ | ---------------------------------------- | ------------------------------------------ |
| `GET`  | `/api/public/coworkers/profiles`         | List all profiles for the current session  |
| `GET`  | `/api/public/plans/my`                   | List active plans for the current customer |
| `PUT`  | `/api/public/coworkers/profiles/current` | Switch the active profile                  |