Skip to content

Bookings API

The Bookings API provides endpoints for managing existing bookings, including cancellation operations.

Endpoints

GET /api/bookings/{orderId}

Get a booking by ID.

Authentication: Required (X-Api-Key)

Path Parameters:

Parameter Type Required Description
orderId string Yes Booking identifier. Accepts either the Evocative order ID (GUID) or your own customerOrderId. See the note below.

Look up by your order ID or your own customerOrderId

The {orderId} path segment accepts either the Evocative order ID (the booking.id / reservationId returned at the book step) or the customerOrderId you supplied when booking. It also resolves referenceNumber and supplierReferenceNumber. The first booking matching the value on your partner account is returned, so use a unique customerOrderId per booking to guarantee a single result. See the Identifier Reference for how these values map to the Evocative Ops portal.

Example Request

# By Entravel order ID
curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/bookings/f06c23b3-666f-4246-a11f-d37d828422fc"

# By your own customerOrderId
curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/bookings/acme_7d6344ba02eeddf11743"

Responses:

  • 200 OK: JSON search results
  • 401 Unauthorized: Invalid/missing API key
  • 404 Not Found: Booking does not exist
  • 429 Too Many Requests: Rate limit exceeded
  • 502 Bad Gateway: Upstream service failure

Response Schema (200 OK)

Field Type Description
id string Unique identifier for the booking (UUID format).
status string Current status of the booking. See the Order Statuses table for possible values.
salePrice number Total sale price of the booking.
currency string Currency code (ISO 4217). Example: USD
hotel object Hotel information object.
hotel.id integer DEPRECATED, use evocativeId instead. This value will be removed in future API updates
hotel.evocativeId string Unique property identifier
hotel.name string Name of the hotel. Example:
hotel.address string Street address of the hotel.
hotel.city string City where the hotel is located. Example: Dubai
hotel.country string Country code (ISO-3166-1 alpha-2). Example: AE
hotel.phoneNumber string Contact phone number for the hotel.
hotel.email string Contact email address for the hotel.
customer object
customer.firstName string
customer.lastName string
customer.email string
customer.phoneNumber string
customer.residency string Residency country code (ISO-3166-1 alpha-2). Example: FR
customer.externalUserId string A user ID assigned to them during the JWE flow. Corresponds to the user_id parameter encoded in the JWE.
boardType string Board/meal plan. See Board Types table
rooms array
rooms[].primaryGuest object
rooms[].primaryGuest.firstName string
rooms[].primaryGuest.lastName string
rooms[].occupancy object
rooms[].occupancy.adultCount integer
rooms[].occupancy.childrenAges array
rooms[].specialRequest string
rooms[].hotelConfirmationNumber string Reference number from the hotel, may be null if not available or pending confirmation.
cancellationPolicies array Array of cancellation policy objects. A booking is fully refundable until the free-cancellation cut-off and non-refundable afterwards — there are no partial refunds.
cancellationPolicies[].fee number Cancellation fee charged in this window, in the order-level currency (0 means free cancellation). Example: 2283.26
cancellationPolicies[].availableFrom string Start date-time when this cancellation policy becomes effective (ISO 8601 format). Example: 2025-10-10T00:01:00Z
cancellationPolicies[].availableTo string End date-time when this cancellation policy is effective (ISO 8601 format). Example: 2025-10-10T00:01:00Z
cancellationPolicies[].description string Detailed description of the cancellation policy (HTML format).
cancellationPolicies[].refundability string Refundability status. Possible values are Unknown, Refundable, Nonrefundable.
taxesAndFees array Array of tax and fee objects.
taxesAndFees[].currency string Currency code for the tax/fee (ISO 4217). Example: EUR
taxesAndFees[].title string Title/name of the tax or fee. Example: Taxes and Fees
taxesAndFees[].isIncludedInPrice boolean Whether the tax/fee is included in the sale price.
taxesAndFees[].isMandatory boolean Whether the tax/fee is mandatory.
taxesAndFees[].isValuePercentage boolean Whether the value is a percentage.
taxesAndFees[].value number Amount of the tax or fee.
createdAt string Date-time when the booking was created (ISO 8601 format). Example: 2025-10-10T11:37:43.931358Z
checkInAt string Check-in date-time (ISO 8601 format). Example: 2025-10-10T00:00:00Z
checkOutAt string Check-out date-time (ISO 8601 format). Example: 2025-10-11T00:00:00Z
bookingRemarks string Additional remarks attached to the booking (e.g. supplier notes). Can be null.

