Skip to content

Latest commit

 

History

History
523 lines (461 loc) · 24.5 KB

reservations.md

File metadata and controls

523 lines (461 loc) · 24.5 KB

Mews API Operations: Reservations

Process group

[async] Use this operation to push a group of reservations or bookings to Mews. The operation is called Process Group because as well as creating new reservations, you can also modify existing reservations and make cancellations, all using the same endpoint. We recommend a maximum of 100 reservations per group. Mews will process the reservation requests and confirm back the reservations asynchronously.

Rules to follow

There are certain rules that need to be followed in order for Mews to process the group correctly:

  • It is required to send multiple related reservations in one group as part of one message.
    • The whole group is uniquely identified by channelManagerId in Mews and in the channel manager extranet.
    • Each reservation should have a unique code within the group. The same code for the reservation should be provided in any following modification message.
    • Each reservation in the group can have different start, end, spaceTypeCode, ratePlanCode.
  • Group total cost group.totalAmount is the sum of all reservation.totalAmount objects in the group, which is the sum of all night amounts and total amounts of all extras of the reservation.
    • If for any reason the sum of the reservation.totalAmount objects is different, Mews will automatically distribute the missing/additional amount to the nights, so the group.totalAmount is achieved.
    • Reservation group amounts should be either gross or net. Either both gross and net amounts, or one of them should be sent.
  • When modifying some reservations from a multi-reservation group, the whole group definition with all other unchanged reservations needs to be sent, i.e. Mews doesn't process diffs.
  • When cancelling a reservation from a multi-reservation group, all remaining reservations need to be present in the group definition as well.
    • There are two ways to cancel a reservation from a multi-reservation group:
      1. If the reservation.state is set to Reservation State 'Canceled'.
      2. If the reservation is not included in the group definition message.
  • When cancelling a whole group, the reservations collection can be empty of all reservations provided as canceled (as per case 1 above).

Request

  • Test environment: https://sandbox.pci-proxy.com/v1/push/0426f19b66715a93
  • Production environment: https://api.pci-proxy.com/v1/push/b2721c9a0351d553

The example shows a valid group definition with two space reservations plus cancellation of a third space reservation. The first reservation definition shows all details, the second reservation definition shows the minimal required details for creation / modification of a reservation. The third reservation definition shows the partial cancellation - canceling the third space reservation.

