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

# Get Availability

> Retrieves available delivery dates and time slots for scheduled delivery shipments

<Info>
  This endpoint is only available for shipments with `SCHEDULED_DELIVERY` fulfillment type. It returns available delivery dates and time slots for scheduling deliveries.
</Info>

## Request

<ParamField path="domain" type="string" required>
  The merchant's domain (e.g. staging.luma.gift)
</ParamField>

<ParamField header="x-firmly-authorization" type="string" required>
  Device authentication token for session identification
</ParamField>

<ParamField body="shipment_id" type="string" required>
  Target shipment identifier
</ParamField>

## Response

<Note>
  This endpoint only works for shipments that have been configured with `SCHEDULED_DELIVERY` fulfillment type. For other fulfillment types, this endpoint is not applicable.
</Note>

<ResponseField name="shipment_id" type="string">
  The shipment identifier
</ResponseField>

<ResponseField name="fulfillment_type" type="object">
  Current fulfillment configuration (will always be SCHEDULED\_DELIVERY)

  **Properties:**

  * `id` (string): Fulfillment type identifier: `SCHEDULED_DELIVERY`
  * `name` (string): Display name for the fulfillment type
  * `description` (string): Detailed description of the fulfillment method
</ResponseField>

<ResponseField name="available_dates" type="array">
  List of available delivery dates with time slots

  **Date Properties:**

  * `date` (string): Date in YYYY-MM-DD format
  * `description` (string): Description of the delivery option
  * `time_slots` (array): Available time slots for this date

  **Time Slot Properties:**

  * `slot_id` (string): Unique identifier for the time slot
  * `start_time` (string): Start time in 24-hour format (HH:MM)
  * `end_time` (string): End time in 24-hour format (HH:MM)
  * `description` (string): Human-readable description
  * `available` (boolean): Whether the slot is available for selection
</ResponseField>

<ResponseField name="delivery_windows" type="array">
  Premium delivery window options (if available)

  **Properties:**

  * `window_id` (string): Unique window identifier
  * `name` (string): Window display name
  * `description` (string): Detailed window description
  * `price` (object): Additional cost for this window
  * `date_range` (object): Available date range
    * `start_date` (string): First available date
    * `end_date` (string): Last available date
</ResponseField>

## Example Request

```bash theme={null}
curl -X POST https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/shipments/get-availability \
  -H "x-firmly-authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_id": "furniture-shipment-001"
  }'
```

## Example Response

```json theme={null}
{
  "fulfillment_type": {
    "id": "SCHEDULED_DELIVERY",
    "name": "Scheduled Delivery",
    "description": "Choose a delivery date and time"
  },
  "available_dates": [
    {
      "date": "2024-03-15",
      "description": "Premium delivery available",
      "time_slots": [
        {
          "slot_id": "morning-premium",
          "start_time": "08:00",
          "end_time": "12:00",
          "description": "Morning premium delivery",
          "available": true
        }
      ]
    }
  ],
  "delivery_windows": [
    {
      "window_id": "premium-week",
      "name": "Premium Delivery Window",
      "description": "White glove delivery with setup",
      "price": {
        "currency": "USD",
        "value": 199.99,
        "number": 19999,
        "symbol": "$"
      },
      "date_range": {
        "start_date": "2024-03-15",
        "end_date": "2024-03-22"
      }
    }
  ]
}
```

## Usage Pattern

<Info>
  This endpoint is specifically designed for scheduled delivery scenarios where customers need to select specific delivery dates and time slots.
</Info>

### Scheduled Delivery Flow

1. Ensure shipment has `SCHEDULED_DELIVERY` fulfillment type set
2. Call this endpoint to get available delivery dates and time slots
3. Customer selects preferred delivery date and time slot
4. Use [Set Shipping Method](/api-reference/shipment-configuration/set-shipping-method) with the selected date and slot
5. Complete checkout with scheduled delivery information

### Prerequisites

* Shipment must already exist in the cart
* Shipment must have `SCHEDULED_DELIVERY` fulfillment type configured
* Shipping address must be set on the cart

## Error Codes

| Code | Description                                           |
| ---- | ----------------------------------------------------- |
| 400  | Missing authentication header or invalid request body |
| 401  | Invalid JWT token                                     |
| 404  | Shipment not found                                    |
| 422  | Unprocessable data in request                         |
| 503  | Availability service temporarily unavailable          |