API Integration Guide

This article describes the integration approach we recommend when connecting your platform to the Booking Manager API. It covers how to authenticate, how to build and maintain a local copy of fleet and yacht data, and how to keep availability and pricing accurate for your customers – from the first full data sync down to the final real-time check before a booking is confirmed.

Following this approach keeps your integration fast and reliable for your end users, while keeping the load on both systems predictable.

Authentication

The Booking Manager API uses Bearer Token authentication. Every request must include an Authorization header in the following format:

Authorization: Bearer <your_access_token>

• Requests sent without a valid token, or with an expired token, will receive a 401 Unauthorized response.
• Your access token should be kept confidential and stored only on your server side – never exposed in client-side code, mobile apps or public repositories.
• If you receive a 401 response, verify the token before retrying the request.

Recommended integration flow – overview

We recommend integrating the API in four steps, each using a specific endpoint and running on a specific schedule. The table below summarizes the flow; each step is explained in detail further down.

Step-by-step integration

Step 1 – Retrieve your fleet list (GET /companies)

The first call to make is getCompanies. This returns the list of all charter fleets (companies) available to you in Booking Manager, together with their unique identifier, companyId.

Store the companyId values you receive – they are used as a filter in the calls described in the following steps.

Step 2 – Build your local yacht database (GET /yachts)

Once you have the companyId values, call getYachts for each fleet (company) to retrieve the full details of its yachts. For each yacht this endpoint returns:

• Core information: name, model, year, base, cabins, berths, and other specifications
• Photos
• Available extras and equipment

We recommend saving this data into your own local database and refreshing it on a weekly basis. This information (yacht specifications, photos, extras) changes infrequently, so a weekly sync is sufficient to keep your catalogue up to date while minimizing unnecessary calls.

Step 3 – Daily availability & pricing sync (GET /offers)

With your local yacht database in place, use getOffers to retrieve availability and pricing for your fleets. In addition to availability, this endpoint returns:

• Base price and discounted price
• Our commission
• Mandatory extras applicable to the yacht
• Any discounts currently active on the yacht

You can call getOffers either by companyId or by country, depending on how you want to scope the sync.

We recommend running a full availability sync across your entire database at least once per day. This keeps the availability and pricing shown to your customers reliably up to date.

Step 4 – Live availability check at selection time (GET /offers)

Because the daily sync only reflects availability at the time it was run, a gap can appear between that sync and the moment your end customer actually selects a yacht – during that window, the yacht’s availability or price may have changed.

To close this gap, we recommend triggering a live check: at the moment the customer clicks on – or selects – a specific yacht, call getOffers again for that exact resource (yachtId) and date. This lets Booking Manager re-confirm availability and price in real time before you proceed with the booking, avoiding the risk of showing a yacht that is no longer available.

Why the live check matters

• The daily sync covers your whole fleet, but availability can change at any time.
• The live check is scoped to one yacht and one date, so it is fast and lightweight.
• Run it right before confirming the customer’s selection, not only at final checkout.

Best practices

1. Always store the token securely on your server and refresh it before it expires.
2. Persist getCompanies and getYachts data locally – do not call these endpoints on every user request.
3. Schedule the full getOffers sync (Step 3) at a consistent time each day, and monitor the job for failures.
4. Always perform the live getOffers check (Step 4) immediately before confirming a booking, even if your local data looks current.
5. Filter getOffers by companyId or country to keep sync jobs efficient when you only need part of the catalogue.
6. Handle 401 and other error responses gracefully, with retries and alerting for repeated failures.

Reference

Full API reference and endpoint schemas: https://app.swaggerhub.com/apis-docs/mmksystems/bm-api/2.2.0