{
    "clientToken": "[Channel manager client token]",
    "connectionToken": "[Token of a concrete connection]",
    "messageId": "MyWeddingMessage789456123",
    "channelId": "EXP-123456",
    "channelManagerId": "123456",
    "availabilityBlockCode": "Wedding123",
    "comments": [
        "Approximate arrival: 16:30.",
        "Guest request a room with ocean view."
    ],
    "currencyCode": "EUR",
    "customer": {
        "address": {
            "addressLine1": "Some street 123",
            "addressLine2": "Some other detail",
            "city": "Some city",
            "country": "US",
            "latitude": 30,
            "longitude": 20,
            "region": "Some region",
            "zip": "123 45"
        },
        "email": "[email protected]",
        "firstName": "John",
        "lastName": "Smith",
        "title": "Mister",
        "nationalityCode": "US",
        "languageCode": "en-US",
        "telephone": "1-3526-88918",
        "loyaltyCode": "PG60972345",
        "loyaltyInfo": {
            "membershipId": "PG60972345",
            "programCode": "BWR",
            "tierCode": "Gold"
        }
    },
    "sources": [
        {
            "code": 1,
            "name": "Expedia",
            "type" : 0,
            "isPrimary": true
        },
        {
            "code": 2,
            "name": "ChoiceCRS",
            "type" : 0,
            "isPrimary": false
        }
    ],
    "company": {
        "id": "MEWS",
        "name": "Mews Systems, s.r.o.",
        "contact": {
            "email": "[email protected]",
            "phone": "+420 775 684 983",
            "address": {
                "zip": "110 00",
                "city": "Prague",
                "country": "Czech Republic",
                "addressLine1": "586 Ulice Test",
                "addressLine2": "Patro 2"
            }
        }
    },
    "travelAgency": {
        "iata": "65553",
        "name": "Best Travel Agency, s.r.o",
        "contact": {
            "email": "[email protected]",
            "phone": "+420 775 775 775",
            "address": {
                "zip": "132 45",
                "addressLine1": "Some other street 123",
                "addressLine2": "Some other detail",
                "city": "Some other city",
                "country": "US"
            }
        }
    },
    "paymentCard": {
        "cvv": "666",
        "expireDate": "1222",
        "holderName": "John Smith",
        "number": "4111111111111111",
        "type": 1
    },
    "paymentType": 1,
    "reservations": [
        {
            "guestCounts": [
                {
                    "code": "Adult",
                    "count": 1
                }
            ],
            "code": "01",
            "extras": [
                {
                    "code": "1",
                    "count": 1,                    
                    "amount": {
                        "net": 16.2,
                        "gross": 20
                    },
                    "from": "2021-05-06",
                    "to": "2021-05-07",
                    "pricing": 3
                }
            ],
            "from": "2020-05-05",
            "guests": [
                {
                    "address": {
                        "addressLine1": "Some other street 123",
                        "addressLine2": "Some other detail",
                        "city": "Some other city",
                        "country": "US",
                        "latitude": 30,
                        "longitude": 20,
                        "region": "Some other region",
                        "zip": "123 45"
                    },
                    "email": "[email protected]",
                    "firstName": "Jane",
                    "lastName": "Smith",
                    "title": "Misses",
                    "nationalityCode": "US",
                    "languageCode": "en-US",
                    "telephone": "1-369-81891"
                }
            ],
            "amounts": [
                {
                    "net": 81,
                    "gross": 100
                },
                {
                    "net": 97.2,
                    "gross": 120
                }
            ],
            "ratePlanCode": "FF",
            "spaceTypeCode": "SGL",
            "state": 1,
            "to": "2020-05-07",
            "totalAmount": {
                "gross": 240,
                "net": 194.4
            }
        },
        {
            "guestCounts": [
                {
                    "code": "Adult",
                    "count": 2
                }
            ],
            "code": "02",
            "from": "2020-05-06",
            "amounts": [
                {
                    "net": 81,
                    "gross": 100
                },
                {
                    "net": 97.2,
                    "gross": 120
                },
                {
                    "net": 97.2,
                    "gross": 120
                }
            ],
            "ratePlanCode": "NR",
            "spaceTypeCode": "DBL",
            "state": 2,
            "to": "2020-05-09",
            "totalAmount": {
                "net": 275.4,
                "gross": 340
            }
        },
        {
            "guestCounts": [
                {
                    "code": "Adult",
                    "count": 2
                }
            ],
            "code": "03",
            "from": "2020-05-06",
            "ratePlanCode": "FF",
            "spaceTypeCode": "DBL",
            "state": 3,
            "to": "2020-05-09"
        }
    ],
    "totalAmount": {
        "net": 469.8,
        "gross": 580
    }
}
Property Type Contract Description
clientToken string required Client token of the channel manager.
connectionToken string required Token of a concrete connection.
messageId string required Unique identification of the message. Used for asynchronous confirmations
channelId string required Unique identification of the booking in the channel (i.e. OTA).
channelManagerId string required Unique identification of the booking in the channel manager.
availabilityBlockCode string optional Unique identification of the availability block in the channel manager.
currencyCode string required (exc. Cancellation) 3 letter code of currency of all prices within the booking.
totalAmount Amount object required (exc. Cancellation) Total amount of the whole booking.
paymentType int required (exc. Cancellation) Payment Type code - determines whether the booking is prepaid or not.
customer Customer object required (exc. Cancellation) Represents the main booker. Does not necessarily mean that the person arrives to the property.
paymentCard Payment Card object optional Represents the payment card of the Customer to cover for the booking.
channel Channel object optional Represents the channel (i.e. Travel Agency). Deprecated!
sources Source collection optional Represents the sources for the booking.
company Company object optional Represents the company associated with the booking.
travelAgency Travel Agency object optional Represents the travel agency associated with the booking.
reservations Reservation collection optional Each reservation within the booking. If the value is null or an empty collection, this implies that the whole group will be canceled.
comments string collection optional Represents any comments related to the booking.

Customer

