Getting Started

Welcome to the CalMac API. This guide covers the essential information you need to integrate successfully.

The Booking Flow

CalMac uses a three-step booking flow: Quotation, Reservation, and Confirmation. Each step must be completed in order, using session tokens passed between steps.

1. Quotation - Get pricing and lock in fares (no commitment)

2. Reservation - Reserve space on the vessel (creates an option)

3. Confirmation - Complete the booking after payment

Critical: Payment Webhook Integration

The confirmation endpoint should be called from your SERVER, not from a client application.

Client-side calls (browser/mobile) are unreliable because network may drop during payment, the user may close the app, or the device may suspend. If payment succeeds but confirmation fails, the customer is charged but has no booking.

Recommended flow: Client initiates payment with your provider, payment provider sends webhook to your server, your server calls the CalMac /confirm endpoint, then your server notifies the client that booking is complete.

Time Limits

Quotation: ~45 minutes - Price is locked until expiry. Proceed to reservation before this time.

Reservation: ~45 minutes - Space is held until expiry. Complete payment and confirmation before this time.

Plan your payment flow to complete well before the reservation expires.

API Route Passenger Requirements

Routes over 20 nautical miles require additional passenger details (date of birth, gender, nationality) for ALL passengers. Check the requiresAdvancedPassengerInfo flag on each route connection from the GET /ports endpoint.

Next Steps

Explore the Timetable API to search for sailings, then use the Booking API to create bookings.