Skip to main content

Create Reservation

Step-by-step guide to creating reservations via the API.

Prerequisites​

  • Valid API key
  • Available time slot (from availability check)
  • Guest information

Basic Reservation Creation​

Request​

POST /external/reservations

Parameters​

  • experienceId (required): Experience ID
  • day (required): Date in YYYY-MM-DD format
  • minutes (required): Minutes since start of day (e.g., 600 = 10:00, 1140 = 19:00)
  • attendees (required): Number of guests
  • lastName (required): Guest last name
  • locale (required): Guest locale (en or de)
  • firstName, email, phone (optional): Additional guest info
  • notes (optional): Reservation notes
  • pinnedTableIds (optional): Specific table IDs (if available)
  • labelIds (optional): Label IDs to add to reservation

Example​

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attendees": 4,
    "day": "2024-01-02",
    "experienceId": "ad5b78a02ca8-4768-bd80-487130c73856",
    "minutes": 1140,
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+436605512234",
    "locale": "en",
    "notes": "Anniversary dinner"
  }' \
  https://api.molzait.com/external/reservations

Response​

{
  "id": "4a4ccb52c0bc-4be3-96cd-32accbb3e3d0",
  "number": "R-001234",
  "attendees": 4,
  "experience": {
    "id": "ad5b78a02ca8-4768-bd80-487130c73856",
    "name": {
      "en": "Dinner",
      "de": "Abendessen"
    },
    "shorthand": "DIN"
  },
  "startTime": "2024-01-02T19:00:00Z",
  "endTime": "2024-01-02T21:00:00Z",
  "checkinTime": null,
  "checkoutTime": null,
  "status": "booked",
  "source": "pos",
  "restaurantId": "e54ba2b9e5f1-4568-a5e0-5998573e002a",
  "guest": {
    "id": "e5e25ac76a2e-4f6d-8f8d-98e64ad283c3",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+436605512234",
    "locale": "en",
    "labels": []
  },
  "pinnedTables": [
    {
      "id": "2f72e7aec901-4427-9ffd-bc4fc435c431",
      "name": "45",
      "minPartySize": 2,
      "maxPartySize": 4
    }
  ],
  "labels": []
}

Guest Information​

All reservations require at minimum lastName and locale. The API will automatically match existing guests or create new ones based on email/phone.

Minimal Guest Info​

{
  "attendees": 2,
  "day": "2024-01-02",
  "experienceId": "ad5b78a02ca8-4768-bd80-487130c73856",
  "minutes": 600,
  "lastName": "Doe",
  "locale": "en"
}

Full Guest Details​

{
  "attendees": 2,
  "day": "2024-01-02",
  "experienceId": "ad5b78a02ca8-4768-bd80-487130c73856",
  "minutes": 600,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "+436605512234",
  "locale": "de"
}

Reservation Status​

Possible status values:

  • requested: Guest requested reservation
  • unconfirmed: Not yet confirmed
  • payment_pending: Awaiting payment
  • booked: Successfully booked and confirmed
  • reconfirmed: Guest reconfirmed attendance
  • arrived: Guest has arrived
  • seated: Guest is seated
  • ordered: Order has been placed
  • paid: Bill has been paid
  • declined: Reservation declined
  • finished: Reservation completed
  • cancelled: Cancelled by guest or restaurant
  • no_show: Guest didn't show up
  • voided: Voided by system

Table Assignment​

The pinnedTableIds parameter controls table assignment behavior:

Automatic Assignment (omit pinnedTableIds)​

When pinnedTableIds is not provided, the system automatically assigns optimal tables based on:

  • Party size
  • Table capacity
  • Current bookings
  • Restaurant preferences
{
  "attendees": 4,
  "day": "2024-01-02",
  "experienceId": "ad5b78a02ca8-4768-bd80-487130c73856",
  "minutes": 1140,
  "lastName": "Smith",
  "locale": "en"
}

No Table Assignment (empty array)​

When pinnedTableIds is an empty array, no tables will be assigned:

{
  "attendees": 4,
  "day": "2024-01-02",
  "experienceId": "ad5b78a02ca8-4768-bd80-487130c73856",
  "minutes": 1140,
  "lastName": "Smith",
  "locale": "en",
  "pinnedTableIds": []
}

Manual Assignment (specific table IDs)​

When pinnedTableIds contains table IDs, those specific tables will be assigned regardless of availability:

{
  "attendees": 4,
  "day": "2024-01-02",
  "experienceId": "ad5b78a02ca8-4768-bd80-487130c73856",
  "minutes": 1140,
  "lastName": "Smith",
  "locale": "en",
  "pinnedTableIds": ["2f72e7aec901-4427-9ffd-bc4fc435c431"]
}

Note: Manual table assignment bypasses availability checks. Ensure tables are available before pinning them.

Error Handling​

400 Bad Request​

Invalid parameters or reservation conflict:

{
  "statusCode": 400,
  "message": "No capacity available for requested time",
  "error": "Bad Request"
}

Solution: Check availability first, use an available slot.

Best Practices​

  1. Check availability first - Verify slot is available before creating reservation
  2. Validate guest data - Ensure email and phone are valid
  3. Store reservation ID - Save for future updates/cancellations
  4. Confirm with guest - Send confirmation email/SMS
  5. Use automatic table assignment - Let the system choose optimal tables unless you have specific requirements

Next Steps​