# Migration guide: Get all reservations
This guide is intended to assist API users to migrate away from the obsolete API Operation [Get all reservations (ver 2017-04-12)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2017-04-12) which is long deprecated and will be permanently discontinued.
> #### Help us improve the migration experience
>
> We’re committed to ensuring a smooth transition from the old 2017 version of 'Get all reservations' to the newer 2023 version. To better support you, we’d love to hear about your migration plans and any potential blockers you may be facing.
>
> * **Migration timeline** – When do you plan to complete your migration?
> * **Feature parity** – Is there any missing functionality preventing your transition?
>
> After consulting the details in this Migration Guide, please take a moment to fill out this [short survey](https://mews.typeform.com/to/izhRLSFg) and share your feedback. If you need further assistance or would like to discuss your migration plans, please [contact support](https://docs.mews.com/connector-api/contact-support).
## Contents
* [Get all reservations (ver 2023-06-06)](#get-all-reservations-ver-2023-06-06)
* [Migration steps](#migration-steps)
* [Request parameters](#request-parameters)
* [Time filters](#time-filters)
* [Extents removal](#extents-removal)
* [Response properties](#response-properties)
* [Known issues](#known-issues)
## Get all reservations (ver 2023-06-06)
API Operation [Get all reservations (ver 2017-04-12)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2017-04-12) is replaced by [Get all reservations (ver 2023-06-06)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06). The original operation became increasingly complex and the combination of extents along with backward compatibility requirements resulted in unpredictable performance and frequent timeouts. The new operation performs the same basic function to fetch reservations from Mews, however there are substantial differences that you need to be aware of. The major differences are as follows:
* The new operation doesn't support extents
* The new operation requires [pagination](https://docs.mews.com/connector-api/guidelines/pagination)
* The new operation supports filtering by more time intervals
* The new operation supports [Portfolio Access Tokens](https://docs.mews.com/connector-api/concepts/multi-property)
### What do these changes mean for you?
* If you previously used extents, you will need to change your implementation to make additional calls to the API to get the same information.
* You will need to change your implementation to support pagination, including supplying the mandatory Limitation parameter in your request.
* Filtering by time intervals offers new opportunities to make your calls more efficient.
* Portfolio Access Tokens again offers new opportunities to users taking advantage of the Mews Multi-Property feature.
> **Extents**: Extents are a way to fetch related entities with a single API request. For example, when fetching reservations in the original Get all reservations operation, you were able to receive data about related customers and resources in the same resources. While this simplified some use cases, it frequently resulted in request timeouts and overfetching of rarely updated data. Furthermore, contract changes in related entities complicated tracking changes to the operation. See also [Best practices](https://docs.mews.com/connector-api/guidelines/best-practices).
## Migration steps
1. Check the usage of request parameters and map the original request parameters to their new equivalents.
2. Replace extents in request parameters (if used) with calls to additional operations.
3. Map original response parameters to their new equivalents.
4. Ensure your implementation supports pagination.
## Request parameters
The following table maps request parameters from [Get all reservations (ver 2017-04-12)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2017-04-12) to the equivalent request parameters in [Get all reservations (ver 2023-06-06)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06).
| Original property | New property | Notes |
| --------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ServiceIds` | `ServiceIds` | No longer `required`. |
| `GroupIds` | `ReservationGroupIds` | - |
| `ReservationIds` | `ReservationIds` | No change. |
| `CustomerIds` | `AccountIds` | Accounts are more general than Customers and include Companies as well. |
| `AssignedResourceIds` | `AssignedResourceIds` | No change. |
| `RateIds` | n/a | Currently not supported. |
| `BusinessSegmentIds` | n/a | Currently not supported. |
| `ChannelNumbers` | `ChannelNumbers` | Reduced to maximum of 100 items. |
| `Numbers` | `Numbers` | No change. |
| `StartUtc` | See [Time filters](#time-filters) | - |
| `EndUtc` | See [Time filters](#time-filters) | - |
| `TimeFilter` | See [Time filters](#time-filters) | - |
| `Currency` | n/a | Currently not supported. |
| `States` | `States` | Uses [Service order state](https://docs.mews.com/connector-api/operations/reservations#service-order-state) instead of [Service order state (ver 2017-04-12)](https://docs.mews.com/connector-api/operations/reservations#service-order-state-ver-2017-04-12): `Enquired` has been renamed to `Inquired`. |
| `Limitation` | `Limitation` | Required for all requests. |
## Time filters
The combination of the request properties `TimeFilter`, `StartUtc` and `EndUtc` has been replaced by individual Time interval properties. For example, instead of `"TimeFilter":"Colliding"` use `CollidingUtc` request property.
Original request to [Get all reservations (ver 2017-04-12)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2017-04-12):
```txt
[PlatformAddress]/api/connector/v1/reservations/getAll
```
```json
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"StartUtc": "2023-04-01T00:00:00Z",
"EndUtc": "2023-05-05T00:00:00Z",
"TimeFilter": "Colliding"
}
```
Migrated request to [Get all reservations (ver 2023-06-06)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06):
```txt
[PlatformAddress]/api/connector/v1/reservations/getAll/2023-06-06
```
```json
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"CollidingUtc": {
"StartUtc": "2023-04-01T00:00:00Z",
"EndUtc": "2023-05-05T00:00:00Z"
}
}
```
The following table maps the original `TimeFilter` value to the equivalent properties for [Get all reservations (ver 2023-06-06)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06):
| `TimeFilter` value | Request property | Notes |
| ------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `Colliding` | `CollidingUtc` | - |
| `Created` | `CreatedUtc` | - |
| `Updated` | `UpdatedUtc` | - |
| `Start` | `ScheduledStartUtc` | Clarified behavior of filtering by the scheduled time of reservation. |
| `End` | `ScheduledEndUtc` | - |
| `Overlapping` | n/a | Dropped due to low usage, use `CollidingUtc` instead. |
| `Canceled` | n/a | Dropped due to low usage. Can be emulated with the combination of `UpdatedUtc` and `States` set to `[“Canceled"]` filters. |
## Extents removal
The new [Get all reservations (ver 2023-06-06)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) operation doesn’t support extents. Instead, separate API Operations to retrieve respective entities should be used.
### Extents migration example
The following example request to [Get all reservations (ver 2017-04-12)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2017-04-12) uses extents to retrieve Reservations, Customers, and Resources in a single request:
```txt
[PlatformAddress]/api/connector/v1/reservations/getAll
```
```json
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"StartUtc": "2023-04-01T00:00:00Z",
"EndUtc": "2023-05-05T00:00:00Z",
"TimeFilter": "Updated",
"Extent": {
"Reservations": true,
"Customers": true,
"Resources": true
},
}
```
With [Get all reservations (ver 2023-06-06)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) the request needs to be broken down into 3 separate requests:
1. [Get all reservations (ver 2023-06-06)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) to retrieve reservations including `AccountId` and `AssignedResourceIds` properties of individual reservations.
2. [Get all customers](https://docs.mews.com/connector-api/operations/customers#get-all-customers) to retrieve customers' details using the `CustomerIds` filter with `AccountId` values retrieved in the first step (where `AccountType` is `"Customer"`).
3. [Get all resources](https://docs.mews.com/connector-api/operations/resources#get-all-resources) to retrieve resources' details using the `ResourceIds` filter with `AssignedResourceIds` values retrieved in the first step. Alternatively, [Get all resources](https://docs.mews.com/connector-api/operations/resources#get-all-resources) can be regularly requested without filters and cached, since resources' details don’t change frequently.
First request to [Get all reservations (ver 2023-06-06)](https://docs.mews.com/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06):
```txt
[PlatformAddress]/api/connector/v1/reservations/getAll/2023-06-06
```
```json
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"UpdatedUtc": {
"StartUtc": "2023-04-01T00:00:00Z",
"EndUtc": "2023-05-05T00:00:00Z"
},
"Limitation": { "Count": 2 }
}
```
Returns the following response with two reservations:
```jsonc
{
"Reservations": [
{
"Id": "0f515589-99b4-423d-b83a-b237009f0509",
"AccountId": "fadd5bb6-b428-45d5-94f8-fd0d89fece6d",
"AccountType": "Customer",
"AssignedResourceId": "20e00c32-d561-4008-8609-82d8aa525714",
// other properties removed for clarity
},
{
"Id": "bdf1138f-6d47-4f30-9d5a-02c65344f396",
"AccountId": "06ab4938-9675-4f3b-a198-012ed8abc1a6",
"AccountType": "Customer",
"AssignedResourceId": "ed705d9e-ec6d-4ba7-9ffb-a25de7fbfb52",
// other properties removed for clarity
}
],
"Cursor": "bdf1138f-6d47-4f30-9d5a-02c65344f396"
}
```
Second request to [Get all customers](https://docs.mews.com/connector-api/operations/customers#get-all-customers) passes value of `AccountId` to `CustomerIds` filter only from the first reservation as `AccountType` is `"Customer"`:
```txt
[PlatformAddress]/api/connector/v1/customers/getAll
```
```json
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"CustomerIds": [
"fadd5bb6-b428-45d5-94f8-fd0d89fece6d"
],
"Limitation": { "Count": 10 }
}
```
Third request to [Get all resources](https://docs.mews.com/connector-api/operations/resources#get-all-resources) uses values from `AssignedResourceId` in `ResourceIds` filter from both reservations:
```txt
[PlatformAddress]/api/connector/v1/resources/getAll
```
```json
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"ResourceIds": [
"20e00c32-d561-4008-8609-82d8aa525714",
"ed705d9e-ec6d-4ba7-9ffb-a25de7fbfb52"
],
"Limitation": { "Count": 10 }
}
```
### Replacement operations for extents
The following table links individual extents together with their replacement API Operations.
| Extent | API operation | Notes |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Reservations` | n/a | Operation always returns reservations. |
| `ReservationGroups` | [Get all reservation groups](https://docs.mews.com/connector-api/operations/reservationgroups#get-all-reservation-groups) | Use `GroupId` response property in `ReservationGroupIds` request parameter. |
| `Customers` | [Get all customers](https://docs.mews.com/connector-api/operations/customers#get-all-customers) | Use `AccountId` response property where `AccountType` is "Customer". |
| `CustomerAdresses` (sic) | [Get all addresses](https://docs.mews.com/connector-api/operations/addresses#get-all-addresses) | Use `AccountId` response property where in `AccountIds` parameter. |
| `CustomerIdentityDocuments` | [Get all identity documents](https://docs.mews.com/connector-api/operations/identitydocuments#get-all-identity-documents) | Use `AccountId` response property where `AccountType` is "Customer" |
| `Services` | [Get all services](https://docs.mews.com/connector-api/operations/services#get-all-services) | Use `ServiceId` response property. |
| `Products` | [Get all products](https://docs.mews.com/connector-api/operations/products#get-all-products) | Use `ServiceId` response property. |
| `BusinessSegments` | [Get all business segments](https://docs.mews.com/connector-api/operations/businesssegments#get-all-business-segments) | Use `BusinessSegmentId` response property. |
| `Resources` | [Get all resources](https://docs.mews.com/connector-api/operations/resources#get-all-resources) | Use `AssignedResourceIds` response property. |
| `ResourceCategories` | [Get all resource categories](https://docs.mews.com/connector-api/operations/resourcecategories#get-all-resource-categories) | Use `RequestedResourceCategoryId` response property. |
| `ResourceCategoryAssignments` | [Get all resource category assignments](https://docs.mews.com/connector-api/operations/resourcecategories#get-all-resource-category-assignments) | Use `AssignedResourceIds` property in `ResourceIds` request parameter. |
| `Rates` | [Get all rates](https://docs.mews.com/connector-api/operations/rates#get-all-rates) | Use `RateId` response property. |
| `Items` | Get all payments
Get all order items
| Payments: Use Id response property in ReservationIds request parameter.
Order items: Use Id response property in ServiceOrderIds request parameter.
|
| `OrderItems` | [Get all order items](https://docs.mews.com/connector-api/operations/orderitems#get-all-order-items) | Use `Id` response property in `ServiceOrderIds` request parameter. |
| `Notes` | [Get all service order notes](https://docs.mews.com/connector-api/operations/serviceordernotes#get-all-service-order-notes) | Use `Id` response property in `ServiceOrderIds` request parameter. |
| `QrCodeData` | n/a | Use `QrCodeData` response property. |
| `Companies` | [Get all companies](https://docs.mews.com/connector-api/operations/companies#get-all-companies) | Use `AccountId` response property where `AccountType` is `"Company"`. |
| `AccountingStates` | Get all payments
Get all order items
| Use `AccountingStates` request parameter for both operations. |
## Response properties
The following table maps the response properties from the original [Reservation (ver 2017-04-12)](https://docs.mews.com/connector-api/operations/reservations#reservation-ver-2017-04-12) entity to the properties of [Reservation (ver 2023-06-06)](https://docs.mews.com/connector-api/operations/reservations#reservation-ver-2023-06-06). Only the changed properties are listed.
| Original property | New property | Notes |
| --------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ChannelManagerGroupNumber` | n/a | No longer supported. |
| `ChannelManager` | n/a | Replaced by [Get reservations channel manager details](https://docs.mews.com/connector-api/operations/reservations#get-reservation-channel-manager-details). |
| `State` | `State` | Uses [Service order state](https://docs.mews.com/connector-api/operations/reservations#service-order-state) instead of [Service order state (ver 2017-04-12)](https://docs.mews.com/connector-api/operations/reservations#service-order-state-ver-2017-04-12): `Enquired` has been renamed to `Inquired`. |
| `Origin` | `Origin` | Operations-specific values moved to `CommanderOrigin` (see [Commander origin](https://docs.mews.com/connector-api/operations/reservations#commander-origin)). |
| `Purpose` | `Purpose` | No longer required. |
| `StartUtc` | ScheduledStartUtc
ActualStartUtc
| Early check-ins changed `StartUtc` value. Check-in time and scheduled start time are now provided in separate properties. |
| `EndUtc` | ScheduledEndUtc
ActualEndUtc
| Check-outs changed EndUtc value. Check-out time and scheduled end time are now provided in separate properties. |
| `RequestedCategoryId` | `RequestedResourceCategoryId` | - |
| `CompanyId` | `PartnerCompanyId` | - |
| `CancellationReason` | `CancellationReason` | Optional, previously incorrectly marked as required. |
| `OwnerId` | `AccountId` | - |
| `Options` | `Options` | Uses Service order options. |
| `AssignedSpaceId` | `AssignedResourceId` | Previously deprecated. |
| `AssignedSpaceLocked` | `AssignedResourceLocked` | Previously deprecated. |
| `AdultCount` | `PersonCounts` | Previously deprecated. |
| `ChildCount` | `PersonCounts` | Previously deprecated. |
| `CustomerId` | `AccountId` | Previously deprecated. |
| `CompanionIds` | n/a | Previously deprecated, replaced by [Get all companions](https://docs.mews.com/connector-api/operations/companies#get-all-companies). |
| `ChannelManagerId` | `ChannelManagerNumber` | Previously deprecated. |
## Known issues
The [Add reservation](https://docs.mews.com/connector-api/operations/reservations#add-reservation) and [Update reservation](https://docs.mews.com/connector-api/operations/reservations#update-reservation) operations work with older versions of request and response properties corresponding to [Reservation (ver 2017-04-12)](https://docs.mews.com/connector-api/operations/reservations#reservation-ver-2017-04-12) entity. An updated versions of these operations will be published in H2/2025.