🔧 Introduction

RateFox is an advanced solution built to empower travel companies by optimizing booking profitability in real time.

RateFox integrates seamlessly into your existing booking flow with a single API call, made just before the Booking Request. This implementation guide will walk you through each step required to successfully integrate RateFox into your system.

👍
Notes and Tips :
Recommended Guides prior to Implementation / Evaluation -

Understanding How Ratefox Operates

Understanding What is 'Evaluation' Mode.

In this guide, you will find detailed information on:

✅ Authentication Method
🔄 Request and Response Structure
🧾 Field Descriptions
📘 Use Case Examples
🧪 Evaluation and Integration Steps
🧠 Best Practices for Optimal Performance

📘
Code Examples
For each code example provided, you’ll also find versions in multiple programming languages. Simply click “More Code Examples” below each section to view them :

Shell

Python

Node

Ruby

Objective-C

PHP

C

C++

C#

Clojure

Go

HTTP

Java

Javascript

JSON

Kotlin

PowerShell

OCaml

R

Swift

🔑 Authentication

The RateFox API uses HTTP Basic Authentication to securely authorize requests. Each API call must include a Base64-encoded username and password in the request header.

Authentication Format
To construct the Authorization header - Combine your username and password with a colon (:).

📘
Example :
If your Username is “api_user” and Password is “secret123”.
Combined string: “api_user:secret123”.
Base64 encoded: "YXBpX3VzZXI6c2VjcmV0MTIz”
Header : Authorization : Basic YXBpX3VzZXI6c2VjcmV0MTIz

✅

Code Example :

curl -X GET 'https://api.example.com/endpoint' \
-H 'Authorization: Basic YXBpX3VzZXI6c2VjcmV0MTIz'

More Code Examples

🛠️ Endpoint Reference

**Base URL - ** https://api.ratefox.io - for all Ratefox API endpoints.

Ratefox API description in Swagger References - Click here.

Ratefox API Endpoints

Method	Endpoint	Description
`POST`	`/hotels/ratefox`	Finds a better price and books the hotel if successful.
`POST`	`/hotels/prefetch`	Optimizes RateFox flow performance (Prefetch mode only).
`POST`	`/hotels/rebook`	Launch Rebook monitoring for a booking created on client side
	Post Booking Requests
`POST`	`/hotels/cancel/{segmentId}`	Cancels the RateFox segment reservation with the specified segmentId. Note: Only for Live mode
`POST`	`/hotels/checkstatus/{segmentId}`	Checks the status of a RateFox segment reservation with the specified segmentId Note: Only for Live mode
`GET`	`/hotels/orderdata/{orderId}`	Returns details of the RateFox booking with the specified orderId
`POST`	`/hotels/orders`	Returns details of the RateFox bookings with the specified FromDate and ToDate
`POST`	`/hotels/excludefromrebooker/{orderId}`	Exclude the Ratefox booking with specified orderID form Rebook monitoring

✅ POST /hotels/ratefox

Standard Mode Ratefox API request for booking the specified hotel room at a better price.

👍
Notes and Tips :
Special Parameters :

**Room Id: **
Under the "Rooms" field, each "Id" - should be a unique (per reach room), self-generated GUID.

Passenger Id:
Under the "LeadPassenger" and "AdditionalPassengers" fields - each passenger "Id" should be unique (per reach passenger), self-generated GUID.

Allocation:
Under the "LeadPassenger" and "AdditionalPassengers" fields - each passenger's "Allocation" should be the respective room "Id" which was provided in the "Rooms" field.

Request Parameters

Field	Description	Format	Mandatory
SupplierHotel	object		Yes
SupplierId	Supplier’s ID in Ratefox. Integrated suppliers list https://documentation.hsp.gimmonix.com/docs/hsp-hotels-integrated-suppliers	Integer	Yes
SupplierHotelId	Supplier’s HotelID - the corresponding supplier's Hotel key / Id, used to identify the desired property.	String	Yes
CheckIn	Check-in date	String - Unix Epoch time	Yes
CheckOut	Check-out date	String - Unix Epoch time	Yes
Residency	The lead passenger residency.	String (2) ISO Country Code `(Ex: US, CZ, IL)`	Yes
Price	object		Yes
BookingPrice	The price from client’s booking flow. Taxes, fees and commission from the request will be applied to the BookingPrice to obtain “clear” price for comparison with alternative packages’ prices. See examples below the table. The Supplier Buying Price.	Double	Yes
Currency	The currency of the BookingPrice. Rates in response will be in this currency.	String (3) ISO Currency Code `(Ex: USD, EUR)`	Yes
TotalTax	object
Amount	Amount of taxes	Double	Yes
IsIncluded	Are taxes included in the BookingPrice. If `false` -excluded, BookingPrice will be increased by Tax Amount before comparing with alternative packages’ prices. When `true` does not affect.	Boolean	Yes
Currency	If not provided, then `Price Currency` is used.	String (3) ISO Currency Code
TotalFee	object
Amount	Amount of fees	Double	Yes
IsIncluded	Are fees included in the BookingPrice. If `true` - included, BookingPrice will be reduced by Fee Amount before comparing with alternative packages’ prices. When `false` does not affect.	Boolean	Yes
Currency	If not provided, then `Price Currency` is used	String (3) ISO Currency Code
Commission	object
Amount	Amount of client’s commission. BookingPrice will be reduced by Commission Amount before comparing with alternative packages’ prices.	Double	Yes
Currency	If not provided, then `Price Currency` is used	String (3) ISO Currency Codes
RefundableUntil	Refundability deadline. (If Non-Refundable, specify the same date of the request).	String Unix Epoch time	Yes
Rooms	Array of objects. (Max. Rooms - 4)	Array	Yes
Id	Room Id inside the request. Self-generated GUID. Should be a unique per each room in the array.	GUID	Yes
RoomName	The name of the booked room in supplier terms Examples: "Standard Room", "Double with sea view", "Triple", "Family Room", etc. (In any language)	String	Yes
RoomBasis	The meal-plan, ”Board” (as it used by supplier from SupplierID). Examples: "Room Only", "Bed and Breakfast", "Half Board", "Full Board", "All Inclusive".	String	Yes
AdultsCount	Number of adults in the room. (Max. Adults - 8).	Integer	Yes
KidsAges	Array of kids ages. Each value must be between 0 and 17. If empty, there are no kids in the room.	Array of integer
WorkMode	Defines the WorkMode for the request. Possible values: “live”. Can be used only by the client which is set “live” in Gimmonix. The request in this mode produces the real booking; “evaluation”. The mode for testing and evaluation. The request in this mode doesn’t produce the real booking but full description of Ratefox found alternative is steal returned. This mode can be used by both clients connected to Ratefox as "evaluation" (new clients before the certification stage is completed) and those who are set "live". More about evaluation mode - link .	String	Yes
LeadPassenger	Object. The main passenger from the booking		Yes
Id	Lead passenger’s Id inside the request. Self-generated GUID. Should be a unique per each passenger in the request.	GUID	Yes
Allocation	The Allocation of the Pax from the RoomId/s from Rooms array. Identifies the room for the LeadPassenger.	GUID	Yes
Name	object		Yes
GivenName	First name. Use English characters only, otherwise the booking might fail on the supplier side.	String(50)	Yes
NamePrefix	Mr, Mrs, Ms etc. If not provided, “Mr” is used.	String
Surname	Last name. Use English characters only, otherwise the booking might fail on the supplier side.	String(50)
Type	Must be “adult” for the LeadPassenger	String	Yes
Age	Lead passenger's age.	Integer
PhoneNumber	Passenger’s phone number to specify in the booking.	String(50)
CustomerEmail	Passenger’s email to specify in the booking.	String(254)
Address	object. Address details to specify in the booking
CountryCode	The country code of the passenger.	String(2) ISO Country Code (Ex: US, CZ, IL)
AddressLine	The address of the passenger.	String(254)
StateProv		String(20)
PostalCode		String(20)
AdditionalPassengers	Array of objects. All passengers (adults and kids) except LeadPassenger must be described in this array.	Array
Id	Passenger’s Id inside the request. Self-generated GUID. Should be a unique per each passenger in the request	GUID	Yes
Allocation	The Allocation of the Pax from the RoomId/s from Rooms array. Identifies the room for the AdditionalPassengers.	GUID	Yes
Name	object		Yes
GivenName	First name. Use English characters only, otherwise the booking might fail on the supplier side.	String(50)
NamePrefix	Mr, Mrs, Ms etc. If not provided, “Mr” is used.	String
Surname	Last name. Use English characters only, otherwise the booking might fail on the supplier side.	String(50)
Type	“adult” or “child”.	String	Yes
Age	Mandatory in case the passenger’s type is ”child”. The value must be between 0 and 17 and match one of the KigsAges array’s values.	Integer
LeadPaxRoomId	Id from Rooms array. Identifies the room of the LeadPassenger	GUID	Yes
Language	Only “en” is currently supported	String	Yes
RoomsRemarks	Free text remarks to be sent to the supplier within booking. Collection of "Key" : "Value” pairs, where Key is room Id from the Rooms array. Only suppliers that support this feature will receive the remarks.
InternalAgentRef1	Agent reference of the booking.	String
CustomBookingReference	Client reference.	String
PointOfSale	Defines the sales channel. Acceptable values must be agreed between the client and Ratefox. No predefined values are used. For more details - link .	String
SupplierIds	The list of suppliers by their IDs in Ratefox. If set then Ratefox only searches for better rates among the listed suppliers. Integrated suppliers list https://documentation.hsp.gimmonix.com/docs/hsp-hotels-integrated-suppliers	Array of Integer
ExcludeFromRebooker	Makes sense if client uses Rebook (adjusted by Ratefox team). Allows to switch off Rebook for created Ratefox booking	Boolean

