Skip to main content

List Bookings

The list endpoint returns bookings that match either a date range (BOOKING_LIST_CRITERIA_TYPE_DATES) or one or more references (BOOKING_LIST_CRITERIA_TYPE_REFERENCES). There is no page cursor in the response: if a range can return many rows, use narrower windows (for example week-by-week) when exporting.

Endpoint​

POST /connect/hotels/v1/bookinglist

Request​

Request body parameters​

ParameterTypeDescription
criteriaobjectFilter criteria (see below)
settings.connectionCodesarrayProvider connection codes (required)

Criteria modes​

criteria.typeSearchWhen to useRequired fields
BOOKING_LIST_CRITERIA_TYPE_DATESReconciliation, reporting by stay or booking datecriteria.dates
BOOKING_LIST_CRITERIA_TYPE_REFERENCESLookup by Bundleport id, your clientReference, or supplier refscriteria.references (array)

Date range (TYPE_DATES)​

dates.dateType is one of:

  • BOOKING_LIST_CRITERIA_DATE_TYPE_ARRIVAL — filter by check-in / arrival window
  • BOOKING_LIST_CRITERIA_DATE_TYPE_BOOKING — filter by when the booking was created

References (TYPE_REFERENCES)​

Each element of criteria.references can include any of:

  • bookingID — Bundleport booking id
  • clientReference — the value you sent on book (ideal after a timeout; see Create a booking)
  • providerReference / confirmationReference — when you store supplier refs

Example: date range (by arrival)​

{
  "criteria": {
    "typeSearch": "BOOKING_LIST_CRITERIA_TYPE_DATES",
    "dates": {
      "dateType": "BOOKING_LIST_CRITERIA_DATE_TYPE_ARRIVAL",
      "start": "2025-06-01T00:00:00Z",
      "end": "2025-06-30T00:00:00Z"
    }
  },
  "settings": {
    "connectionCodes": ["testb-hbds-1876"]
  }
}

Example: by booking id​

{
  "criteria": {
    "typeSearch": "BOOKING_LIST_CRITERIA_TYPE_REFERENCES",
    "references": [
      { "bookingID": "BK-987654321" }
    ]
  },
  "settings": {
    "connectionCodes": ["testb-hbds-1876"]
  }
}

Example: by client reference​

{
  "criteria": {
    "typeSearch": "BOOKING_LIST_CRITERIA_TYPE_REFERENCES",
    "references": [
      { "clientReference": "BOOKING-2025-001" }
    ]
  },
  "settings": {
    "connectionCodes": ["testb-hbds-1876"]
  }
}

Response​

Success response​

The API returns a bookings array (and optional errors / warnings). Shape below is illustrative; see the API reference for the full booking summary fields.

{
  "bookings": [
    {
      "bookingID": "BK-987654321",
      "status": "CONFIRMED",
      "reference": {
        "bookingID": "BK-987654321",
        "clientReference": "BOOKING-2025-001"
      },
      "hotel": {
        "code": "12345",
        "name": "Example Hotel Barcelona"
      },
      "stay": {
        "checkIn": "2025-06-15",
        "checkOut": "2025-06-17"
      },
      "price": {
        "currency": "EUR",
        "net": 150.00
      },
      "createdAt": "2025-06-01T10:30:00Z"
    }
  ]
}

Use Cases​

List is your operational workhorse: finance reconciliation, support lookups, and exports should go through dates or references criteria—not through ad-hoc caches of search results.

1. Reconciliation​

const bookings = await listBookings({
  criteria: {
    typeSearch: 'BOOKING_LIST_CRITERIA_TYPE_DATES',
    dates: {
      dateType: 'BOOKING_LIST_CRITERIA_DATE_TYPE_ARRIVAL',
      start: '2025-06-01T00:00:00Z',
      end: '2025-06-30T00:00:00Z',
    },
  },
  settings: {
    connectionCodes: ['testb-hbds-1876'],
  },
});

bookings.bookings.forEach(booking => {
  reconcileBooking(booking);
});

2. Customer Service​

// Find booking by Bundleport booking id (or use clientReference in references[0] instead)
const bookings = await listBookings({
  criteria: {
    typeSearch: 'BOOKING_LIST_CRITERIA_TYPE_REFERENCES',
    references: [{ bookingID: customerProvidedBookingId }],
  },
  settings: {
    connectionCodes: ['testb-hbds-1876'],
  },
});

if (bookings.bookings.length > 0) {
  const booking = bookings.bookings[0];
  // Display booking details to customer service agent
  displayBookingDetails(booking);
}

3. Reporting​

There is no page field: chunk the date range (for example one month per request) if responses grow large.

const allBookings = [];

for (const { start, end } of monthlyChunks(overallStart, overallEnd)) {
  const result = await listBookings({
    criteria: {
      typeSearch: 'BOOKING_LIST_CRITERIA_TYPE_DATES',
      dates: {
        dateType: 'BOOKING_LIST_CRITERIA_DATE_TYPE_ARRIVAL',
        start,
        end,
      },
    },
    settings: {
      connectionCodes: ['testb-hbds-1876'],
    },
  });
  allBookings.push(...result.bookings);
}

generateReport(allBookings);

Code Examples​

The cURL sample uses arrival date range. For a single booking or your own clientReference, switch to BOOKING_LIST_CRITERIA_TYPE_REFERENCES and a references array as in the examples above.

curl -X POST https://api.bundleport.com/connect/hotels/v1/bookinglist \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "criteria": {
      "typeSearch": "BOOKING_LIST_CRITERIA_TYPE_DATES",
      "dates": {
        "dateType": "BOOKING_LIST_CRITERIA_DATE_TYPE_ARRIVAL",
        "start": "2025-06-01T00:00:00Z",
        "end": "2025-06-30T00:00:00Z"
      }
    },
    "settings": {
      "connectionCodes": ["testb-hbds-1876"]
    }
  }'

Next Steps​