Read the currency field — do not assume USD

Monetary amounts are currently returned in USD, but every response carries an explicit currency field and your integration must use it rather than hard-coding USD. currency is set at the order level (top-level currency). Nested objects that omit their own currency (such as each entry in cancellationPolicies) inherit the order-level currency; taxesAndFees entries carry their own currency and may differ. See Currency for the general rule.

Example Response

{
    "id": "a672081b-0148-4e19-bed2-ea480a33fdf5",
    "status": "Completed",
    "salePrice": 714.8,
    "currency": "USD",
    "hotel": {
        "id": 15838,
        "evocativeId": "R:226291",
        "name": "New York Marriott Marquis",
        "address": "1535 Broadway",
        "city": "New York",
        "country": "US",
        "phoneNumber": "1-212-398-1900",
        "email": null
    },
    "boardType": "None",
    "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "sink@example.com",
        "residency": "PT",
        "phoneCountryCode": "+351",
        "phoneNumber": "99999999"
    },
    "rooms": [
        {
            "name": "Deluxe Room, 1 King Bed",
            "primaryGuest": {
                "firstName": "John",
                "lastName": "Doe"
            },
            "occupancy": {
                "adultCount": 2,
                "childrenAges": []
            },
            "specialRequest": null,
            "hotelConfirmationNumber": null
        }
    ],
    "cancellationPolicies": [
        {
            "fee": 0,
            "availableFrom": "2026-07-20T00:00:00Z",
            "availableTo": "2026-09-07T03:59:00Z",
            "description": "Free cancellation",
            "refundability": "Refundable"
        },
        {
            "fee": 714.8,
            "availableFrom": "2026-09-07T03:59:00Z",
            "availableTo": "2026-09-12T00:00:00Z",
            "description": "Non-refundable",
            "refundability": "Refundable"
        }
    ],
    "taxesAndFees": [
        {
            "currency": "USD",
            "title": "Mandatory Fee",
            "isIncludedInPrice": false,
            "isMandatory": true,
            "isValuePercentage": false,
            "value": 45
        },
        {
            "currency": "USD",
            "title": "Mandatory Tax",
            "isIncludedInPrice": false,
            "isMandatory": true,
            "isValuePercentage": false,
            "value": 6.64
        },
        {
            "currency": "USD",
            "title": "Property Fee",
            "isIncludedInPrice": true,
            "isMandatory": true,
            "isValuePercentage": false,
            "value": 14.79
        },
        {
            "currency": "USD",
            "title": "Taxes and Fees",
            "isIncludedInPrice": true,
            "isMandatory": true,
            "isValuePercentage": false,
            "value": 96.42
        }
    ],
    "createdAt": "2026-07-21T15:03:11.009872Z",
    "checkInAt": "2026-09-10T00:00:00Z",
    "checkOutAt": "2026-09-11T00:00:00Z",
    "bookingRemarks": null
}

GET /api/bookings

Get existing bookings.

Authentication: Required (X-Api-Key)

Query Parameters:

These are optional query parameters.

Parameter Type Description
createdAt.from string Start date-time for filtering bookings by creation date (ISO 8601 format). Example: 2025-01-01T00:00:00Z
createdAt.to string End date-time for filtering bookings by creation date (ISO 8601 format). Example: 2025-12-31T23:59:59Z
checkInAt.from string Start date-time for filtering bookings by check-in date (ISO 8601 format). Example: 2025-06-01T15:00:00Z
checkInAt.to string End date-time for filtering bookings by check-in date (ISO 8601 format). Example: 2025-06-30T15:00:00Z
checkOutAt.from string Start date-time for filtering bookings by check-out date (ISO 8601 format). Example: 2025-06-05T11:00:00Z
checkOutAt.to string End date-time for filtering bookings by check-out date (ISO 8601 format). Example: 2025-07-05T11:00:00Z
page.limit integer Maximum number of results to return per page. Example: 50
page.offset integer Number of results to skip for pagination. Example: 0 for the first page, 50 for the second page