(*) Examples of price (P) calculations for comparison with alternative packages’ prices.

	Ex.1	Ex.2	Ex.3	Ex.3
BookingPrice	500	500	500	500
TotalTax
Amount	100	100	100	100
IsIncluded	true	false	true	false
TotalFee
Amount	50	50	50	50
IsIncluded	true	false	false	true
Commission
Amount	25	25	25	25

General formula:

P = BookingPrice - Commission.Amount + If(TotalTax.Included == True; 0; TotalTax.Amount) - If(TotalFee.Included == True; TotalFee.Amount; 0)

Ex.1: P = 500 - 50 - 25 = 425

Ex.2: P = 500 + 100 - 25 = 575

Ex.3: P = 500 - 25 = 475

Ex.4: P = 500 + 100 - 50 - 25 = 525

Response parameters

Field	Description	Format	Mandatory
Result	object. Filled in if Ratefox has made the booking		Yes
GimmonixHotelId	Ratefox internal Hotel Id.	Integer	Yes
OrderId	Ratefox internal Order Id once a Booking is created. (Used to fetch bookings data in a separate post-booking request)	Integer	Yes
SupplierName	Ratefox internal Supplier Name (The supplier from the booking was made by Ratefox)	String
ContractId	Id of the contract between Client and Supplier in Ratefox	Integer	Yes
SupplierId	Supplier’s ID in Ratefox	Integer	Yes
RequestPrice	The requested price. BookingPrice from the Request after applying Taxes, Fees and Commission (see request description above) The Supplier Buying Price.	Double	Yes
RequestPriceInClientCurrency	Request price in client currency	Double	Yes
RequestedCurrency	The currency requested.	String ISO Currency Code	Yes
ClientCurrency	The currency of client's account settings (adjusted by Ratefox team)	String ISO Currency Code	Yes
FinalPrice	Final Price of the booking made by Ratefox.	Double	Yes
FinalPriceInClientCurrency	Final Price of the booking in client currency	Double	Yes
Revenue	[RequestPrice - FinalPrice] - the profit increase occurred by deducting the requested and final prices.	Double	Yes
RevenueInClientCurrency	Revenue in client currency	Double	Yes
IsProfitRequirementMet	Is returned if in client settings fallback to zero profit is allowed (adjusted by Ratefox team). `True` if Revenue is greater than threshold from client settings. `False` if Revenue is less than threshold from client settings (in this case booking is created without expected profit as a start point for Rebook).	Boolean
CustomBookingReference	The value from the request	String
Segments	Array of objects. Depending on the supplier multi-room booking may have one or several segments	Array
SegmentId	Ratefox Segment Id. (Used to cancel / Check-status in a separate post-booking request)	Integer	Yes
Status	Segment status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses. Note: in Evaluation mode Segment status is “EV” (successful Ratefox request doesn’t result real booking)	String
IsRebookCandidate	Is returned if in client settings Rebook is enabled (adjusted by Ratefox team). `True` if the segment is a candidate for rebooking (meets Rebook restrictions and in Ratefox request ExcludeFromRebooker = false). `False` if the segment won't be taken into account by Rebook.	Boolean
Rooms	Array of objects.	Array
RoomName	The name of the booked room.	String
MealPlan	The Basis / meal-plan of the booked room.	String
TotalPrice	object
Commission	Commission amount	Double	Yes
CommissionInSupplierCurrency	Commission amount in SupplierCurrency	Double	Yes
Currency	Currency specified in the request in Price.	String ISO Currency Code	Yes
FinalPrice	The final price of the booking in Currency	Double	Yes
FinalPriceInSupplierCurrency	The price of the booking in Suppliers Currency	Double	Yes
SupplierCurrency	The currency in which the price were originally received from the supplier.	String ISO Currency Code
TaxesAndFees	Array of objects	array
FeeTitle	the tax or fee title as returned by the supplier	String
IsIncludedInPrice	is this tax or fee included in the FinalPrice	Boolean
IsMandatory	is the tax or fee mandatory to be paid. For instance, 'resort fees' are typically mandatory, while 'wifi fee' might be not.	Boolean
Currency	Currency specified in the request in Price.Currency	String ISO Currency Code
UnitType	represents the category of the tax or fee: “Other” (not specified), “NotApplicable” (the supplier specified that this tax/fee is not applicable for the selected room), “NotSpecified”, “PerOccurrence” (of the fee title), “PerItem” (eg.: number of speedboats), “PerReservation” (the tax/fee will be applied per the entire reservation), “PerChild”, “PerAdult”, “PerNight”, “PerRoom”, “PerStay”, “PerPerson”.	String
FrequencyType	represents the repetitive type of tax or fee: “Other”, ”NotApplicable”, “NotSpecified”, “PerMinute”, “PerHour”, ”PerHalfDay”, “PerNight”, “PerWeek”, “PerStay”.	String
Value	the decimal value of the taxes and fees	String
IsValuePercentage	is the tax or fee a percentage value or an absolute value	Boolean
Remarks	the tax or fee description as the supplier returned	String
SupplierReservationDetails	object
BookingID	Supplier’s booking confirmation Id	String
BookingReference	Supplier’s booking reference	String
BookingRemarks	Supplier’s booking remarks	String
SupplierVoucherId	Supplier’s voucher Id	String
PostBookingPriceChange	True if supplier changed the price (reduced or increased) while booking action was proceed.	Boolean
CancellationPolicies	Array of objects	Array
CancellationFee	Same approach to detail CancellationFee as for the TotalPrice object above		Yes
Commission		Double	Yes
CommissionInSupplierCurrency		Double	Yes
Currency		String ISO Currency Code
FinalPrice	The charge amount in case of cancellation	Double	Yes
FinalPriceInSupplierCurrency	The charge amount in case of cancellation in supplier currency	Double	Yes
SupplierCurrency		String ISO Currency Code
DateFrom	first date and time of the cancellation policy. Time is GMT. Please be aware that we won't be able to service complaints on a cancellation fee that was charged by the supplier because of time-zone differences between the supplier cancellation policy time to your time	String Unix Epoch time	Yes
DateTo	end date and time for the policy. Time is GMT.	String Unix Epoch time	Yes
Description	policy description as returned from the supplier.	String
Errors	Array of error codes and messages.	Array
Message	error description	String
ErrorCode	List of possible error codes with description https://documentation.hsp.gimmonix.com/docs/error-code-handling	String
ErrorText	short error message	String

