Order API¶

The Order API provides endpoints for creating orders, checking order status, and updating payment information.

NOTE

These endpoints won't be supported in the future. Prefer using the search -> quote -> book flow described on the overview page.

Endpoints¶

GET /api/order/status¶

Retrieve the current status of an order.

Authentication: Required (X-Api-Key)

Query Parameters:

Parameter	Type	Required	Description
`orderId`	string	Yes	Unique order key for the order

Example Request:

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/order/status?orderId=ORDER-123"

Responses:

200 OK: JSON status payload (relayed from upstream)
400 Bad Request: Invalid query parameters
404 Not Found: Order not found
401 Unauthorized: Invalid/missing API key
429 Too Many Requests: Rate limit exceeded
502 Bad Gateway: Upstream service failure

Response Schema (200 OK):

Field	Type	Description
`hotelName`	string	The name of the hotel.
`price`	number	The total price of the reservation.
`roomName`	string	The name of the booked room.
`totalNights`	integer	The total number of nights for the stay.
`checkInDate`	string	The ISO 8601 timestamp for the check-in date.
`checkOutDate`	string	The ISO 8601 timestamp for the check-out date.
`currency`	string	The three-letter ISO currency code for the price.
`customerPhoneNumber`	string	The phone number of the customer making the booking.
`customerEmail`	string	The email address of the customer.
`status`	string	Payment status the booking process. See the `Order Statuses` table for possible values.
`hotelId`	integer	The unique identifier for the hotel.
`bookingStatus`	string	The specific status of the booking. See the `Order Statuses` table for possible values.
`bookingReference`	string	A unique code assigned to a reservation when it is confirmed. Serves as additional tracing information. Corresponds to the Booking Number.
`specialRequest`	string	Any special requests made by the customer. Can be `null`.
`stayInformation`	string	A human-readable summary of the stay duration.
`hotelAddress`	string	The street address of the hotel.
`roomsInformation`	array	An array of objects detailing the occupancy for each booked room.
`roomsInformation[].name`	string	The name of the room type.
`roomsInformation[].foodType`	integer	A code representing the meal plan for the room. See the Boarding Options table for possible values.
`roomsInformation[].adultsCount`	integer	The number of adults staying in the room.
`roomsInformation[].childrenAges`	array	An array of integers representing the ages of children staying in the room.
`cancellationPolicies`	array	An array of objects describing the cancellation policy rules.
`cancellationPolicies[].price`	number	The price amount associated with the cancellation rule.
`cancellationPolicies[].fee`	number	The cancellation fee that applies within the specified date range.
`cancellationPolicies[].dateFrom`	string	The ISO 8601 timestamp for the start of the cancellation policy window.
`cancellationPolicies[].dateTo`	string	The ISO 8601 timestamp for the end of the cancellation policy window.
`cancellationPolicies[].description`	string	A human-readable description of the cancellation policy.
`cancellationPolicies[].refundability`	integer	A code indicating the refundability status. Possible values are `0 = Unknown`, `1 = Refundable`, `2 = Nonrefundable`.
`cancellationPolicies[].sellingPrice`	number	The selling price related to this specific policy rule.

Order Statuses

Booking Status (bookingStatus)	Meaning
WaitingForPayment	The order has been created and is awaiting payment confirmation. The reservation is created and ready for the payment.
Failed	The booking could not be completed. This may occur due to room unavailability, supplier errors, or payment issues. The reservation was not confirmed.
Rebooked	The original booking was modified or replaced with a new reservation. This typically happens when the original room becomes unavailable and an alternative is provided by the CS team.
Cancelled	The booking has been cancelled. This can occur due to customer request.
Completed	The booking has been successfully confirmed with the hotel. The guest has a valid reservation and will receive confirmation details.

Payment Status (status)	Meaning
Processing	Payment is currently being processed. This is the initial state after order creation while awaiting payment confirmation.
Failed	Payment processing failed. The transaction was declined or encountered an error. The booking will not be confirmed.
Successful	Payment has been successfully received and processed. The booking confirmation process will proceed.
Refunded	The payment has been refunded to the customer. This occurs after a successful cancellation or when a booking cannot be fulfilled.
Cancelled	The payment was cancelled before completion. This may occur if the customer abandons the payment or the payment window expires.