Property Type Contract Description
email string recommended Email.
lastName string required Last name.
firstName string optional First name.
title string Title optional Customer title, e.g. "Mister"
telephone string optional Telephone.
loyaltyCode string optional Loyalty code of the customer, usually used for the customer's membership number. This is stored in Mews against the Customer Internals tab. Processed only for the main customer. Deprecated!
loyaltyInfo Loyalty Info object optional Loyalty information of the customer. Processed only for the main customer or Availability block booker.
nationalityCode string optional ISO 3166-1 alpha-2 country code - two letter country code or ISO 3166-1 alpha-3 country code - three letter country code.
languageCode string optional Language code of the communication language of the customer. This language will be used as the default for communication with the customer.
address Address object optional Represents address.

Loyalty Info

Property Type Contract Description
membershipId string required Loyalty membership identifier of the Customer.
programCode string optional Loyalty program code.
tierCode string optional Loyalty tier code.

Title

  • Mister
  • Misses
  • Miss

Company

Property Type Contract Description
id string optional Identifier of company.
name string optional Name of company.
iata string optional IATA number of travel agency. Deprecated!
contact Contact object optional Company contact information.

Travel Agency

Property Type Contract Description
iata string optional IATA number of travel agency.
name string optional Name of travel agency.
contact Contact object optional Travel agency contact information.

Contact

Property Type Contract Description
email string recommended Contact email address.
telephone string optional Contaact telephone number.
address Address object optional Contact address.

Payment card

Property Type Contract Description
type int required Payment Card Type code. Important: Only permitted values must be used, we recommend that if you do not know the correct value then use 1 as a fallback.
number string required Payment card number. Only numbers allowed.
expireDate string required Expiration date of card in "MMyy" format (e.g "0222" for February 2022 expiration).
cvv string optional Card CVV code. The value cannot be 000.
holderName string optional Card holder name.

Payment Card Types

Code Description
1 Visa
2 Master Card
3 American Express
4 Bank Card
5 Carte Bleu
6 Carte Blanche
7 Diners Club
8 Discover Card
9 Eurocard
10 Japanese Credit Bureau
11 Universal Air Travel
12 China Unionpay
13 Maestro

Source

Property Type Contract Description
code int required (exc. new unknown sources) Code number of the source or channel.
name string required Name of the source or channel.
type int required Source Type code.
isPrimary bool required Indicates which source is the primary source for the booking.

Source Types

Code Description
0 Online Travel Agency
1 Central Reservation System
2 Global Distribution System
3 Alternative Distribution System
4 Sales And Catering System
5 Property Management System
6 Tour Operator System
7 Online Booking Engine
8 Kiosk
9 Agent

Reservation