Example Request

{
  "SupplierHotel": {
    "SupplierId": 1077,
    "SupplierHotelId": "60055"
  },
  "CheckIn": "2025-03-20T09:36:37.099Z",
  "CheckOut": "2025-03-21T09:36:37.099Z",
  "Residency": "IL",
  "Price": {
    "BookingPrice": 261,
    "Currency": "USD",
    "TotalTax": {
      "Amount": 10,
      "IsIncluded": true,
      "Currency": "USD"
    },
    "TotalFee": {
      "Amount": 10,
      "IsIncluded": false,
      "Currency": "USD"
    },
    "Commission": {
      "Amount": 100,
      "Currency": "USD"
     }
    },
  "RefundableUntil": "2025-02-25T09:36:37.099Z",
  "Rooms": [
    {
      "AdultsCount": 2,
      "Id": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
      "RoomBasis": "room only",
      "RoomName": "Standard",
      "KidsAges": [1]
    }
  ],
  "WorkMode": "Evaluation",
  "LeadPassenger": {
    "Id": "7e6f9032-fe51-4759-b88a-22c5c75a825e",
    "Allocation": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
    "Name": {
                    "GivenName": "Aras",
                    "NamePrefix": "Mr",
                    "Surname": "Akkar"
    },
    "Type": "Adult"
  },
"AdditionalPassengers": [
    {
      "Id": "0f741b1e-5e59-4fa9-ba61-84f5ecdd9988",
      "Allocation": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
      "Name": {
        "GivenName": "Nadu",
        "NamePrefix": "Ms",
        "Surname": "Akkar"
      },
      "Type": "Adult",
      "Age": 21
    },
    {
      "Id": "1f2c479a-354c-46a8-ade2-7b34927cadc6",
      "Allocation": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
      "Name": {
        "GivenName": "Kain",
        "NamePrefix": "Mr",
        "Surname": "Akkar"
      },
      "Type": "Child",
      "Age": 1
    }
  ],
  "LeadPaxRoomId": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
  "Language": "en"
}

✅
More Code Examples

Example Response

{
    "result": {
        "gimmonixHotelId": 4137826,
        "orderId": 3861446,
        "supplierName": "HB2",
        "contractId": 14821,
        "supplierId": 1123,
        "requestPrice": 161.0,
        "requestedCurrency": "USD",
        "finalPrice": 150.87,
        "profit": 9.09,
        "revenue": 10.129999999999999,
        "segments": [
            {
                "segmentId": 3888217,
                "status": "EV",
                "totalPrice": {
                    "commission": 0.0,
                    "commissionInSupplierCurrency": 0.0,
                    "currency": "USD",
                    "finalPrice": 150.87,
                    "finalPriceInSupplierCurrency": 150.87,
                    "supplierCurrency": "USD",
                    "taxesAndFees": []
                },
                "supplierReservationDetails": {
                    "bookingID": null,
                    "bookingReference": null,
                    "bookingRemarks": " .  Car park YES (With additional debit notes).Check-in hour 16:00-.",
                    "supplierVoucherId": null
                },
                "postBookingPriceChange": false,
                "rooms": [
                    {
                        "roomName": "DOUBLE STANDARD",
                        "mealPlan": "ROOM ONLY"
                    }
                ],
                "cancellationPolicies": [
                    {
                        "cancellationFee": {
                            "commission": 0.0,
                            "commissionInSupplierCurrency": 0.0,
                            "currency": "USD",
                            "finalPrice": 150.87,
                            "finalPriceInSupplierCurrency": 150.87,
                            "supplierCurrency": "USD"
                        },
                        "dateFrom": "2025-03-09T00:00:00",
                        "dateTo": "9999-12-31T00:00:00",
                        "description": null
                    }
                ]
            }
        ]
    },
    "errors": []
}

Response Codes :

200 - OK
403 - Forbidden.
500 - Internal Server Error.

✅ POST /hotels/prefetch

Prefetch Mode Ratefox API request (pre-loading data, no booking is made). To proceed with the booking, a subsequent Ratefox API call is required.

👍
Notes and Tips :

The Prefetch Request will store room information for period of time specified in Client configurations.

For the Ratefox API request to recognize the prefetch results, the information must be identical to the previous Prefetch request (including Room Name, Basis, Cancellation Policy, Check-in/out dates, number of Adults and Kids, Booking price, Hotel, etc.). Otherwise the Ratefox API request will proceed detached.

Request Parameters

Field	Description	Format	Mandatory
SupplierHotel	object		Yes
SupplierId	Supplier’s ID in Ratefox. Integrated suppliers list: https://documentation.hsp.gimmonix.com/docs/hsp-hotels-integrated-suppliers	Integer	Yes
SupplierHotelId	Supplier’s HotelID - the corresponding supplier's Hotel key / Id, used to identify the desired property.	String	Yes
CheckIn	Check-in date	String Unix Epoch time	Yes
CheckOut	Check-out date	String Unix Epoch time	Yes
Residency	The lead passenger residency	String(2) ISO Country Code (Ex: US, CZ, IL)	Yes
Price	object		Yes
BookingPrice	The price from client’s booking flow. Taxes, fees and commission from the request will be applied to the BookingPrice to obtain “clear” price for comparison with alternative packages’ prices. See examples below the /hotels/ratefox endpoint request parameters table . The Supplier Buying Price.	Double	Yes
Currency	The currency of the BookingPrice. Rates in response will be in this currency	String(3) ISO Currency Code (Ex: USD, EUR)	Yes
TotalTax	object
Amount	Amount of taxes	Double	Yes
IsIncluded	Are taxes included in the BookingPrice. If false - excluded, BookingPrice will be increased by Tax Amount before comparing with alternative packages’ prices. When true does not affect.	Boolean	Yes
Currency	If not provided, then Price Currency is used	String(3) ISO Currency Code
TotalFee	object
Amount	Amount of fees	Double	Yes
IsIncluded	Are fees included in the BookingPrice. If true - included, BookingPrice will be reduced by Fee Amount before comparing with alternative packages’ prices. When false does not affect.	Boolean	Yes
Currency	If not provided, then Price Currency is used	String(3) ISO Currency Code
Commission	object
Amount	Amount of client’s commission. BookingPrice will be reduced by Commission Amount before comparing with alternative packages’ prices.	Double	Yes
Currency	ISO Currency Codes. If not provided, then Price Currency is used	String(3) ISO Currency Codes
RefundableUntil	Refundability deadline	String Unix Epoch time	Yes
Rooms	Array of objects. Possible room quantity is between 1 and 4	Array	Yes
Id	Room Id inside the request. Is generated by client GUID. Should be a unique per each room in the array	GUID	Yes
RoomName	The name of the booked room in supplier terms. Examples: "Standard Room", "Double with sea view", "Triple", "Family Room", etc. (In any language)	String	Yes
RoomBasis	The meal-plan, ”Board” (as it used by supplier from SupplierID).Examples: "Room Only", "Bed and Breakfast", "Half Board", "Full Board", "All Inclusive".	String	Yes
AdultsCount	Number of adults in the room. The value must be between 1 and 8	Integer	Yes
KidsAges	Array of kids ages. Each value must be between 0 and 17. If empty, there are no kids in the room	Array of integer
WorkMode	Defines the WorkMode for the request. Possible values: “live”. Can be used only by the client which is set “live” in Gimmonix. The request in this mode produces the real booking; “evaluation”. The mode for testing and evaluation. The request in this mode doesn’t produce the real booking but full description of Ratefox found alternative is steal returned. This mode can be used by both clients connected to Ratefox as "evaluation" (new clients before the certification stage is completed) and those who are set "live". More about evaluation mode - link .	String	Yes
Language	Only “en” is currently supported	String	Yes
PointOfSale	Defines the sales channel. Acceptable values must be agreed between the client and Ratefox. No predefined values are used. For more details - link .	String
SupplierIds	The list of suppliers by their IDs in Ratefox. If set then Ratefox only searches for better rates among the listed suppliers. Integrated suppliers list https://documentation.hsp.gimmonix.com/docs/hsp-hotels-integrated-suppliers	Array of Integer