Example Request:

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/bookings"

curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/bookings?page.limit=50&page.offset=50"

Responses:

  • 200 OK: JSON search results
  • 400 Bad Request: Invalid query parameters
  • 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
total integer Total number of bookings matching the query.
data array Array of booking objects.
data[].id string Unique identifier for the booking (UUID format).
data[].status string Current status of the booking. See the Order Statuses table for possible values.
data[].salePrice number Total sale price of the booking.
data[].currency string Currency code (ISO 4217). Example: USD
data[].hotel object Hotel information object.
data[].hotel.id integer DEPRECATED, use evocativeId instead. This value will be removed in future API updates
data[].hotel.evocativeId string Unique property identifier
data[].hotel.name string Name of the hotel. Example:
data[].hotel.address string Street address of the hotel.
data[].hotel.city string City where the hotel is located. Example: Dubai
data[].hotel.country string Country code (ISO-3166-1 alpha-2). Example: AE
data[].hotel.phoneNumber string Contact phone number for the hotel.
data[].hotel.email string Contact email address for the hotel.
data[].customer object
data[].customer.firstName string
data[].customer.lastName string
data[].customer.email string
data[].customer.phoneNumber string
data[].customer.residency string Residency country code (ISO-3166-1 alpha-2). Example: FR
customer.externalUserId string A user ID assigned to them during the JWE flow. Corresponds to the user_id parameter encoded in the JWE.
data[].boardType string Board/meal plan. See Board Types table
data[].rooms array
data[].rooms[].primaryGuest object
data[].rooms[].primaryGuest.firstName string
data[].rooms[].primaryGuest.lastName string
data[].rooms[].occupancy object
data[].rooms[].occupancy.adultCount integer
data[].rooms[].occupancy.childrenAges array
data[].rooms[].specialRequest string
data[].rooms[].hotelConfirmationNumber string Reference number from the hotel, may be null if not available or pending confirmation.
data[].cancellationPolicies array Array of cancellation policy objects.
data[].cancellationPolicies[].fee number Cancellation fee amount. Example: 2283.26
data[].cancellationPolicies[].availableFrom string Start date-time when this cancellation policy becomes effective (ISO 8601 format). Example: 2025-10-10T00:01:00Z
data[].cancellationPolicies[].availableTo string End date-time when this cancellation policy is effective (ISO 8601 format). Example: 2025-10-10T00:01:00Z
data[].cancellationPolicies[].description string Detailed description of the cancellation policy (HTML format).
data[].cancellationPolicies[].refundability string Refundability status. Possible values are Unknown, Refundable, Nonrefundable.
data[].taxesAndFees array Array of tax and fee objects.
data[].taxesAndFees[].currency string Currency code for the tax/fee (ISO 4217). Example: EUR
data[].taxesAndFees[].title string Title/name of the tax or fee. Example: Taxes and Fees
data[].taxesAndFees[].isIncludedInPrice boolean Whether the tax/fee is included in the sale price.
data[].taxesAndFees[].isMandatory boolean Whether the tax/fee is mandatory.
data[].taxesAndFees[].isValuePercentage boolean Whether the value is a percentage.
data[].taxesAndFees[].value number Amount of the tax or fee.
data[].createdAt string Date-time when the booking was created (ISO 8601 format). Example: 2025-10-10T11:37:43.931358Z
data[].checkInAt string Check-in date-time (ISO 8601 format). Example: 2025-10-10T00:00:00Z
data[].checkOutAt string Check-out date-time (ISO 8601 format). Example: 2025-10-11T00:00:00Z
data[].bookingRemarks string Additional remarks attached to the booking (e.g. supplier notes). Can be null.
limit integer Maximum number of results returned per page. Example: 1
offset integer Number of results skipped for pagination. Example: 3

Example Response

