Get availability for a listing

Retrieves day-level availability for a listing, with optional date range, status, and price filters. For availability searches across listings, use the search endpoints.

Authorization

x-calry-api-key

x-calry-api-key<token>

In: header

Path Parameters

listingID*string

Unique identifier of the listing

Query Parameters

startDate?string

Start date for availability period (ISO format)

Formatdate-time

endDate?string

End date for availability period (ISO format)

Formatdate-time

status?string

Filter by availability status

Value in"AVAILABLE" | "NOT_AVAILABLE"

displayCurrency?string

Currency to display pricing in (ISO 4217)

page?number

Page number for pagination

Default1

Range1 <= value

limit?number

Number of days per page

Default90

Range1 <= value <= 730

includePrice?boolean

Whether to include the average nightly price in the response

Defaultfalse

aggregate?boolean

Return one record per date (AVAILABLE if any unit is free) instead of one per unit per date. Ideal for calendar display on multi-unit listings.

Defaultfalse

Header Parameters

x-calry-tenant-id?string

Optional tenant ID to specify which tenant to operate as. Controls access to listings and their availability. If not provided, the default tenant will be used.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/availability/123e4567-e89b-12d3-a456-426614174000"

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "date": "2025-12-15",
      "status": "AVAILABLE",
      "price": 200,
      "minimumNights": 2,
      "maximumNights": 30,
      "currency": "USD",
      "originalPrice": 250,
      "priceModifications": {
        "defaultDiscount": {
          "percentage": 10,
          "value": 25
        },
        "markup": {
          "percentage": 10,
          "value": 25
        },
        "promotionDiscount": {
          "percentage": 10,
          "value": 25
        }
      },
      "unit": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "providerUnitID": "unit-123",
        "name": "Ocean View Suite"
      }
    }
  ],
  "meta": {
    "total": 100,
    "limit": 15,
    "totalPages": 8,
    "current": 2,
    "previous": 1,
    "next": 3
  },
  "avgNightlyPrice": 150
}

Empty