Note

Payment Status is not yet available via the API.

Example Response:

{
  "hotelName": "Hôtel Elysées Opéra",
  "price": 258.01,
  "roomName": "Classic Single Room",
  "totalNights": 1,
  "checkInDate": "2025-11-25T00:00:00Z",
  "checkOutDate": "2025-11-26T00:00:00Z",
  "currency": "USD",
  "customerPhoneNumber": "+11234567890",
  "customerEmail": "john.doe@example.com",
  "status": "Processing",
  "hotelId": 1368,
  "bookingStatus": "WaitingForPayment",
  "specialRequest": null,
  "stayInformation": "Tue, 25 Nov - Wed, 26 Nov(1 night)",
  "hotelAddress": "17, Rue de Turin",
  "roomsInformation": [
    {
      "name": "Classic Single Room",
      "foodType": 0,
      "adultsCount": 1,
      "childrenAges": []
    }
  ],
  "cancellationPolicies": [
    {
      "price": 212.38,
      "fee": 212.38,
      "dateFrom": "2025-11-19T23:59:00Z",
      "dateTo": "2025-11-25T00:00:00Z",
      "description": "",
      "refundability": 1,
      "sellingPrice": 212.38
    }
  ]
}

POST /api/order¶

Create a new booking order.

Authentication: Required (X-Api-Key)

Request Headers:

X-Api-Key: <partner-api-key>
Content-Type: application/json

Request Body Schema:

Field	Type	Description
`searchId`	integer	Unique identifier from the original room search. Must be obtained from the `/api/search` endpoint.
`encodedString`	string	An encoded string containing the specific search and rate details for booking. Must be obtained from the `/api/search` endpoint.
`hotelId`	integer	Unique identifier for the hotel being booked.
`packageId`	string	Unique identifier for the specific room and rate package selected (group). Must be obtained from the `/api/search/rooms` endpoint.
`currency`	string	The three-letter ISO currency code for the transaction (default: `USD`).
`customerOrderId`	string	Optional external unique order ID
`guestDetails`	object	An object containing information about the guests.
`guestDetails.primaryGuest`	object	An object with the details of the primary guest for the reservation.
`guestDetails.primaryGuest.firstName`	string	The first name of the primary guest.
`guestDetails.primaryGuest.lastName`	string	The last name of the primary guest.
`guestDetails.primaryGuest.email`	string	The email address of the primary guest.
`guestDetails.primaryGuest.phone`	string	The phone number of the primary guest.
`guestDetails.primaryGuest.phoneCountryCode`	string	The international country calling code for the guest's phone number.
`guestDetails.additionalGuests[]`	array	An array of information about additional guests for multi-room bookings
`guestDetails.additionalGuests[].firstName`	string	The first name of the primary guest for the additional room.
`guestDetails.additionalGuests[].lastName`	string	The last name of the primary guest for the additional room.
`guestDetails.additionalGuests[].specialRequests`	string	Optional special requests for the additional room.

Field Validation and Limits¶

Guest Name Fields:

firstName and lastName: Maximum 50 characters each
Latin characters only — non-English / non-Latin characters (e.g. ć, ę, ü, ø, æ) are not accepted and will be rejected with OCCUPANCY_INVALID_NAME

Contact Information:

email: Maximum 200 characters, must be valid email format
phone and phoneCountryCode: Maximum 50 characters combined

Special Requests:

Maximum 500 characters
No restrictions on character types (emojis and symbols supported)

Example Request:

