ORDERS
/
Create orders
Last updated

Create your orders

Learn how to use the /orders/preview and /orders/create endpoints to create an order for the selected products

To create an order, you need to use two endpoints:

Endpoint
Use it to...
/orders/previewCheck the details of the order before creating it. This includes:

  • Specific allocation of guests - This significantly reduces the risk of price mismatches.

  • Price breakdown verification.

  • Review of available payment timings, methods and schedules for each product in the order.

  • Obtaining a unique order_token, with encapsulated information needed to create the order. You must pass this token to the /orders/create request instead of having to rebuild the order information again, reducing the risk of data errors.

/orders/createBook the requested products and process payment for the order.

The order creation process

When a traveller has selected the products they wish to book from either your search results or products page, you can create an order for those products.

Step 1 - Call the /orders/preview

Use the /orders/preview endpoint to check that the order details are correct before proceeding with the booking.

The request should be built using the relevant data from the previous responses, such as the product and accommodation details.

If you are implementing:Define your request using:
Search and book flowThe response from the /accommodations/search endpoint .
Search, look and book flowThe response from the /accommodations/availability endpoint.

Defining the request

Define the /orders/preview request with the following fields:

  • booker, currency, accommodation.checkin and accommodation.checkout - Use the values from the previous response.

  • accommodation.id and products - Use the values from the preceding response for the products selected by the traveller.

Guest allocation

If multiple rooms are required, you must specify the exact allocation of guests to each product in the products.allocation field.

For example, the following request shows two instances of the same product, each with one adult allocated to the room:

...
"accommodation": {
  "id": 10507360,
  ...
  "products": [{
      "id": "1050736002_377311511_0_2_0",
      "allocation": {
        "number_of_adults": 1
      }
    },
    {
      "id": "1050736002_377311511_0_2_0",
      "allocation": {
        "number_of_adults": 1
      }
    }
  ]
}
...

The guest allocation data depends on the application flow you are using:

Search and book flow

The response from the /accommodations/search endpoint call returns exact guest allocation for each recommended product, in the products object.

For example, the following response shows a suggestion of two instances of the same product, with one adult guest allocated to each product.

{
  "products": [
    {
      "id": "1050736002_377311511_0_2_0",
      "number_of_adults": 1,
      "room": 1050736002
    },
    {
      "id": "1050736002_377311511_0_2_0",
      "number_of_adults": 1,
      "room": 1050736002
    }
  ]
}
Search, look and book flow

The /accommodations/availability endpoint returns exact guest allocation in the recommendation.products object.

For example:

{
  "recommendation": {
    "products": [
      {
        "id": "1050736003_377312697_1_2_0",
        "number_of_adults": 1,
        "room": 1050736002
      },
      {
        "id": "1050736003_377312697_1_2_0",
        "number_of_adults": 1,
        "room": 1050736002
      }
    ]
  }
}

For non-recommended products, you must validate guest allocation manually.

In the response, the products.maximum_occupancy field will indicate the maximum number of guests allowed for each product.

For more details about occupancy and allocation, refer to the child policies guide

Response from orders/preview

A successful response from the /orders/preview endpoint returns the following information about the order:

  • Accommodation-specific details:

  • Product-specific details:

  • Order token.

    • A secure token containing encapsulated details of the selected order, which must be passed to the /orders/create request.

The order_token is only valid for 15 minutes. After this period, the /orders/create request will fail.

Important considerations

Different products may support different payment timelines and methods.

The payment object contains only timelines and methods that are supported by every selected product in the order.

Step 2 - Display the order preview page

Display the order details on the order preview page so the traveller can:

  • Review their order details.

  • Choose the payment method and timings.

  • Provide any additional details, such as guest information, arrival times, or special requests.

Example:

order-preview

Step 3 - Call the /orders/create endpoint

Once the traveller has confirmed their order, call the /orders/create endpoint, passing the order_token from the orders/preview response nd the traveller's inputs from the order preview page.

Define the request

The /orders/create request requires the following fields:

Field
Description
bookerSpecify the contact details of the person placing the order.
order_tokenCopy the token from the /orders/preview response.

payment

Specify the payment details, including method and timing.

(Refer to Payments section for more details on how to set orders for different use cases and payment methods.)

The order_token is only valid for 15 minutes after it is issued.

Optional fields: You may also include the following optional fields:

  • products - Set the bed configuration and include guest details..

  • remarks - Add any special requests, such as estimated arrival times or specific room preferences..

  • payment.include_receipt - Set to "true" if you wish to generate a receipt for the payment.

Considerations about receipts

Timing
Endpoint
pay_online_nowYou can generate a receipt via orders/create endpoint only when the payment timing is pay_online_now.

pay_online_later

In this timing you can retrieve a credit slip calling the orders/details/accommodations endpoint once the scheduled payment is active.

Example: 3 days prior to arrival depending on the payment policy of the reservation.

Example request

In this request, we have include the optional fields: products details, remarks and receipt generation:

{
  "accommodation": {
    "products": [
      {
        "id": "333",
        "bed_configuration": "123456",
        "guests": [
          {
            "email": "test.name@booking.com",
            "name": "Test Name"
          }
        ]
      }
    ],
    "remarks": {
      "estimated_arrival_time": {
        "hour": 12
      },
      "special_requests": "We will need an extra cot."
    }
  },
  "booker": {
    "address": {
      "address_line": "Road-1, house-2",
      "city": "Amsterdam",
      "country": "nl",
      "post_code": "11111"
    },
    "company": "Booking B.V",
    "email": "test.name@booking.com",
    "language": "en-gb",
    "name": {
      "first_name": "Test",
      "last_name": "Name"
    },
    "telephone": "12345678"
  },
  "order_token": "sample-token",
  "payment": {
    "card": {
      "cardholder": "Test Name",
      "cvc": "111",
      "expiry_date": "2030-10",
      "number": "23333333333333"
    },
    "include_receipt": true,
    "method": "card",
    "timing": "pay_at_the_property"
  }
}

Response from orders/create

A successful response from /orders/create returns the following information about the order:

Field
Description
payment.receipt_urlLink to the payment receipt for the order (if provided)..
authorisation_form_urlIn this example, this field is null as no payment instructions or authorisations have been included.
accommodation.order
  • Unique identifier for the booking, which can be used for cancellations or customer support.
  • Use it if you need order information for post-booking tasks (see /orders/details/*)
accommodation.pincodeThis is a shorter authorisation number that is required to perform certain operations on the order.
accommodation.reservationFor backward compatibility with V2, only used if you need to access legacy orders.

For more information about Reservation ID, see Migration guide.

Example of a response

{
  "request_id": "01j69mtd91x3pdcmqyj0spebt9",
  "data": {
    "payment": {
      "receipt_url": "https://secure.booking.com/payment_receipt.html?product_type=BookingBudget&aid=2373042&auth_key=8riKJJ0XuxDhk4ds&lang=en",
      "authorisation_form_url": null
    },
    "accommodation": {
      "order": "5006302528200239",
      "pincode": "884512",
      "reservation": 55303962
    }
  }
}

Step 4 - Confirm the booking with the traveller.

Use the data from the /orders/create response data to populate populate your order confirmation page and notify the traveller that their booking has been confirmed.

Curious to know more?
Previous page
Next page