Example Request

{
  "SupplierHotel": {
    "SupplierId": 1077,
    "SupplierHotelId": "60055"
  },
  "CheckIn": "2025-01-21T12:30:03.205Z",
  "CheckOut": "2025-01-21T12:30:03.205Z",
  "Residency": "IL",
  "Price": {
    "BookingPrice": 261,
    "Currency": "USD",
    "TotalTax": {
      "Amount": 8,
      "IsIncluded": true,
      "Currency": "USD"
    },
    "TotalFee": {
      "Amount": 6.2,
      "IsIncluded": true,
      "Currency": "USD"
    },
    "Commission": {
      "Amount": 0,
      "Currency": "USD"
    }
  },
  "RefundableUntil": "2025-01-21T12:30:03.205Z",
  "Rooms": [
    {
      "Id": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
      "RoomName": "Standard Room with See View",
      "RoomBasis": "Bed and Breakfast",
      "AdultsCount": 2,
      "KidsAges": [
        3
      ]
    }
  ],
  "Language": "en",
  "WorkMode": "Evaluation"
}

✅
More Code Examples

Example Response

{
	"result": {
		"success": true
	},
	"errors": []
}

✅ POST /hotels/rebook

Launch Rebook monitoring for a booking created on a client side. Full booking description should be provided in the API request.

❗️
Terms of use:
By launching Rebook monitoring for a booking made directly with a supplier, the client agrees to the following: upon receiving a rebooking notification from Ratefox, the client is responsible for canceling their original booking.
This requirement applies only to the initial rebooking. For subsequent rebookings, Rebook will automatically cancel the previous booking (as it was initiated through Ratefox).

👍
Note:
Rebook request parameters correspond to the same parameters of the Ratefox request.

Request Parameters

Field	Description	Format	Mandatory
SupplierHotel	object		Yes
SupplierId	Supplier’s ID in Ratefox. Integrated suppliers list https://documentation.hsp.gimmonix.com/docs/hsp-hotels-integrated-suppliers	Integer	Yes
SupplierHotelId	Supplier’s HotelID - the corresponding supplier's Hotel key / Id, used to identify the desired property.	String	Yes
CheckIn	Check-in date	String - Unix Epoch time	Yes
CheckOut	Check-out date	String - Unix Epoch time	Yes
Residency	The lead passenger residency.	String (2) ISO Country Code `(Ex: US, CZ, IL)`	Yes
Price	object		Yes
BookingPrice	The price from client’s booking flow. Taxes, fees and commission from the request will be applied to the BookingPrice to obtain “clear” price for comparison with alternative packages’ prices. See examples below the table. The Supplier Buying Price.	Double	Yes
Currency	The currency of the BookingPrice. Rates in response will be in this currency.	String (3) ISO Currency Code `(Ex: USD, EUR)`	Yes
TotalTax	object
Amount	Amount of taxes	Double	Yes
IsIncluded	Are taxes included in the BookingPrice. If `false` -excluded, BookingPrice will be increased by Tax Amount before comparing with alternative packages’ prices. When `true` does not affect.	Boolean	Yes
Currency	If not provided, then `Price Currency` is used.	String (3) ISO Currency Code
TotalFee	object
Amount	Amount of fees	Double	Yes
IsIncluded	Are fees included in the BookingPrice. If `true` - included, BookingPrice will be reduced by Fee Amount before comparing with alternative packages’ prices. When `false` does not affect.	Boolean	Yes
Currency	If not provided, then `Price Currency` is used	String (3) ISO Currency Code
Commission	object
Amount	Amount of client’s commission. BookingPrice will be reduced by Commission Amount before comparing with alternative packages’ prices.	Double	Yes
Currency	If not provided, then `Price Currency` is used	String (3) ISO Currency Codes
RefundableUntil	Refundability deadline. (If Non-Refundable, specify the same date of the request).	String Unix Epoch time	Yes
Rooms	Array of objects. (Max. Rooms - 4)	Array	Yes
Id	Room Id inside the request. Self-generated GUID. Should be a unique per each room in the array.	GUID	Yes
RoomName	The name of the booked room in supplier terms Examples: "Standard Room", "Double with sea view", "Triple", "Family Room", etc. (In any language)	String	Yes
RoomBasis	The meal-plan, ”Board” (as it used by supplier from SupplierID). Examples: "Room Only", "Bed and Breakfast", "Half Board", "Full Board", "All Inclusive".	String	Yes
AdultsCount	Number of adults in the room. (Max. Adults - 8).	Integer	Yes
KidsAges	Array of kids ages. Each value must be between 0 and 17. If empty, there are no kids in the room.	Array of integer
WorkMode	should be "Evaluation"	String
LeadPassenger	Object. The main passenger from the booking		Yes
Id	Lead passenger’s Id inside the request. Self-generated GUID. Should be a unique per each passenger in the request.	GUID	Yes
Allocation	The Allocation of the Pax from the RoomId/s from Rooms array. Identifies the room for the LeadPassenger.	GUID	Yes
Name	object		Yes
GivenName	First name. Use English characters only, otherwise the booking might fail on the supplier side.	String(50)	Yes
NamePrefix	Mr, Mrs, Ms etc. If not provided, “Mr” is used.	String
Surname	Last name. Use English characters only, otherwise the booking might fail on the supplier side.	String(50)
Type	Must be “adult” for the LeadPassenger	String	Yes
Age	Lead passenger's age.	Integer
PhoneNumber	Passenger’s phone number to specify in the booking.	String(50)
CustomerEmail	Passenger’s email to specify in the booking.	String(254)
Address	object. Address details to specify in the booking
CountryCode	The country code of the passenger.	String(2) ISO Country Code (Ex: US, CZ, IL)
AddressLine	The address of the passenger.	String(254)
StateProv		String(20)
PostalCode		String(20)
AdditionalPassengers	Array of objects. All passengers (adults and kids) except LeadPassenger must be described in this array.	Array
Id	Passenger’s Id inside the request. Self-generated GUID. Should be a unique per each passenger in the request	GUID	Yes
Allocation	The Allocation of the Pax from the RoomId/s from Rooms array. Identifies the room for the AdditionalPassengers.	GUID	Yes
Name	object		Yes
GivenName	First name. Use English characters only, otherwise the booking might fail on the supplier side.	String(50)
NamePrefix	Mr, Mrs, Ms etc. If not provided, “Mr” is used.	String
Surname	Last name. Use English characters only, otherwise the booking might fail on the supplier side.	String(50)
Type	“adult” or “child”.	String	Yes
Age	Mandatory in case the passenger’s type is ”child”. The value must be between 0 and 17 and match one of the KigsAges array’s values.	Integer
LeadPaxRoomId	Id from Rooms array. Identifies the room of the LeadPassenger	GUID	Yes
Language	Only “en” is currently supported	String	Yes
RoomsRemarks	Free text remarks to be sent to the supplier within booking. Collection of "Key" : "Value” pairs, where Key is room Id from the Rooms array. Only suppliers that support this feature will receive the remarks.
InternalAgentRef1	Agent reference of the booking.	String
CustomBookingReference	Client reference. Should be unique for each client booking.	String	Yes

Response parameters