curl -X POST "<BASE_URL>/api/order" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchId": 113730431,
    "encodedString": "a59Njr5VQXxnUyPQQDvY_an-GhgHfxh6z40Znv5x7z0FP17DQLsAqbUsugb8YUOa76ICezPS4fXMyGTlDFgE0APay9S9DfCPFCIjfWdA5Yagap-o5MbFQ9B_IPmrKI2r0",
    "hotelId": 1368,
    "packageId": ""eyJTZWFyY2giOnsiUHJvcGVydHlJZCI6IjgxNTE5ODQiLCJRdWVyeSI6eyJSZXNpZGVuY3kiOiJJTiIsIk9jY3VwYW5jaWVzIjpbeyJBZHVsdENvdW50IjoyLCJDaGlsZHJlbkFnZXMiOlsyXX1dLCJDaGVja0luQXQiOiIyMDI1LTEyLTMwIiwiQ2hlY2tPdXRBdCI6IjIwMjUtMTItMzEifX0sIlF1b3RlVW5pcXVlSWRlbnRpZmllciI6IjIxNjY1ODYxMzpOb25lOjE3NS42M1VTRDpUcnVlOjpGbGF0LDE3NS42M1VTRCwxMi8yNy8yMDI1IDE2OjAwOjAwLTAxLzAxLzIwMjYgMDA6MDA6MDAifQ==",
    "currency": "USD",
    "guestDetails": {
        "primaryGuest": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "john.doe@example.com",
            "phone": "1234567890",
            "phoneCountryCode": "+1"
        }
    },
    "specialRequests": ""
}'

Example Multi-Room Booking Request:

curl -X POST "<BASE_URL>/api/order" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchId": 113730431,
    "encodedString": "a59Njr5VQXxnUyPQQDvY_an-GhgHfxh6z40Znv5x7z0FP17DQLsAqbUsugb8YUOa76ICezPS4fXMyGTlDFgE0APay9S9DfCPFCIjfWdA5Yagap-o5MbFQ9B_IPmrKI2r0",
    "hotelId": 1368,
    "packageId": ""eyJTZWFyY2giOnsiUHJvcGVydHlJZCI6IjgxNTE5ODQiLCJRdWVyeSI6eyJSZXNpZGVuY3kiOiJJTiIsIk9jY3VwYW5jaWVzIjpbeyJBZHVsdENvdW50IjoyLCJDaGlsZHJlbkFnZXMiOlsyXX1dLCJDaGVja0luQXQiOiIyMDI1LTEyLTMwIiwiQ2hlY2tPdXRBdCI6IjIwMjUtMTItMzEifX0sIlF1b3RlVW5pcXVlSWRlbnRpZmllciI6IjIxNjY1ODYxMzpOb25lOjE3NS42M1VTRDpUcnVlOjpGbGF0LDE3NS42M1VTRCwxMi8yNy8yMDI1IDE2OjAwOjAwLTAxLzAxLzIwMjYgMDA6MDA6MDAifQ==",
    "currency": "USD",
    "guestDetails": {
        "primaryGuest": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "john.doe@example.com",
            "phone": "1234567890",
            "phoneCountryCode": "+1"
        },
        "additionalGuests": [
            {
                "firstName": "John",
                "lastName": "Smith",
                "specialRequests": "Additional soft pillow, if available"
            }
        ]
    },
    "specialRequests": ""
}'

Responses:

200 OK: Order created successfully
400 Bad Request: Invalid request body
404 Not Found: Hotel or room not available
500 Internal Server Error: Upstream processing error
401 Unauthorized: Invalid/missing API key
429 Too Many Requests: Rate limit exceeded
502 Bad Gateway: Upstream service failure

Response Schema (200 OK):

Field	Type	Description
`success`	boolean	Indicates if the request was successfully processed.
`discount`	number	The discount amount applied to the reservation.
`data`	object	An object containing the core details of the reservation.
`data.reservationId`	string	A unique identifier for the created reservation.
`data.status`	string	The current status of the reservation (e.g., `WaitingForPayment`).
`data.priceToPay`	number	The total amount that needs to be paid to confirm the reservation.
`data.createdAt`	string	The ISO 8601 timestamp for when the reservation was created.
`timestamp`	string	The ISO 8601 timestamp for when this response was generated.
`expiresAt`	string	The ISO 8601 timestamp for when the reservation will expire if payment is not completed.

Example Response:

{
  "success": true,
  "discount": 0,
  "data": {
    "reservationId": "056a4aaf-5001-4437-8abf-7879da248b70",
    "status": "WaitingForPayment",
    "priceToPay": 225.12,
    "createdAt": "2025-10-07T08:56:26.4731282Z"
  },
  "timestamp": "2025-10-07T08:56:26.4731282Z",
  "expiresAt": "2025-10-07T09:16:26.4731282Z"
}

