This article describes how to add optional extras to a reservation, and remove them, through the Booking Manager API. It covers how to authenticate, how to find the extras available for a reservation, how to add one or more of them, and how to remove an extra that is no longer needed.
Extras such as an outboard engine, a skipper, or SUP can be added to a reservation while it is still an option (Status=2). Obligatory extras are added automatically when the option is created, so these calls are meant for optional extras. They are the REST counterparts of the SOAP calls insertOptionItem and removeInvoiceItem.
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>- All extras calls use the base URL
https://www.booking-manager.com/api/v2. - 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.
Reservation extras endpoints – overview
All three calls need the ID of your reservation reservationId). The table below summarizes them; each one is explained in detail further down.
| Endpoint | Purpose | Success response |
|---|---|---|
|
1. GET /reservation/{reservationId}/extras/available (getAvailableReservationExtras) |
List the extras that can be added to the reservation | 200 OK with the list of extras (may be empty) |
|
2. POST /reservation/{reservationId}/extras (addReservationExtras) |
Add one or more extras to the reservation | 201 Created with the updated reservation |
|
3. DELETE /reservation/{reservationId}/extras/{itemId} (removeReservationExtra) |
Remove an extra from the reservation | 200 OK with the updated reservation |
Before you start
-
Extras can be changed only on options (status 2) and not on reservations (status 1). Once a reservation is confirmed, adding or removing extras is rejected with
Reservation already confirmed.Add all the extras you need before you confirm the option withPUT /reservation/{reservationId}. - Agencies work on their own reservation. When an agency adds an extra that belongs to the charter company, the extra is added both to the agency reservation and to the related charter reservation. The same applies when it is removed.
- Who can remove what. An agency can remove only extras it added itself. A charter company can remove any extra on its own reservation.
-
Email notifications. By default, the charter company and the client receive an email about every change to the reservation. To avoid this, add
sendNotification=falseto the POST or DELETE call.
Step-by-step usage
Step 1 – Get the reservation ID
After you create an option with createReservation (POST /reservation), use GetReservations to obtain the charter Reservation Id and the agency reservation ID.
For reservations created earlier, you can find the ID with getReservations (GET /reservations/{year}).
Agencies: use the id of your own reservation, not the charterReservationId of the related charter reservation.
Step 2 – List the available extras (GET /reservation/{reservationId}/extras/available)
Call getAvailableReservationExtras to see which extras can be added to the reservation. The list contains the charter company's extras that are valid for the reservation's yacht, product, dates, and bases. Extras with a stock limit are listed only while stock is left. If you use an agency token, your agency's own extras are included as well.
The price of each extra is already calculated for this reservation, in the reservation currency.
GET /api/v2/reservation/11851860000100797/extras/available
Authorization: Bearer <your_access_token>Response: 200 OK
[
{
"id": 4401234500000012300,
"name": "Outboard engine",
"description": "5 HP outboard engine for the dinghy",
"obligatory": false,
"price": 120,
"percentage": 0,
"currency": "EUR",
"unit": "per booking",
"payableInBase": true,
"includesDepositWaiver": false,
"quantityIsSelectable": true,
"quantityLimit": 2,
"includedExtras": [],
"availableInBase": null
},
{
"id": 4401234500000012301,
"name": "Final cleaning",
"description": "Cleaning of the yacht after check-out",
"obligatory": false,
"price": 150,
"percentage": 0,
"currency": "EUR",
"unit": "per booking",
"payableInBase": true,
"includesDepositWaiver": false,
"quantityIsSelectable": false,
"quantityLimit": 0,
"includedExtras": [],
"availableInBase": null
}
]Store the id of each extra you want to add – you send it as extraId in the next step.
Step 3 – Add extras (POST /reservation/{reservationId}/extras)
To add extras, call addReservationExtras with a JSON array of one or more extras. For each extra:
-
extraIdis required and must be theidof an extra returned in Step 2. -
quantityis optional and defaults to1. It must not exceed the extra'squantityLimit, and it can be higher than 1 only ifquantityIsSelectableistrue. -
priceis optional. If you leave it out, the system calculates the price for this reservation. A custom price is accepted only for extras that belong to your own company.
All extras in the list are checked before any of them is added: if one is invalid, nothing is added.
The example below adds two outboard engines at the system price:
POST /api/v2/reservation/11851860000100797/extras
Authorization: Bearer <your_access_token>
Content-Type: application/json
[
{
"extraId": 4401234500000012300,
"quantity": 2
}
]You can add several extras in the same call. In this example, a charter company adds two outboard engines and final cleaning at a custom price of its own:
[
{
"extraId": 4401234500000012300,
"quantity": 2
},
{
"extraId": 4401234500000012301,
"price": 130
}
]Response: 201 Created, with the updated reservation. The added extras appear in the items list, and the totals are recalculated. Shortened example for the first request:
{
"id": 11851860000100797,
"reservationCode": "1234/2026",
"status": 2,
"currency": "EUR",
"basePrice": 3200,
"finalPrice": 3440,
"items": [
{
"id": 4401234500000099000,
"name": "Outboard engine",
"quantity": 2,
"unit": "PIECES",
"price": 240,
"payableInBase": true
}
]
}extraId and itemId are not the same
extraIdis the id of the extra in the list from Step 2. You use it to add an extra.itemIdis theidof the entry in the reservation'sitemslist, created when the extra was added. You use it to remove an extra.- Sending an
extraIdto the DELETE call returns 404 Not Found.
Step 4 – Remove an extra (DELETE /reservation/{reservationId}/extras/{itemId})
To remove an extra, call removeReservationExtra with the id of its entry in the reservation's items list as itemId. No request body is needed. Each call removes one extra.
DELETE /api/v2/reservation/11851860000100797/extras/4401234500000099000
Authorization: Bearer <your_access_token>Response: 200 OK, with the updated reservation, without the removed extra and with recalculated totals.
Field reference
Available extra (Step 2 response)
| Field | Type | Description |
|---|---|---|
id |
integer | Extra ID. Send it as extraId when adding the extra. |
name |
string | Name of the extra. |
description |
string | Description of the extra. |
obligatory |
boolean | Obligatory extras are added automatically and usually do not need to be added manually. |
price |
number | Price of the extra for this reservation. |
percentage |
number | Percentage value, for extras priced as a percentage of the base price. |
currency |
string | Currency code of price. |
unit |
string | Pricing unit, e.g. per booking, per day, per person. |
payableInBase |
boolean |
true if the extra is paid at the base at check-in instead of with the charter price. |
includesDepositWaiver |
boolean |
true if the extra includes a deposit waiver. |
quantityIsSelectable |
boolean |
true if a quantity other than 1 can be sent for this extra. |
quantityLimit |
integer | Maximum quantity that can still be booked. 0 means no limit. |
includedExtras |
array | IDs of other extras included in this one. |
availableInBase |
integer | ID of the base the extra is restricted to, if any. |
Best practices
- Always store the token securely on your server side.
- Call getAvailableReservationExtras right before adding extras – availability and stock can change, and prices are calculated for each reservation.
- Add all the extras you need before confirming the option: after confirmation, they can no longer be changed through the API.
- Check
quantityLimitandquantityIsSelectablebefore sending a quantity, so one invalid extra does not block the whole request. - Keep the
itemsreturned by the POST call: you need the itemidto remove an extra later. - Use
sendNotification=falsewhen you make several changes in a row, so the charter company does not receive an email for each one.
Reference
Full API reference and endpoint schemas: https://app.swaggerhub.com/apis-docs/mmksystems/bm-api/
Comments
0 comments
Please sign in to leave a comment.