Field	Description	Format	Mandatory
Result	object
CustomBookingReference	as from request	String	Yes
OrderId	Ratefox internal Order Id for a booking under Rebook monitoring. (Used to fetch current booking data and the history of rebookings in a separate post-booking OrderData request, to exclude the booking from Rebook monitoring in a separate post-booking Excludefromrebooker request)	String	Yes
SegmentId	Ratefox Segment Id. (Used to cancel / check-status in a separate post-booking requests)	String	Yes
Errors	Array of error codes and messages.	Array
Message	error description	String
ErrorCode	List of possible error codes with description https://documentation.hsp.gimmonix.com/docs/error-code-handling	String
ErrorText	short error message	String

Example Request

{
  "SupplierHotel": {
    "SupplierId": 1058,
    "SupplierHotelId": "1032268"
  },
  "CheckIn": "2025-08-25T00:00:00.099Z",
  "CheckOut": "2025-08-26T00:00:00.099Z",
  "CustomBookingReference": "CR0108",
  "Residency": "IL",
  "Price": {
    "BookingPrice": 180,
    "Currency": "USD"
    },
  "RefundableUntil": "2025-08-01T00:00:00.099Z",
  "Rooms": [
    {
                    "AdultsCount": 2,
                    "Id": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
                    "RoomBasis": "room only",
                    "RoomName": "Standard",
                    "KidsAges": []
    }
  ],
  "WorkMode": "Evaluation",
  "LeadPassenger": {
    "Id": "7e6f9032-fe51-4759-b88a-22c5c75a825e",
    "Allocation": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
    "Name": {
                    "GivenName": "Adam",
                    "NamePrefix": "Mr",
                    "Surname": "Taros"
    },
    "Type": "Adult"
  },
"AdditionalPassengers": [
    {
      "Id": "0f741b1e-5e59-4fa9-ba61-84f5ecdd9988",
      "Allocation": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
      "Name": {
        "GivenName": "Nadia",
        "NamePrefix": "Ms",
        "Surname": "Taros"
      },
      "Type": "Adult",
      "Age": 21
    }
  ],
  "LeadPaxRoomId": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
  "Language": "en"
}

✅
More Code Examples

Example Response

{
    "result": {
        "customBookingReference": "CR0108",
        "orderId": 3879909,
        "segmentId": 3906741
    },
    "errors": []
}

Post Booking

✅ POST `/hotels/cancel/{segmentId}`

Cancel the Ratefox segment reservation with specified ID.

Since the cancellation request is also sent to the booking supplier, the Cancel endpoint only performs any actions for segments, created in "Live" work mode, and returns an error for segments created in "Evaluation" work mode.

👍
Notes and Tips :
Multi-Room Reservations

There are suppliers that return a single booking confirmation id for all rooms together - on Ratefox all rooms will be under single Segment ID.

There are suppliers that return for each room a unique booking confirmation id - on Ratefox each room will have his own Segment ID (correlated with supplier).

'Cancel Book' request supports single Segment ID only.
For case (1): all rooms will be cancelled at once.
For case (2): requires to send a 'Cancel Book' request per each SegmentID. Or cancel part of the rooms by relevant SegmentIDs.

Request Parameters

segmentId - Integer.
(The segmentId is returned as part of Ratefox Response)

Response parameters

Field	Description	Format
BookCancelID	Cancellation ID	String
CancellationComment	Cancellation Comment	String
CancellationFee	Cancellation Fee	Double
Currency	Currency of the cancellation fee	String ISO Currency Code
Status	Cancellation Status. Possible statuses list: `<https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-cancellation-statuses>`	String
Errors	Array of error codes and messages.	Array
Message	error description	String
ErrorCode	List of possible error codes with description `<https://documentation.hsp.gimmonix.com/docs/error-code-handling>`	String
ErrorText	short error message	String

Example Request

curl --request POST \
     --url https://example.com/hotels/cancel/454974 \
     --header 'accept: application/json' \
     --header 'authorization: Basic VGVzdFVzZXJOYW1lOmFzZGFkc2E='

✅
More Code Examples

Example Response

{
  "Result": {
    "BookCancelID": "string",
    "CancellationComment": "string",
    "CancellationFee": 0,
    "Currency": "string",
    "Status": "string"
  },
  "Errors": [
    {
      "Message": "string",
      "ErrorCode": "string",
      "ErrorText": "string"
    }
  ]
}

✅ POST `/hotels/checkstatus/{segmentId}`

Check status of the Ratefox segment reservation with specified ID.

Since the status is checked with the booking supplier, the Checkstatus endpoint only performs any actions for segments, created in "Live" work mode, and returns an error for segments created in "Evaluation" work mode.

Request Parameters

segmentId - Integer.
(The segmentId is returned as part of Ratefox Response)

Response parameters

Field	Description	Format
Status	Segment Status. Possible statuses list: `<https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses>`	String
Errors	Array of error codes and messages.	Array
Message	error description	String
ErrorCode	List of possible error codes with description `<https://documentation.hsp.gimmonix.com/docs/error-code-handling>`	String
ErrorText	short error message	String

Example Request

curl --request POST \
     --url https://example.com/hotels/checkstatus/454974 \
     --header 'accept: application/json' \
     --header 'authorization: Basic VGVzdFVzZXJOYW1lOmFzZGFkc2E='

✅
More Code Examples

Example Response

{
  "Result": {
    "Status": "OK"
  },
  "Errors": [
    {
      "Message": "string",
      "ErrorCode": "string",
      "ErrorText": "string"
    }
  ]
}

✅ GET `/hotels/orderdata/{orderId}`

Provide description of the Ratefox order (booking) reservation with specified ID.

Request Parameters

orderid - Integer.
(The orderid is returned as part of Ratefox Response)

Response parameters