{
  "total": 11,
  "data": [
    {
      "id": "f06c23b3-666f-4246-a11f-d37d828422fc",
      "status": "Completed",
      "salePrice": 2515.24,
      "currency": "USD",
      "hotel": {
        "id": 108504312,
        "evocativeId": "R:213405813",
        "name": "Modern and Cozy Studio at Seven Palm",
        "address": "Seven Palm",
        "city": "Dubai",
        "country": "AE",
        "phoneNumber": "+9",
        "email": ""
      },
      "cancellationPolicies": [
        {
          "fee": 2283.26,
          "availableFrom": "2025-10-10T00:01:00Z",
          "availableTo": "2025-10-10T00:01:00Z",
          "description": "<h4>Check in</h4><p>3:00 PM-anytime</p><h4>Check out</h4><p>11:00 AM</p><h4>Instructions</h4><ul>  <li>Extra-person charges may apply and vary depending on property policy</li><li>Government-issued photo identification and a credit card, debit card, or cash deposit may be required at check-in for incidental charges</li><li>Special requests are subject to availability upon check-in and may incur additional charges; special requests cannot be guaranteed</li><li>This property accepts credit cards, debit cards, and cash</li><li>Host has not indicated whether there is a carbon monoxide detector on the property; consider bringing a portable detector with you on the trip</li><li>Host has not indicated whether there is a smoke detector on the property</li>  </ul><h4>Special instructions</h4><p>There is no front desk at this property. To make arrangements for check-in please contact the property at least 24 hours before arrival using the information on the booking confirmation. Guests must contact the property in advance for check-in instructions. The host will greet guests on arrival.</p><h4>Fees</h4><p>You'll be asked to pay the following charges at the property. Fees may include applicable taxes:</p> <ul><li>Deposit: AED 1000 per accommodation, per stay</li><li>A tax is imposed by the city: AED 10.00 per accommodation, per night</li></ul> <p>We have included all charges provided to us by the property. </p>",
          "refundability": "Nonrefundable"
        }
      ],
      "taxesAndFees": [
        {
          "currency": "EUR",
          "title": "Taxes and Fees",
          "isIncludedInPrice": true,
          "isMandatory": false,
          "isValuePercentage": false,
          "value": 264.62
        },
        {
          "currency": "EUR",
          "title": "Mandatory Tax",
          "isIncludedInPrice": false,
          "isMandatory": false,
          "isValuePercentage": false,
          "value": 2.72
        }
      ],
      "createdAt": "2025-10-10T11:37:43.931358Z",
      "checkInAt": "2025-10-10T00:00:00Z",
      "checkOutAt": "2025-10-11T00:00:00Z"
    }
  ],
  "limit": 1,
  "offset": 3
}

POST /api/bookings/{orderId}/cancel

Cancel an existing booking.

One request cancels the whole reservation

Cancellation is performed per booking order using the orderId. A single request cancels the entire reservation — there is no need to cancel each room independently.

No cancellation on the check-in date

Booking cancellation is not supported on the check-in date.

Authentication: Required (X-Api-Key)

Path Parameters:

Parameter Type Required Description
orderId string (GUID) Yes Unique identifier for the order to cancel

Request Headers:

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

Example Request:

curl -X POST "<BASE_URL>/api/bookings/11d6b5b2-3e94-4f78-9f33-2c1a5a0df1a1/cancel" \
     -H "X-Api-Key: YOUR_KEY"

Responses:

  • 200 OK: Cancellation processed successfully
  • 400 Bad Request: Invalid order ID or cancellation not allowed
  • 404 Not Found: User or 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
isSuccessful boolean Whether the cancellation was successful
success boolean Alias of isSuccessful; both carry the same value
errorCode integer Error code (null on success)
error string Error message (null on success)

No refund amount is returned

The cancellation response confirms the outcome only — it does not include any refund amount, cancellation fee, or currency. Bookings are either fully refundable or non-refundable (there are no partial refunds), so a successful cancellation within the free-cancellation window returns the full amount as credit to your account. Credits against your credit line are reflected in the Liabilities API; the fee that would apply per window is visible on the booking's cancellationPolicies (see GET /api/bookings/{orderId}).

Success Response Example:

{
  "isSuccessful": true,
  "success": true,
  "errorCode": null,
  "error": null
}

Error Response Schema:

Field Type Description
isSuccessful boolean Always false for errors
errorCode integer Error code identifier
error string Human-readable error message

Error Response Example:

{
  "isSuccessful": false,
  "errorCode": 27,
  "error": "UPDATE_STATUS_ERROR"
}

Cancellation Workflow

  1. Check cancellation policy: Review the booking's cancellationPolicies (fee per window) before attempting cancellation
  2. Submit cancellation: Call POST /api/bookings/{orderId}/cancel and confirm isSuccessful / success is true
  3. Reconcile the credit: The response returns no refund amount. A refundable cancellation credits the full amount to your credit line — reconcile it via the Liabilities API
  4. Verify status: Use GET /api/order/status to confirm cancellation

Common Use Cases

Cancel a Booking

curl -X POST "<BASE_URL>/api/bookings/11d6b5b2-3e94-4f78-9f33-2c1a5a0df1a1/cancel" \
     -H "X-Api-Key: YOUR_KEY"

Cancel and Verify

# Step 1: Cancel the booking
CANCEL_RESPONSE=$(curl -X POST "<BASE_URL>/api/bookings/${ORDER_ID}/cancel" \
     -H "X-Api-Key: YOUR_KEY"

# Step 2: Verify cancellation status
curl -H "X-Api-Key: YOUR_KEY" \
     "<BASE_URL>/api/order/status?orderId=${ORDER_ID}"

Important Notes

Cancellation Policies

  • Cancellation availability depends on the hotel's cancellation policy
  • Cancellation policies are passed through from the supplier unchanged (never worsened)
  • A booking is either fully refundable or non-refundable — there are no partial refunds
  • A refundable booking is fully refundable until its free-cancellation cut-off and non-refundable afterwards; the fee per window is on cancellationPolicies
  • Cancellation is not available on the check-in date
  • Always check the booking terms before attempting cancellation

Amendments

  • Reservation amendments are not available via the API. No reservation parameters can be modified after booking.
  • To change a reservation, cancel it (subject to its cancellation policy) and create a new booking.

Refunds

  • No refund amount in the response: The cancel response confirms the outcome only (isSuccessful / success). It does not return a refund amount, cancellation fee, or currency.
  • Full-or-nothing: Because bookings are fully refundable or non-refundable, a successful cancellation within the free-cancellation window returns the full amount as credit — there are no partial refunds.
  • Where the credit appears: Evocative operates a Credit Line payment model. Refunds are applied as credit to your account; utilization and liability records are available through the Liabilities API.
  • Currency: There is no separate refund currency to read — the booking's amounts follow its order-level currency (currently USD; always read the field rather than assuming USD).

Error Handling

Error Finality: - Cancellation errors are final (not retriable) - If you receive an error, do not automatically retry - Verify booking status and cancellation policy before attempting again

Common cancellation errors:

Error Code Description Action
2 SIGNUP_OR_SIGNIN Verify the API token is valid and present in the request.
4 SOMETHING_WRONG Internal server error, verify the booking status before any action.
27 UPDATE_OFFER_STATUS_ERROR Unable to cancel the booking due to policy constraints. Final error.

Customer Service and Support

Partner CS Portal

  • Current status: A partner/customer-service portal is not currently available
  • Planned feature: Portal for viewing, searching, and managing API bookings (including cancellations and modifications)
  • The portal will allow your support team to handle booking issues and manual interventions

Support Communication

For booking issues or manual interventions:

  • Slack channel: A dedicated Slack channel will be set up for partner support
  • Include in requests:
  • X-Correlation-Id from the response
  • Timestamp (UTC)
  • Full request path and HTTP method
  • Reservation ID or Order ID
  • Sample request/response (redact sensitive data)

Best Practices

  1. Validate before cancellation: Check the order status and cancellation policy before submitting
  2. Handle errors gracefully: Provide clear error messages to users
  3. Log correlation IDs: Always include X-Correlation-Id for troubleshooting
  4. Confirm with the user: Get explicit confirmation before canceling bookings
  5. Process refunds promptly: Handle refunds according to your SLA