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

> Returns the authenticated customer's deliveries.

# List Deliveries

Returns deliveries addressed to the authenticated customer. Filter by pending status to show only uncollected parcels.

## Authentication

Requires a valid customer bearer token.

## Query Parameters

<ParamField query="page" type="number">
  Page number for pagination. **Default**: `1`.
</ParamField>

<ParamField query="size" type="number">
  Number of results per page. **Default**: `15`.
</ParamField>

<ParamField query="showPending" type="boolean" required>
  `true` — return only uncollected deliveries. `false` — return collected/handled deliveries.
</ParamField>

<ParamField query="query" type="string">
  Free-text search string matched against the delivery name.
</ParamField>

<ParamField query="deliveryType" type="string">
  Filter by delivery type enum value (e.g. `Parcel`, `Letter`, `LargeParcel`).
</ParamField>

<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. Example: `_shape=Records.Name,Records.Collected,TotalItems`.
</ParamField>

## Response

Returns a `DeliveryList` object — a paginated wrapper containing an array of delivery records.

### Pagination

<ResponseField name="Records" type="Delivery[]">
  Array of delivery objects for the current page.
</ResponseField>

<ResponseField name="CurrentPage" type="number">
  Current page number (1-based).
</ResponseField>

<ResponseField name="TotalItems" type="number">
  Total number of matching deliveries.
</ResponseField>

<ResponseField name="TotalPages" type="number">
  Total number of pages.
</ResponseField>

<ResponseField name="HasNextPage" type="boolean">
  Whether there are more pages after the current one.
</ResponseField>

<ResponseField name="HasPreviousPage" type="boolean">
  Whether there are pages before the current one.
</ResponseField>

### Delivery Fields (within `Records[]`)

#### Identity

| Field      | Type     | Description                                |
| ---------- | -------- | ------------------------------------------ |
| `Id`       | `number` | Unique numeric identifier for the delivery |
| `UniqueId` | `string` | Globally unique identifier                 |

#### Core

| Field               | Type             | Description                                              |
| ------------------- | ---------------- | -------------------------------------------------------- |
| `Name`              | `string`         | Delivery reference number / name                         |
| `Notes`             | `string \| null` | Notes added to the delivery                              |
| `Location`          | `string`         | Physical location where the delivery is stored           |
| `DeliveryType`      | `string`         | Type of delivery (`Parcel`, `Letter`, etc.)              |
| `CoworkerFullName`  | `string`         | Full name of the customer the delivery is addressed to   |
| `RecipientId`       | `number \| null` | Id of the specific recipient contact, if applicable      |
| `RecipientFullName` | `string`         | Full name of the recipient (falls back to customer name) |
| `RequiresSignature` | `boolean`        | Whether collection requires a signature                  |

#### Media

| Field              | Type      | Description                                 |
| ------------------ | --------- | ------------------------------------------- |
| `HasImage`         | `boolean` | Whether the delivery has a label image      |
| `ImageUrl`         | `string`  | URL to the delivery label image             |
| `HasSignature`     | `boolean` | Whether a collection signature was captured |
| `HasScan`          | `boolean` | Whether a scanned copy exists               |
| `HasForwardedFile` | `boolean` | Whether a forwarding receipt file exists    |

#### Status

| Field                 | Type      | Description                             |
| --------------------- | --------- | --------------------------------------- |
| `Collected`           | `boolean` | Whether the delivery has been collected |
| `StoredForCollection` | `boolean` | Whether stored at the location          |
| `ReturnedToSender`    | `boolean` | Whether returned to sender              |
| `CheckDeposited`      | `boolean` | Whether a check was deposited           |
| `Forwarded`           | `boolean` | Whether forwarded to another address    |
| `Scanned`             | `boolean` | Whether scanned and sent digitally      |
| `Recycled`            | `boolean` | Whether recycled                        |
| `Shredded`            | `boolean` | Whether shredded                        |

#### Status Dates

| Field                   | Type             | Description                         |
| ----------------------- | ---------------- | ----------------------------------- |
| `CollectedOn`           | `string \| null` | ISO date when collected             |
| `StoredForCollectionOn` | `string \| null` | ISO date when stored for collection |
| `ReturnedToSenderOn`    | `string \| null` | ISO date when returned to sender    |
| `CheckDepositedOn`      | `string \| null` | ISO date when check was deposited   |
| `ForwardedOn`           | `string \| null` | ISO date when forwarded             |
| `ScannedOn`             | `string \| null` | ISO date when scanned               |
| `RecycledOn`            | `string \| null` | ISO date when recycled              |
| `ShreddedOn`            | `string \| null` | ISO date when shredded              |

#### Handling

| Field                         | Type             | Description                                      |
| ----------------------------- | ---------------- | ------------------------------------------------ |
| `HandlingPreference`          | `string \| null` | Current handling preference set by the customer  |
| `HandlingPreferenceCanChange` | `boolean`        | Whether the handling preference can still change |
| `ForwardingAddressUniqueId`   | `string \| null` | UniqueId of the forwarding address               |

#### Timestamps (from base)

| Field          | Type             | Description                             |
| -------------- | ---------------- | --------------------------------------- |
| `CreatedOn`    | `string`         | Date created (business-local time)      |
| `UpdatedOn`    | `string \| null` | Date last updated (business-local time) |
| `CreatedOnUtc` | `string`         | Date created (UTC)                      |
| `UpdatedOnUtc` | `string \| null` | Date last updated (UTC)                 |

## Examples

### Fetch pending deliveries

```http theme={null}
GET /api/public/deliveries/my?showPending=true
Authorization: Bearer {token}
```

### Fetch with response shaping

```http theme={null}
GET /api/public/deliveries/my?showPending=true&_shape=Records.Name,Records.DeliveryType,Records.Collected,Records.CollectedOn,TotalItems
Authorization: Bearer {token}
```

## TypeScript Integration

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

const { resource: deliveries } = useTypedData(httpClient, endpoints.deliveries.list(true))
```

## 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/deliveries/{id}`                 | Get a single delivery's full details |
| `PUT`  | `/api/public/deliveries/{id}/markAsCollected` | Mark a delivery as collected         |