# Delivery Time Slots API

`GET /v1/timeslots` returns available delivery slots for a tenant-configured shipping method and date. It is a delivery integration endpoint, not a general appointment calendar or a rental-availability API. The current implementation retrieves slots from the Stuart integration; other shipping-method types can return an empty slot list.

All examples use Bearer authentication. Tenant identity is resolved from the authenticated request by the gateway; do not send separate identity headers.

## Request

Required query parameters:

| Parameter | Type | Description |
|---|---|---|
| `shipping_method_id` | integer | ID of the tenant's configured shipping method. |
| `date` | string | Delivery date requested by the client. |

```bash
curl "$API/v1/timeslots?shipping_method_id=12&date=2026-12-10" \
  -H "Authorization: Bearer $TOKEN"
```

The shipping method must exist for the authenticated tenant and must not be archived. An invalid method returns an API error.

## Response

The response contains a `timeslot` object with the requested `date` and a `slots` array. Each slot contains `start_time` and `end_time` as Unix epoch seconds. For Stuart, the implementation derives a 30-minute slot from each provider-reported start time. If the provider returns no slots—or the shipping method does not use Stuart—the array is empty.

```json
{
  "data": {
    "timeslot": {
      "date": "2026-12-10",
      "slots": [
        { "start_time": 1796900400, "end_time": 1796902200 }
      ]
    }
  }
}
```

This endpoint only looks up delivery-provider slots. It does not reserve a slot, create an order, or configure recurring business hours. Submit the selected delivery window through the applicable cart/checkout flow.