Skip to content
Last updated

Retrieve and display bundles and value adds

Use this guide to retrieve bundle details, match them to accommodation products, and display the associated value adds throughout the booking flow. A product can include a bundle ID. To display the benefits associated with that bundle, retrieve the accommodation’s bundle details and match the ID to the product.


How the API returns bundle information

Bundles appear consistently across the booking flow:

Booking stageResponse dataHow to use it
Searchdata[].products[].bundle when extras includes productsUse the bundle ID to identify the bundle associated with the returned product.
Availabilitydata[].products[].bundleUse the current product and bundle ID when presenting available options.
Accommodation detailsdata[].bundles[], including each bundle ID and its value_addsMatch the bundle ID to the product’s bundle field to retrieve the benefit descriptions.
Order previewdata.accommodation.products[].bundleConfirm which bundle is associated with the selected product before creating the order.
Post-booking detailsThe product’s bundle object, when applicableDisplay the value adds returned for the confirmed reservation.

In Demand API v3.2 and v3.3, do not send the legacy v3.1 include_bundle_variants parameter.

  • For Search, request product information with extras: ["products"].
  • For bundle descriptions, request extras: ["bundles"] from /accommodations/details.

Store bundle details from /accommodations/details and reuse them across all stages of the booking flow.

Version behaviour

In order to retrieve the full list of bookable products with bundles:

  • Demand API v3.1 - You must explicitly request bundled products in availability using extras.include_bundle_variants.
  • Demand API v3.2 and v3.3 - Bundled products are returned automatically. No extras are required.

1. Search for accommodation

→ Call the accommodations/search endpoint with the traveller’s search details.

Include products in extras to retrieve product-level information, including the bundle ID.

Example request:

{
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2027-02-02",
  "checkout": "2027-02-10",
  "country": "es",
  "extras": [
    "products"
  ],
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}

This simplified response excerpt shows a product with a bundle ID:

Example response:


{
  "request_id": "0123456789abcdef0123456789abcdef",
  "data": [
    {
      "id": 13766008,
      "currency": {
        "accommodation": "EUR",
        "booker": "EUR"
      },
      "products": [
        {
          "id": "1376600801_409788848_0_0_0_843543",
          "bundle": 843543
        }
      ]
    }
  ]
}

The bundle value identifies the bundle associated with that product. It can be null when no bundle applies.

2. Retrieve current availability

→ Call /accommodations/availability for the accommodation to refresh availability and pricing before the traveller selects a product.

Example request:

{
  "accommodations": [13766008],
  "booker": {
    "country": "nl",
    "platform": "desktop"
  },
  "checkin": "2027-02-02",
  "checkout": "2027-02-10",
  "guests": {
    "number_of_adults": 2,
    "number_of_rooms": 1
  }
}

The response uses a data array. Each product can include a bundle ID:

Example response:

{
  "request_id": "0123456789abcdef0123456789abcdef",
  "data": [
    {
      "id": 13766008,
      "currency": {
        "accommodation": "EUR",
        "booker": "EUR"
      },
      "products": [
        {
          "id": "1376600801_409788848_0_0_0_843543",
          "bundle": 843543,
          "number_available": 1,
          "price": {
            "display": {
              "accommodation_currency": 740.00,
              "booker_currency": 740.00
            },
            "total": {
              "accommodation_currency": 740.00,
              "booker_currency": 740.00
            }
          }
        }
      ]
    }
  ]
}

This is a simplified response excerpt. Use the returned product price and policies; do not infer them from the bundle ID.

Prices may change between search and availability. Always confirm before booking.


3. Retrieve bundle details

→ Call /accommodations/details with extras: ["bundles"] and the languages you want returned.

Example request:

{
  "accommodations": [
    13766008
  ],
  "extras": [
    "bundles"
  ],
  "languages": [
    "en-gb",
    "es"
  ]
}

Example response:

The response can include the bundles available for the accommodation and their value adds:

{
  "request_id": "0123456789abcdef0123456789abcdef",
  "data": [
    {
      "id": 13766008,
      "bundles": [
        {
          "id": 843543,
          "value_adds": [
            {
              "type": "parking",
              "description": {
                "en-gb": [
                  "Self parking for one vehicle per booked unit per stay."
                ],
                "es": [
                  "Parking para un vehículo por unidad reservada y estancia."
                ]
              }
            },
            {
              "type": "high_speed_internet",
              "description": {
                "en-gb": [
                  "High-speed internet throughout your stay."
                ],
                "es": [
                  "Internet de alta velocidad durante toda la estancia."
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

A property might not return any bundles. Requesting extras: ["bundles"] does not guarantee that bundle data will be present.

You can store bundle details as accommodation content, but refresh them according to your content-update strategy. Do not treat cached details as valid indefinitely.

4. Match bundle details to the selected product

For each product:

  1. Read its bundle value.
  2. If the value is null, do not display bundle benefits for that product.
  3. Find the bundle with the same id in the bundles array for the same accommodation.
  4. Display the value adds from that matching bundle.

Do not show every bundle returned for an accommodation as though it applies to every product. A product can have at most one bundle.

Use the localised description returned by the API. The type identifies the kind of value add; it does not provide a separate amount or currency. Do not invent or calculate a benefit’s value. Preserve amounts, currency, frequency, and scope as stated in the returned description.

5. Confirm the selected product with order preview

If you are implementing a Search, look and book flow call /orders/preview before creating an order.

  • Use the selected product ID and allocation in your request.

Example request

{
  "currency": "EUR",
  "accommodation": {
    "id": 13766008,
    "booker": {
      "country": "nl",
      "platform": "desktop"
    },
    "checkin": "2027-02-02",
    "checkout": "2027-02-10",
    "products": [
      {
        "id": "1376600801_409788848_0_0_0_843543",
        "allocation": {
          "number_of_adults": 2,
          "children": []
        }
      }
    ]
  }
}

The preview response validates the selected product.

When a bundle applies, its ID is included in the selected product’s bundle field.

Example response with bundle ID

{
  "request_id": "0123456789abcdef0123456789abcdef",
  "data": {
    "accommodation": {
      "id": 13766008,
      "products": [
        {
          "id": "1376600801_409788848_0_0_0_843543",
          "bundle": 843543
        }
      ]
    },
    "order_token": "..."
  }
}

This is a simplified response excerpt.

Display the preview price and policies returned by the API. If the traveller changes the selected product or allocation, request a new preview.

6. Create the order

After the traveller confirms the preview, call /orders/create using the returned order_token and the fields required by the order creation flow.

Do not send a separate bundle selection. The selected product ID in the preview determines the product and its associated bundle.

Orders guides

See the Orders creation guide for the complete order flow.

7. Retrieve confirmed bundle details after booking

After the order is created, call /orders/details/accommodations to retrieve the reservation details.

When a bundle applies, the product’s bundle field is an object that can include the bundle ID and value adds.

{
  "data": [
    {
      "products": [
        {
          "id": "1376600801_409788848_0_0_0_843543",
          "bundle": {
            "id": 843543,
            "value_adds": [
              {
                "type": "parking",
                "description": [
                  "Self parking for one vehicle per booked unit per stay."
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

Use the bundle information returned for the reservation when displaying confirmed benefits in an itinerary or post-booking experience. A product without a bundle does not have bundle value adds to display.


Best practices

✅ Match a product’s bundle ID only with bundle details for the same accommodation.
✅ Display only the value adds associated with the selected product.
✅ Present value adds as included benefits, not selectable extras or upsells.
✅ Use the returned price and policies; do not infer them from the bundle.
✅ Preserve the returned description, currency, amount, frequency, and scope.
✅ Handle products and accommodations with no bundle.
✅ Refresh availability before order preview because availability and prices can change.


Next steps

Not familiar with bundles and value adds? Start with Bundles and value adds overview to understand the concepts.