Error Response Schema:

Field	Type	Description
`name`	string	The name of the error type (e.g., `ROOM_SOLD_OUT`).
`message`	string	A concise, machine-readable message or code for the specific error.
`details`	object	Additional details about the error. Can be `null`.

Common Error Codes:

Field	Description
`ROOM_SOLD_OUT`	Room package is no longer available
`DUPLICATE_CUSTOMER_ORDER_ID`	Order with given `CustomerOrderId` already exists
`PROPERTY_NOT_FOUND`	Property not found
`OCCUPANCY_MISMATCH`	Missing `additionalGuests` for the multi-room booking request.
`OCCUPANCY_DUPLICATE`	One person was given as primary guest for multiple rooms (in multi-room booking request)
`OCCUPANCY_INVALID_NAME`	One of the guest's name is invalid or missing

Example Error Response:

{
  "name": "ROOM_SOLD_OUT",
  "message": "room package is no longer available",
  "details": null
}

Important Notes¶

Booking Reliability:

Idempotency: Use the customerOrderId field to enable safe retries. If an order with the same customerOrderId already exists, the API returns DUPLICATE_CUSTOMER_ORDER_ID instead of creating a duplicate
Recommendation: Always include a unique customerOrderId with each booking request to prevent duplicate bookings on retries

Reservation Identifiers:

reservationId returned in the response is globally unique across all partners
reservationId is equivalent to orderId used in other endpoints
These identifiers are interchangeable after booking confirmation

Payment Expiration:

Orders must be paid before expiresAt timestamp (typically 15 minutes after creation)
Late payment confirmations (after expiresAt) will be rejected

POST /api/order/update-status¶

Inform Evocative that payment has succeeded on the partner side and update the order status accordingly. If the paid parameter is false, the order will be released earlier than the order timeout.

Authentication: Required (X-Api-Key)

Request Headers:

X-Api-Key: <partner-api-key>
Content-Type: application/json

Request Body Schema:

Field	Type	Description
`orderId`	string	The unique identifier for the order being reserved.
`paid`	boolean	Indicates the payment status for the order (`true` for paid, `false` for payment cancelled).

Example Request:

# To confirm the payment
curl -X POST "<BASE_URL>/api/order/update-status" \
     -H "X-Api-Key: YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "orderId": "11d6b5b2-3e94-4f78-9f33-2c1a5a0df1a1",
       "paid": true
     }'

# To cancel the payment
curl -X POST "<BASE_URL>/api/order/update-status" \
     -H "X-Api-Key: YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "orderId": "11d6b5b2-3e94-4f78-9f33-2c1a5a0df1a1",
       "paid": false
     }'

Responses:

200 OK: Payment status updated successfully
400 Bad Request: Invalid request body or order ID
404 Not Found: Order not found
500 Internal Server Error: Upstream processing error
401 Unauthorized: Invalid/missing API key
429 Too Many Requests: Rate limit exceeded
502 Bad Gateway: Upstream service failure

Error Response Schema:

Based on the JSON structure you provided, here is the MD table response schema:

Field	Type	Description
`name`	string	A unique, human-readable name for the error.
`message`	string	A detailed, user-friendly description of what went wrong.
`details`	string	Optional field for extra technical or contextual information about the error.

Example Error Response:

{
  "name": "PaymentStatusUpdateError",
  "message": "Payment is already cancelled",
  "details": null
}

Data Synchronization¶

Strong Consistency:

The system maintains strong consistency across all endpoints
After calling /api/order/update-status, the new status is immediately visible in /api/order/status
As soon as you receive a successful response from any state-changing request, all subsequent requests will reflect the updated state
Booking records are reflected immediately after creation

Status Consistency:

/api/bookings results are always consistent with /api/order/status
No temporary inconsistencies or delays between endpoints

Order Workflow¶

Create Order: Use POST /api/order to create a new booking
Process Payment: Handle payment on your platform
Update Payment Status: Call POST /api/order/update-status after successful payment
Check Status: Use GET /api/order/status to verify order confirmation