Field	Description	Format	Mandatory
Result	object
OrderId	Ratefox internal Id of the booking	Integer	Yes
SupplierId	Supplier’s ID in Ratefox	Integer	Yes
SupplierName	Ratefox internal Supplier Name (supplier from the booking made by Ratefox)	String	Yes
HotelId	Ratefox Hotel Id	String	Yes
ContractId	Id of the contract between Client and Supplier in Ratefox	Integer	Yes
RequestPrice	BookingPrice from the Request after applying Taxes, Fees and Commission (see Ratefox API request description above)	Double	Yes
RequestPriceInClientCurrency		Double
RequestCurrency	Price.Currency from the request	String ISO Currency Code	Yes
ClientCurrency	Client currency as set in client settings by Ratefox team. This currency is ones agreed between the client and the Ratefox and isn't changed after	String ISO Currency Code	Yes
FinalPrice	Price from the booking made by Ratefox. If booking was rebooked by Rebook in live mode than Price of the last rebooking.	Double	Yes
FinalPriceInClientCurrency		Double
Revenue	Profit increase generated by the booking. If booking was rebooked by Rebook in live mode than Profit increase generated by the last rebooking.	Double	Yes
RevenueInClientCurrency		Double
TotalRevenue	Is returned if in client settings Rebook is enabled (adjusted by Ratefox team). If the booking was rebooked TotalRevenue contains total profit increase generated by Ratefox and Rebook. Only live rebookings are taken into account.	Double
TotalRevenueInClientCurrency		Double
CheckIn		String Unix Epoch time	Yes
CheckOut		String Unix Epoch time	Yes
CustomBookingReference	The value from the Ratefox request	String
IsProfitRequirementMet	Is returned if Rebook is enabled for the client. `True` if initial booking created by Ratefox generated Revenue greater than threshold from client settings. `False` if Revenue was less than threshold from client settings (in this case booking was created without expected profit as a start point for Rebook).	Boolean
Segments	Array of objects
SegmentId	Ratefox Segment Id	Integer	Yes
Status	Segment status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses. Note: in Evaluation mode Segment status is “EV” (successful Ratefox request doesn’t result real booking)	String	Yes
IsRebookCandidate	Is returned if in client settings Rebook is enabled (adjusted by Ratefox team). `True` if the segment is a candidate for rebooking (meets Rebook restrictions and in Ratefox request ExcludeFromRebooker = false). `False` if the segment won't be taken into account by Rebook.	Boolean
Rooms	Array of objects
RoomName	The name of the booked room in supplier terms. Examples: "Standard Room", "Double with sea view", "Triple", "Family Room", etc.	String	Yes
MealPlan	The meal-plan name of the booked room in supplier terms	String	Yes
TotalPrice	object
Commission	Commission amount	Double	Yes
CommissionInSupplierCurrency	Commission amount in SupplierCurrency	Double	Yes
Currency	Currency specified in the request in Price.Currency	String ISO Currency Code	Yes
FinalPrice	the price of the booking in Currency	Double	Yes
FinalPriceInSupplierCurrency	the price of the booking in SupplierCurrency	Double	Yes
SupplierCurrency	The currency in which the price were originally received from the supplier	String ISO Currency Code
TaxesAndFees	Array of objects	array
FeeTitle	the tax or fee title as returned by the supplier	String
IsIncludedInPrice	is this tax or fee included in the FinalPrice	Boolean
IsMandatory	is the tax or fee mandatory to be paid.	Boolean
Currency	Currency specified in the request in Price.Currency	String ISO Currency Code
UnitType	represents the category of the tax or fee: “Other” (not specified), “NotApplicable” (the supplier specified that this tax/fee is not applicable for the selected room), “NotSpecified”, “PerOccurrence” (of the fee title), “PerItem” (eg.: number of speedboats), “PerReservation” (the tax/fee will be applied per the entire reservation), “PerChild”, “PerAdult”, “PerNight”, “PerRoom”, “PerStay”, “PerPerson”.	String
FrequencyType	represents the repetitive type of tax or fee: “Other”, ”NotApplicable”, “NotSpecified”, “PerMinute”, “PerHour”, ”PerHalfDay”, “PerNight”, “PerWeek”, “PerStay”.	String
Value	the decimal value of the taxes and fees	String
IsValuePercentage	is the tax or fee a percentage value or an absolute value	Boolean
Remarks	the tax or fee description as the supplier returned	String
SupplierReservationDetails	object
BookingID	Supplier’s booking confirmation Id	String
BookingReference	Supplier’s booking reference	String
BookingRemarks	Supplier’s booking remarks	String
SupplierVoucherId	Supplier’s voucher Id	String
CancellationPolicies	Array of objects	Array
CancellationFee		Double	Yes
CancellationFeeInSupplierCurrency		Double	Yes
Currency		String ISO Currency Code
SupplierCurrency		String ISO Currency Code
DateFrom	first date and time of the cancellation policy. Time is GMT. Please be aware that we won't be able to service complaints on a cancellation fee that was charged by the supplier because of time-zone differences between the supplier cancellation policy time to your time	String Unix Epoch time	Yes
DateTo	end date and time for the policy. Time is GMT.	String Unix Epoch time	Yes
Description	policy description as returned from the supplier.	String
History	Array of objects. Is returned if order's segment was rebooked and contains initial segment data and all rebookings data.
ActionDate	Date and time of segment creation	String Unix Epoch time	Yes
Status	Segment status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses.	String	Yes
Revenue	profit increase generated by this segment	Double	Yes
RevenueInClientCurrency	revenue in client's currency	Double	Yes
ContractId		Integer
SupplierId		Integer
SupplierName		String
Rooms	object
RoomName		String
MealPlan		String
TotalPrice		Double
Commission		Double
CommissionInSupplierCurrency		Double
Currency		String ISO Currency Code
FinalPrice		Double
FinalPriceInSupplierCurrency		Double
SupplierCurrency		String ISO Currency Code
TaxesAndFees	array of objects
FeeTitle		String
IsIncludedInPrice		Boolean
IsMandatory		Boolean
Currency		String
UnitType		String
FrequencyType		String
Value		String
IsValuePercentage		Boolean
Remarks		String
SupplierReservationDetails	object
BookingID		String
BookingReference		String
BookingRemarks		String
SupplierVoucherId		String
Initiator	service that created this segment. "Ratefox" - for segment created by Ratefox API request or by Rebook API request, "Rebooker" - for segment created by Rebook monitoring	String	Yes
Errors	Array of error codes and messages.
Message	error description	String
ErrorCode	List of possible error codes with description https://documentation.hsp.gimmonix.com/docs/error-code-handling	String
ErrorText	Short error message	String

Example Request

curl --request GET \
     --url https://example.com/hotels/orderdata/456787 \
     --header 'accept: application/json' \
     --header 'authorization: Basic VGVzdFVzZXJOYW1lOmFzZGFkc2E='

✅
More Code Examples

Example Response

{
 "Result": { 
   "HotelId": 0,
   "OrderId": 0,
   "SupplierName": "string",
   "ContractId": 0,
   "SupplierId": 0,
   "RequestPrice": 0,
   "RequestedCurrency": "string",
   "FinalPrice": 0,
   "Profit": 0,
   "CheckIn": "2025-01-21T12:43:38.569Z",
   "CheckOut": "2025-01-21T12:43:38.569Z",
   "Segments": [
    {
      "SegmentId": 0,
      "Status": "string",
      "Rooms": [
        {
          "RoomName": "string",
          "MealPlan": "string"
        }
      ],
      "TotalPrice": {
        "Commission": 0,
        "CommissionInSupplierCurrency": 0,
        "Currency": "string",
        "FinalPrice": 0,
        "FinalPriceInSupplierCurrency": 0,
        "SupplierCurrency": "string",
        "TaxesAndFees": [
          {
            "FeeTitle": "string",
            "IsIncludedInPrice": true,
            "IsMandatory": true,
            "Currency": "string",
            "UnitType": "string",
            "FrequencyType": "string",
            "Value": "string",
            "IsValuePercentage": true,
            "Remarks": "string"
          }
        ]
      },
      "SupplierReservationDetails": {
        "BookingID": "string",
        "BookingReference": "string",
        "BookingRemarks": "string",
        "SupplierVoucherId": "string"
      },
      "CancellationPolicies": [
        {
          "CancellationFee": 0,
          "CancellationFeeInSupplierCurrency": 0,
          "Currency": "string",
          "SupplierCurrency": "string",
          "DateFrom": "2025-01-21T12:43:38.569Z",
          "DateTo": "2025-01-21T12:43:38.569Z",
          "Description": "string"
        }
      ]
    }
  ]
 }
}

✅ POST /hotels/orders

Provide the list of descriptions of the Ratefox orders (bookings) created in a specified period of time.

Request Parameters

Field	Description	Format	Mandatory
FromDate	Date and time of the beginning of the period	String Unix Epoch time	Yes
ToDate	Date and time of the end of the period	String Unix Epoch time	Yes
PageSize	The number of records returned in the response (from 1 to 100)	Integer	Yes
PageNumber	Number of page to be returned. Numeration starts with 0. If not specified, then it is considered equal to 0	Integer

Response Parameters