Property Type Contract Description
code string required (exc. Mews to ChM.) Unique code of the reservation within the whole booking. Any value but _ accepted. No characters limit.
confirmationNumber string required (exc. ChM to Mews.) Unique code of the reservation within the whole booking in Mews. No characters limit.
spaceTypeCode string required (exc. Cancellation) Space type code of the reservation.
ratePlanCode string required (exc. Cancellation) Rate type code of the reservation.
from string required (exc. Cancellation) Start date in format "yyyy-MM-dd" (e.g. "2021-12-24" for Christmas Eve).
to string required (exc. Cancellation) End date (exclusive) in format "yyyy-MM-dd" (e.g. "2021-12-31" for New Year's Eve). This is the date of resrvation departure.
totalAmount Amount object required (exc. Cancellation) Total amount of the reservation.
guestCounts array of Guest Count required Number of guests in the reservation for each age category.
state int optional Reservation State code of reservation state. If not provided, Mews will handle the reservation as Created or Modified.
amounts Amount collection required (exc. Cancellation) Collection of amounts for each night of the reservation. The count of amounts in this collection has to correspond with number of nights in the reservation.
extras Extra collection optional Collection of extra ordered products for the reservation (e.g. Breakfast). Their total amount is included in the totalAmount of the reservation.
guests Customer collection optional Collection of guests that will arrive to the property.
timeState int required (used only in CHM: Process group operation) Reservation Time State code of reservation state.
paymentCardData Payment Card Data object optional (used only in CHM: Process group operation) Represents the payment card of the Customer to cover for the booking. It doesn't contain the actual card number.
adultCount int required (exc. Cancellation) Number of adults in the reservation. Deprecated!
childCount int optional (exc. Cancellation) Number of children in the reservation. Deprecated!

Codes: It is required that code remains the same within each booking modification message and partial modification message. If this can't be achieved because the channel doesn't provide it, simple generation of codes "01", "02", ... will suffice as long as those codes are generated in the same way for each message regarding that one booking.

From/To: This represents the reservation arrival, from is arrival date, to is departure date. So reservation for 2 nights (e.g. 2021-12-24/25 and 2021-12-25/26 is represented as "from": "2021-12-24", "to": "2021-12-26").

Payment Card Data

Property Type Contract Description
type int required Payment Card Type code.
obfuscatedNumber string required Obfuscated payment card number.
expireDate string required Expiration date of card in "MMyy" format (e.g "0222" for February 2022 expiration).
identifier string required Mews identifier of the payment card.
holderName string optional Card holder name.

Guest Count

Property Type Contract Description
code string required Age category code.
count int required Number of persons for specified age category.

Age Category Code

  • Infant
  • Child
  • Teenager
  • Adult
  • SeniorCitizen

Reservation States

Code Description
1 Created
2 Modified
3 Canceled

Reservation Time States

Code Description
0 Optional - any tentative reservation that has not been confirmed yet. By default Mews does not synchronize such reservations to Channel Managers.
1 Confirmed - reservation with arrival date in the future.
2 CheckedIn - reservation that is currently checked-in.
3 CheckedOut - reservation that is already checked out (i.e. past reservation)
4 Canceled - reservation that is canceled.
5 NoShow - reservation that is canceled with NoShow reason.

Extra

Property Type Contract Description
code string required Mapping code of the extra product.
amount Amount object required Total amount of the extra product.
count int required Count of extra products ordered.
from string optional (exc. Cancellation) Start date in format "yyyy-MM-dd" (e.g., "2021-12-24" for Christmas Eve).
to string optional (exc. Cancellation) End date in format "yyyy-MM-dd" (e.g., "2021-12-31" for New Year's Eve).
pricing int required Extra pricing Type code of the extra product pricing.

Extra product cost

  • The total cost of the extra product should be sent in amount.
  • amount can include only gross, only net, or both gross and net.
  • from and to can define any interval within the reservation dates, but they cannot be the same date. For example, if a reservation is from 2025-10-12 to 2025-10-15, then the extra from and to cannot be specified as 2025-10-12 to 2025-10-12.

Negative amounts

  • The cost for an extra product can be negative, i.e. less than zero.
  • If a reservation night price is negative, the reservation will fail.
  • If extra product costs are negative, their value will be deducted from the reservation night price.
  • As long as the resulting reservation price (after deducting the cost of the extra products) is positive, all is well.
  • If the resulting reservation price (after deducting the cost of the extra products) is negative, the reservation will still pass and be processed, however this can create complications for the property and they may have to re-price it.
  • It is recommended to send extras per room or space, because it is less likely that the resulting reservation price will fall below zero.

Amount

Property Type Contract Description
net decimal optional Price with taxes excluded.
gross decimal optional Price with taxes included.

Extra Pricing Types

Code Description
1 Once per reservation.
2 Per person - for each guest of reservation.
3 Per night - for each night of reservation.
4 Per person per night - for each guest for each night of reservaion.

Response

Synchronous simple response will determine whether the reservations or bookings were accepted for processing or not. Confirmation will be sent asynchronously using the Confirm booking operation.

Confirm group confirmation

Request

[PlatformAddress]/api/channelManager/v1/processGroupConfirmation

{
    "clientToken": "[Channel manager client token]",
    "connectionToken": "[Token of a concrete connection]",
    "relatedMessageId": "[Id of message which request relates to]",
    "success": true,
    "code": 123,
    "reservations": [
        {
            "code": "Ext123",
            "confirmationNumber": "Mews456"
        }
    ]
}
Property Type Contract Description
clientToken string required Client token of the channel manager.
connectionToken string required Token of a concrete connection.
relatedMessageId string required Id of message which requests relates to.
success bool required Determinines the result of the operation.
errors array of Error optional In case of "success": false, this property holds information about the errors that occurred.
code string required Unique reference code from external system for the group. Will be sent with every group changes.
reservations Reservation Confirmation collection optional Confirmation details for each individual reservation in the group.

Reservation Confirmation

Property Type Contract Description
code string required Unique reference code for the individual reservation. Will be sent back with group changes.
confirmationNumber string required Mews confirmation number for the individual reservation.

Response

Synchronous simple response is expected.