🔧 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 Booking Requests
`POST`	`/hotels/cancel/{segmentId}`	Cancels the RateFox segment reservation with the specified segmentId.
`POST`	`/hotels/checkstatus/{segmentId}`	Checks the status of a RateFox segment reservation with the specified segmentId
`GET`	`/hotels/orderdata/{orderId}`	Returns details of the RateFox segment reservation with the specified orderId

✅ 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 generated 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 (NULL), 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 (NULL), 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 (NULL), 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 requested room (as it used by supplier from SupplierID). Examples: "Standard Room", "Double with sea view", "Triple", "Family Room", etc.	String	Yes
RoomBasis	The meal-plan, ”Board” (as it used by supplier from SupplierID). Possible Values : `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`. “evaluation”. The mode for testing and evaluation. The request in this mode doesn’t produce the real booking. More Information - Click Here.	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 environment. Possible values: - “web” - rates that are available to be sold through desktop websites, - ”mobileapp” - rates that are available to be sold through mobile apps/websites, - ”cug” - Closed User Group. Discounted rates which are sold to ‘members-only’ groups, - ”b2b” - rates which are intended to be sold by travel agents, operating under a B2B booking engine. Suppliers forbid selling B2B rates in B2C channels.	String

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
RequestedCurrency	The currency requested.	String ISO Currency Code
FinalPrice	Final Price of the booking made by Ratefox.	Double	Yes
Revenue	[RequestPrice - FinalPrice] - the profit increase occurred by deducting the requested and final prices.	Double	Yes
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
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 (NULL), 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 (NULL), 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 (NULL), 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 requested room (as it used by supplier from SupplierID). Examples: "Standard Room", "Double with sea view", "Triple", "Family Room", etc.	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

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 Booking

✅ POST /hotels/cancel/{segmentId}

Cancel the Ratefox segment reservation with specified ID.

👍
Notes and Tips :
Multi-Room Reservations

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

There are suppliers that return for each room a unique booking confirmation id - on HSP 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.

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/545647 \
     --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
RequestCurrency	Price.Currency from the request	String ISO Currency Code	Yes
FinalPrice	Price from the booking made by Ratefox	Double	Yes
Revenue	RequestPrice - FinalPrice	Double	Yes
CheckIn		String Unix Epoch time	Yes
CheckOut		String Unix Epoch time	Yes
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
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
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
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"
        }
      ]
    }
  ]
 }
}

🔗 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

✅More Code Examples

Example Response

✅ POST /hotels/prefetch

👍Notes and Tips :

Request Parameters

Example Request

✅More Code Examples

Example Response

Post Booking

✅ POST /hotels/cancel/{segmentId}

👍Notes and Tips :

Request Parameters

Response parameters

Example Request

✅More Code Examples

Example Response

✅ POST /hotels/checkstatus/{segmentId}

Request Parameters

Response parameters

Example Request

✅More Code Examples

Example Response

✅ GET /hotels/orderdata/{orderId}

Request Parameters

Response parameters

Example Request

✅More Code Examples

Example Response

🔗 Resources

✔️ Check-List for Starting the Evaluation / Integration

📊 RateFox - Monitoring and Insights

📞 Support & During and after Integration.

👍
Notes and Tips :

📘
Code Examples

📘
Example :

✅
Code Example :

👍
Notes and Tips :

✅
More Code Examples

👍
Notes and Tips :

✅
More Code Examples

👍
Notes and Tips :

✅
More Code Examples

✅
More Code Examples

✅
More Code Examples