Field	Description	Format	Mandatory
CurrentPage	Returned page number (same as PageNumber from the request). If PageNumber = 0 in the request CurrentPage isn't returned	Integer
TotalPages	Total number of pages	Integer	Yes
TotalCount	Total number of orders that fit the requested period	Integer	Yes
Orders	Array of objects
OrderId	Ratefox internal Id of the booking	Integer	Yes
SupplierId	Supplier’s ID in Ratefox	Integer	Yes
SupplierName	Ratefox internal Supplier Name (supplier from the booking made by Ratefox)	String	Yes
HotelId	Ratefox Hotel Id	String	Yes
ContractId	Id of the contract between Client and Supplier in Ratefox	Integer	Yes
RequestPrice	BookingPrice from the Request after applying Taxes, Fees and Commission (see Ratefox API request description above)	Double	Yes
RequestPriceInClient Currency	Price from the request in clint currency	Double	Yes
RequestCurrency	Price.Currency from the request	String ISO Currency Code	Yes
ClientCurrency	Client currency as set in client settings by Ratefox team. This currency is ones agreed between the client and the Ratefox and isn't changed after	String ISO Currency Code	Yes
FinalPrice	Price from the booking made by Ratefox	Double	Yes
FinalPriceInClientCurrency	Price from the booking made by Ratefox in client currency	Double	Yes
Revenue	RequestPrice - FinalPrice	Double	Yes
RevenueInClientCurrency	Revenue in client currency	Double	Yes
CheckIn		String Unix Epoch time	Yes
CheckOut		String Unix Epoch time	Yes
BookingDate	Order creation date	String Unix Epoch time	Yes
CustomBookingReference	The value from the Ratefox request	String
IsProfitRequirementMet	Is returned if Rebook is enabled for the client. `True` if initial booking created by Ratefox generated Revenue greater than threshold from client settings. `False` if Revenue was less than threshold from client settings (in this case booking was created without expected profit as a start point for Rebook).	Boolean
Segments	Array of objects
SegmentId	Ratefox Segment Id	Integer	Yes
Status	Segment status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses. Note: in Evaluation mode Segment status is “EV” (successful Ratefox request doesn’t result real booking)	String	Yes
IsRebookCandidate	Is returned if in client settings Rebook is enabled (adjusted by Ratefox team). `True` if the segment is a candidate for rebooking (meets Rebook restrictions and in Ratefox request ExcludeFromRebooker = false). `False` if the segment won't be taken into account by Rebook.	Boolean
Rooms	Array of objects
RoomName	The name of the booked room in supplier terms	String	Yes
MealPlan	The meal-plan name of the booked room in supplier terms	String	Yes
TotalPrice	object
Commission	Commission amount	Double	Yes
CommissionInSupplier Currency	Commission amount in SupplierCurrency	Double	Yes
Currency	Currency specified in the request in Price.Currency	String ISO Currency Code	Yes
FinalPrice	the price of the booking in Currency	Double	Yes
FinalPriceInSupplier Currency	the price of the booking in SupplierCurrency	Double	Yes
SupplierCurrency	The currency in which the price were originally received from the supplier	String ISO Currency Code
TaxesAndFees	Array of objects	array
FeeTitle	the tax or fee title as returned by the supplier	String
IsIncludedInPrice	is this tax or fee included in the FinalPrice	Boolean
IsMandatory	is the tax or fee mandatory to be paid.	Boolean
Currency	Currency specified in the request in Price.Currency	String ISO Currency Code
UnitType	represents the category of the tax or fee: “Other” (not specified), “NotApplicable” (the supplier specified that this tax/fee is not applicable for the selected room), “NotSpecified”, “PerOccurrence” (of the fee title), “PerItem” (eg.: number of speedboats), “PerReservation” (the tax/fee will be applied per the entire reservation), “PerChild”, “PerAdult”, “PerNight”, “PerRoom”, “PerStay”, “PerPerson”.	String
FrequencyType	represents the repetitive type of tax or fee: “Other”, ”NotApplicable”, “NotSpecified”, “PerMinute”, “PerHour”, ”PerHalfDay”, “PerNight”, “PerWeek”, “PerStay”.	String
Value	the decimal value of the taxes and fees	String
IsValuePercentage	is the tax or fee a percentage value or an absolute value	Boolean
Remarks	the tax or fee description as the supplier returned	String
SupplierReservationDetails	object
BookingID	Supplier’s booking confirmation Id	String
BookingReference	Supplier’s booking reference	String
BookingRemarks	Supplier’s booking remarks	String
SupplierVoucherId	Supplier’s voucher Id	String
CancellationPolicies	Array of objects	Array
CancellationFee		Double	Yes
CancellationFeeInSupplier Currency		Double	Yes
Currency		String ISO Currency Code
SupplierCurrency		String ISO Currency Code
DateFrom	first date and time of the cancellation policy. Time is GMT. Please be aware that we won't be able to service complaints on a cancellation fee that was charged by the supplier because of time-zone differences between the supplier cancellation policy time to your time	String Unix Epoch time	Yes
DateTo	end date and time for the policy. Time is GMT.	String Unix Epoch time	Yes
Description	policy description as returned from the supplier.	String
History	Array of objects. Is returned if order's segment was rebooked and contains initial segment data and all rebookings data.
ActionDate	Date and time of segment creation	String Unix Epoch time	Yes
Status	Segment status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses.	String	Yes
Revenue	profit increase generated by this segment	Double	Yes
RevenueInClientCurrency	revenue in client's currency	Double	Yes
ContractId		Integer
SupplierId		Integer
SupplierName		String
Rooms	object
RoomName		String
MealPlan		String
TotalPrice		Double
Commission		Double
CommissionInSupplierCurrency		Double
Currency		String ISO Currency Code
FinalPrice		Double
FinalPriceInSupplierCurrency		Double
SupplierCurrency		String ISO Currency Code
TaxesAndFees	array of objects
FeeTitle		String
IsIncludedInPrice		Boolean
IsMandatory		Boolean
Currency		String
UnitType		String
FrequencyType		String
Value		String
IsValuePercentage		Boolean
Remarks		String
SupplierReservationDetails	object
BookingID		String
BookingReference		String
BookingRemarks		String
SupplierVoucherId		String
Initiator	service that created this segment. "Ratefox" - for segment created by Ratefox API request or by Rebook API request, "Rebooker" - for segment created by Rebook monitoring	String	Yes
Errors	Array of error codes and messages.
Message	error description	String
ErrorCode	List of possible error codes with description https://documentation.hsp.gimmonix.com/docs/error-code-handling	String
ErrorText	Short error message	String

Example Request

{
  "FromDate": "2025-03-02T00:00:00.099Z",
  "ToDate": "2025-03-02T23:59:59.999Z",
  "PageSize": 3,
  "PageNumber": 2
}

✅
More Code Examples

Example Response

