Skip to main content

Check Availability

Step-by-step guide to querying available time slots.

Prerequisites​

  • Valid API key
  • Experience ID (from /external/availability/experiences)

Basic Availability Query​

Request​

GET /external/availability/slots?experienceId={id}&day={day}&attendees={attendees}

Parameters​

  • experienceId (required): ID of the dining experience
  • day (required): Date in YYYY-MM-DD format
  • attendees (required): Number of guests (1-50)

Example​

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.molzait.com/external/availability/slots?experienceId=ad5b78a02ca8-4768-bd80-487130c73856&day=2024-06-10&attendees=2"

Response​

{
  "slots": [
    {
      "restaurantId": "e54ba2b9e5f1-4568-a5e0-5998573e002a",
      "experienceId": "ad5b78a02ca8-4768-bd80-487130c73856",
      "day": "2024-06-10",
      "minutes": 1080,
      "duration": 120,
      "attendees": 2,
      "spotsTotal": 10,
      "spotsOpen": 5,
      "seated": 45,
      "seatedLimit": 50,
      "starting": 15,
      "startingLimit": 20,
      "availableAssignments": [
        {
          "floorPlanId": "fp_123",
          "tableIds": ["2f72e7aec901-4427-9ffd-bc4fc435c431"],
          "score": 0.122,
          "minPartySize": 2,
          "maxPartySize": 4,
          "reservable": true,
          "tableCategoryIds": []
        }
      ],
      "exclusionReasons": [],
      "confirmationMode": "instant",
      "showEndTime": true,
      "paymentSettings": null
    }
  ]
}

Advanced Options​

Update Existing Reservation​

When updating a reservation, exclude it from availability calculation:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.molzait.com/external/availability/slots?experienceId=ad5b78a02ca8-4768-bd80-487130c73856&day=2024-06-10&attendees=2&reservationId=4a4ccb52c0bc-4be3-96cd-32accbb3e3d0"

Handling the Response​

Determining Availability​

A slot is available when the exclusionReasons array is empty:

const availableSlots = response.slots.filter(s => s.exclusionReasons.length === 0);
const unavailableSlots = response.slots.filter(s => s.exclusionReasons.length > 0);

Available Slots​

Present available times (empty exclusionReasons) to the user for selection.

Unavailable Slots​

Check exclusionReasons to provide helpful feedback:

unavailableSlots.forEach(slot => {
  const time = `${Math.floor(slot.minutes / 60)}:${(slot.minutes % 60).toString().padStart(2, '0')}`;
  console.log(`${time}: ${slot.exclusionReasons.join(', ')}`);
});

Best Practices​

  1. Cache experience IDs - They rarely change
  2. Limit date range - Query 1-2 weeks at a time
  3. Handle time zones - Use ISO 8601 format
  4. Show loading states - Calculations may take 1-2 seconds
  5. Retry on failure - Implement exponential backoff

Error Handling​

400 Bad Request​

Invalid parameters (missing required fields, invalid date format).

401 Unauthorized​

Invalid or expired API key.

404 Not Found​

Experience ID doesn't exist.

500 Internal Server Error​

Temporary issue - retry with backoff.

Next Steps​