{
    "currentPage": 2,
    "totalPages": 15,
    "totalCount": 44,
    "orders": [
        {
            "orderId": 3861622,
            "supplierId": 1127,
            "supplierName": "TLA",
            "hotelId": 6846896,
            "contractId": 4331,
            "requestPriceInClientCurrency": 164.26,
            "requestPrice": 164.26,
            "requestedCurrency": "EUR",
            "clientCurrency": "EUR",
            "finalPrice": 161.95,
            "finalPriceInClientCurrency": 161.95,
            "revenueInClientCurrency": 2.31,
            "revenue": 2.31,
            "profit": 1.31,
            "profitInClientCurrency": 1.31,
            "checkIn": "2025-05-01T00:00:01.1",
            "checkOut": "2025-05-02T00:00:01.1",
            "bookingDate": "2025-03-02T10:01:39.733",
            "segments": [
                {
                    "segmentId": 3888394,
                    "status": "EV",
                    "rooms": [
                        {
                            "roomName": "Standard Double room (full double bed)",
                            "mealPlan": "Breakfast"
                        }
                    ],
                    "cancellationPolicies": [
                        {
                            "cancellationFee": {
                                "currency": "EUR",
                                "finalPrice": 161.95,
                                "finalPriceInSupplierCurrency": 161.95,
                                "supplierCurrency": "EUR"
                            },
                            "dateFrom": "2025-04-26T00:00:00",
                            "dateTo": "9999-12-31T00:00:00",
                            "description": "\r\n"
                        }
                    ],
                    "totalPrice": {
                        "currency": "EUR",
                        "finalPrice": 161.95,
                        "finalPriceInSupplierCurrency": 161.95,
                        "supplierCurrency": "EUR",
                        "taxesAndFees": []
                    },
                    "supplierReservationDetails": {
                        "bookingRemarks": "\r\n<p><b>Know Before You Go</b> <br /><ul>  <li>This property offers transfers from the airport (surcharges may apply). Guests must contact the property with arrival details before travel, using the contact information on the booking confirmation. </li>  </ul></p><p><b>Fees</b> <br /><p>The following fees and deposits are charged by the property at time of service, check-in, or check-out. </p> <ul> <li>Breakfast fee: EUR 10 for adults and EUR 10 for children (approximately)</li>      <li>Airport shuttle fee: EUR 40 per vehicle (one way)</li>   <li>Valet parking fee: EUR 25 per day</li>          <li>Rollaway bed fee: EUR 40.0 per night</li>            </ul> <p>The above list may not be comprehensive. Fees and deposits may not include tax and are subject to change. </p></p>\r\nBreakfast for children aged 0-0: 10 EUR\r\nExtra Bed: 40 EUR per guest per night.\r\nParking: 25 EUR per car per night."
                    }
                }
            ]
        },
        {
            "orderId": 3861623,
            "supplierId": 1073,
            "supplierName": "SUN",
            "hotelId": 6846896,
            "contractId": 4158,
            "requestPriceInClientCurrency": 164.26,
            "requestPrice": 164.26,
            "requestedCurrency": "EUR",
            "clientCurrency": "EUR",
            "finalPrice": 155.61,
            "finalPriceInClientCurrency": 155.61,
            "revenueInClientCurrency": 8.65,
            "revenue": 8.65,
            "profit": 7.65,
            "profitInClientCurrency": 7.65,
            "checkIn": "2025-05-01T00:00:01.1",
            "checkOut": "2025-05-02T00:00:01.1",
            "bookingDate": "2025-03-02T10:01:56.077",
            "segments": [
                {
                    "segmentId": 3888395,
                    "status": "EV",
                    "rooms": [
                        {
                            "roomName": "Double room",
                            "mealPlan": "Breakfast"
                        }
                    ],
                    "cancellationPolicies": [
                        {
                            "cancellationFee": {
                                "currency": "EUR",
                                "finalPrice": 155.61,
                                "finalPriceInSupplierCurrency": 162.0,
                                "supplierCurrency": "USD"
                            },
                            "dateFrom": "2025-04-25T00:00:00",
                            "dateTo": "9999-12-31T00:00:00"
                        }
                    ],
                    "totalPrice": {
                        "currency": "EUR",
                        "finalPrice": 155.61,
                        "finalPriceInSupplierCurrency": 162.0,
                        "supplierCurrency": "USD",
                        "taxesAndFees": []
                    },
                    "supplierReservationDetails": {
                        "bookingRemarks": "\r\nFrom 5/1/2025 12:00:00 AM to 5/2/2025 12:00:00 AM:  (CheckIn: 14:00, CheckOut: 12:00)\r\n"
                    }
                }
            ]
        },
        {
            "orderId": 3861624,
            "supplierId": 1073,
            "supplierName": "SUN",
            "hotelId": 6846896,
            "contractId": 4158,
            "requestPriceInClientCurrency": 164.26,
            "requestPrice": 164.26,
            "requestedCurrency": "EUR",
            "clientCurrency": "EUR",
            "finalPrice": 155.61,
            "finalPriceInClientCurrency": 155.61,
            "revenueInClientCurrency": 8.65,
            "revenue": 8.65,
            "profit": 7.65,
            "profitInClientCurrency": 7.65,
            "checkIn": "2025-05-01T00:00:01.1",
            "checkOut": "2025-05-02T00:00:01.1",
            "bookingDate": "2025-03-02T10:02:33.847",
            "segments": [
                {
                    "segmentId": 3888396,
                    "status": "EV",
                    "rooms": [
                        {
                            "roomName": "Double room",
                            "mealPlan": "Breakfast"
                        }
                    ],
                    "cancellationPolicies": [
                        {
                            "cancellationFee": {
                                "currency": "EUR",
                                "finalPrice": 155.61,
                                "finalPriceInSupplierCurrency": 162.0,
                                "supplierCurrency": "USD"
                            },
                            "dateFrom": "2025-04-25T00:00:00",
                            "dateTo": "9999-12-31T00:00:00"
                        }
                    ],
                    "totalPrice": {
                        "currency": "EUR",
                        "finalPrice": 155.61,
                        "finalPriceInSupplierCurrency": 162.0,
                        "supplierCurrency": "USD",
                        "taxesAndFees": []
                    },
                    "supplierReservationDetails": {
                        "bookingRemarks": "\r\nFrom 5/1/2025 12:00:00 AM to 5/2/2025 12:00:00 AM:  (CheckIn: 14:00, CheckOut: 12:00)\r\n"
                    }
                }
            ]
        }
    ],
    "errors": []
}

✅ POST `/hotels/excludefromrebooker/{orderId}`

Exclude the Ratefox order (booking) with specified orderID from Rebook monitoring.

Request Parameters

ordertId - Integer.
(The orderId is returned as part of Ratefox Response or Rebook Response)

Example Request

curl --request POST \
     --url https://example.com/hotels/excludefromrebooker/3906695 \
     --header 'accept: application/json' \
     --header 'authorization: Basic VGVzdFVzZXJOYW1lOmFzZGFkc2E='

✅
More Code Examples

Example Response

{
    "errors": [],
    "success": true
}

🔗 Resources

Hotel Identification: Each request requires a valid SupplierID and the corresponding supplier hotel key. To view the full list of suppliers and their IDs - Click here.
Orders and Segments: Learn more about how orders and segments work, including possible statuses - Click here.
Error Handling and Messages: For information on error codes, informative messages, and handling guidance - Click here.

✔️ Check-List for Starting the Evaluation / Integration

Credentials for RateFox have been obtained.
Access to Grafana - RateFox Monitoring and Insights tool has been granted.
IP Whitelisting: When operating in Evaluation mode with a Live supplier, RateFox IPs must be whitelisted in the supplier's system.

📊 RateFox - Monitoring and Insights

For more information - Click here.

RateFox provides clients with visibility into their request flow, including a breakdown of Winning, Losing, and Invalid cases. This enables clients to better understand their integration, identify failure points, and ensure proper handling—ultimately helping them implement and optimize RateFox more effectively.

📞 Support & During and after Integration.

Our support team is committed to providing support for swift and effective integration, as well as ongoing assistance post-integration.

Should you need help, have questions, or seek clarification either during or after the integration process, you have two options for support:

Search in our Documentation for the information you need. (Recommended)
Submit a ticket to our dedicated support team.

🔧 Introduction

Notes and Tips :

Code Examples

🔑 Authentication

Example :

Code Example :

🛠️ Endpoint Reference

Ratefox API Endpoints

✅ POST /hotels/ratefox

Notes and Tips :

Request Parameters

Response parameters

Example Request

Example Response

✅ POST /hotels/prefetch

Notes and Tips :

Request Parameters

Example Request

Example Response

✅ POST /hotels/rebook

Terms of use:

Note:

Request Parameters

Response parameters

Example Request

Example Response

Post Booking

✅ POST /hotels/cancel/{segmentId}

Notes and Tips :

Request Parameters

Response parameters

Example Request

Example Response

✅ POST /hotels/checkstatus/{segmentId}

Request Parameters

Response parameters

Example Request

Example Response

✅ GET /hotels/orderdata/{orderId}

Request Parameters

Response parameters

Example Request

Example Response

✅ POST /hotels/orders

Request Parameters

Response Parameters

Example Request

Example Response

✅ POST /hotels/excludefromrebooker/{orderId}

Request Parameters

Example Request

Example Response

🔗 Resources

✔️ Check-List for Starting the Evaluation / Integration

📊 RateFox - Monitoring and Insights

📞 Support & During and after Integration.

✅ POST `/hotels/cancel/{segmentId}`

✅ POST `/hotels/checkstatus/{segmentId}`

✅ GET `/hotels/orderdata/{orderId}`

✅ POST `/hotels/excludefromrebooker/{orderId}`