# Table of Contents - [Cashiers | Connector API](#cashiers-connector-api) - [Mews Connector API | Connector API](#mews-connector-api-connector-api) - [Usage guidelines | Connector API](#usage-guidelines-connector-api) - [Getting started | Connector API](#getting-started-connector-api) - [Authentication | Connector API](#authentication-connector-api) - [Requests | Connector API](#requests-connector-api) - [Responses | Connector API](#responses-connector-api) - [Pagination | Connector API](#pagination-connector-api) - [Serialization | Connector API](#serialization-connector-api) - [Environments | Connector API](#environments-connector-api) - [Taxation | Connector API](#taxation-connector-api) - [Concepts | Connector API](#concepts-connector-api) - [Multi-property | Connector API](#multi-property-connector-api) - [Best practices | Connector API](#best-practices-connector-api) - [Restrictions | Connector API](#restrictions-connector-api) - [Time units | Connector API](#time-units-connector-api) - [Use cases | Connector API](#use-cases-connector-api) - [Accounting | Connector API](#accounting-connector-api) - [Customer management | Connector API](#customer-management-connector-api) - [Customer messaging | Connector API](#customer-messaging-connector-api) - [Customer loyalty | Connector API](#customer-loyalty-connector-api) - [Data export | Connector API](#data-export-connector-api) - [Guest technology | Connector API](#guest-technology-connector-api) - [Device integration | Connector API](#device-integration-connector-api) - [Housekeeping | Connector API](#housekeeping-connector-api) - [Payment automation | Connector API](#payment-automation-connector-api) - [Reputation management | Connector API](#reputation-management-connector-api) - ['How to' use cases | Connector API](#-how-to-use-cases-connector-api) - [Upsell | Connector API](#upsell-connector-api) - [Events | Connector API](#events-connector-api) - [Kiosk | Connector API](#kiosk-connector-api) - [Certification | Connector API](#certification-connector-api) - [API Events | Connector API](#api-events-connector-api) - [Ways to communicate | Connector API](#ways-to-communicate-connector-api) - [Your integration journey | Connector API](#your-integration-journey-connector-api) - [Webhooks FAQ | Connector API](#webhooks-faq-connector-api) - [Mews Channel Manager API | Channel Manager API](#mews-channel-manager-api-channel-manager-api) - [Booking Engine API | Booking Engine Guide](#booking-engine-api-booking-engine-guide) - [Your journey with Mews | Open API](#your-journey-with-mews-open-api) - [Concepts | Channel Manager API](#concepts-channel-manager-api) - [Use cases | Channel Manager API](#use-cases-channel-manager-api) - [Deprecations | Channel Manager API](#deprecations-channel-manager-api) - [Your integration journey | Channel Manager API](#your-integration-journey-channel-manager-api) - [Usage guidelines | Channel Manager API](#usage-guidelines-channel-manager-api) - [API Operations (Mews) | Channel Manager API](#api-operations-mews-channel-manager-api) - [API Operations (CHM) | Channel Manager API](#api-operations-chm-channel-manager-api) - [Changelog | Channel Manager API](#changelog-channel-manager-api) - [Mews Booking Engine Guide | Booking Engine Guide](#mews-booking-engine-guide-booking-engine-guide) - [Booking Engine Standalone | Booking Engine Guide](#booking-engine-standalone-booking-engine-guide) - [FAQ | Booking Engine Guide](#faq-booking-engine-guide) - [Changelog | Booking Engine Guide](#changelog-booking-engine-guide) - [Usage guidelines | Booking Engine Guide](#usage-guidelines-booking-engine-guide) - [Booking Engine Widget | Booking Engine Guide](#booking-engine-widget-booking-engine-guide) - [Integrations | Booking Engine Guide](#integrations-booking-engine-guide) - [Deprecations | Booking Engine Guide](#deprecations-booking-engine-guide) - [API Operations | Booking Engine Guide](#api-operations-booking-engine-guide) - [Use cases | Booking Engine Guide](#use-cases-booking-engine-guide) - [Troubleshooting | Booking Engine Guide](#troubleshooting-booking-engine-guide) - [Mews Open API | Open API](#mews-open-api-open-api) - [Getting started | Open API](#getting-started-open-api) - [Mews Marketplace | Open API](#mews-marketplace-open-api) - [The Mews APIs | Open API](#the-mews-apis-open-api) - [Booking Engine integrations | Open API](#booking-engine-integrations-open-api) - [Staying up to date | Open API](#staying-up-to-date-open-api) - [Use Cases | Open API](#use-cases-open-api) - [Authentication | Channel Manager API](#authentication-channel-manager-api) - [Channels | Channel Manager API](#channels-channel-manager-api) - [Requests | Channel Manager API](#requests-channel-manager-api) - [Restrictions | Channel Manager API](#restrictions-channel-manager-api) - [Configuration | Channel Manager API](#configuration-channel-manager-api) - [Availability blocks | Channel Manager API](#availability-blocks-channel-manager-api) - [Inventory | Channel Manager API](#inventory-channel-manager-api) - [Inventory updates | Channel Manager API](#inventory-updates-channel-manager-api) - [Certification | Channel Manager API](#certification-channel-manager-api) - [Certification tests | Channel Manager API](#certification-tests-channel-manager-api) - [Availability blocks | Channel Manager API](#availability-blocks-channel-manager-api) - [Compliance | Channel Manager API](#compliance-channel-manager-api) - [Reservations | Channel Manager API](#reservations-channel-manager-api) - [Environments | Channel Manager API](#environments-channel-manager-api) - [Notifications | Channel Manager API](#notifications-channel-manager-api) - [Changelog 2023 | Channel Manager API](#changelog-2023-channel-manager-api) - [Deprecations Policy | Open API](#deprecations-policy-open-api) - [Changelog 2021 | Channel Manager API](#changelog-2021-channel-manager-api) - [Responses | Channel Manager API](#responses-channel-manager-api) - [Changelog 2020 | Channel Manager API](#changelog-2020-channel-manager-api) - [Changelog 2022 | Channel Manager API](#changelog-2022-channel-manager-api) - [Getting started | Booking Engine Guide](#getting-started-booking-engine-guide) - [Changelog 2018 | Channel Manager API](#changelog-2018-channel-manager-api) - [Changelog 2019 | Channel Manager API](#changelog-2019-channel-manager-api) - [Ways to integrate | Booking Engine Guide](#ways-to-integrate-booking-engine-guide) - [Changelog 2017 | Channel Manager API](#changelog-2017-channel-manager-api) - [Deeplinks | Booking Engine Guide](#deeplinks-booking-engine-guide) - [Inventory | Channel Manager API](#inventory-channel-manager-api) - [Authentication | Booking Engine Guide](#authentication-booking-engine-guide) - [Availability blocks | Booking Engine Guide](#availability-blocks-booking-engine-guide) - [Requests | Booking Engine Guide](#requests-booking-engine-guide) - [Reservations | Channel Manager API](#reservations-channel-manager-api) - [Changelog 2023 | Booking Engine Guide](#changelog-2023-booking-engine-guide) - [Migration off the mews.li domain | Booking Engine Guide](#migration-off-the-mews-li-domain-booking-engine-guide) - [Responses | Booking Engine Guide](#responses-booking-engine-guide) - [Changelog 2024 | Booking Engine Guide](#changelog-2024-booking-engine-guide) - [Google Tag Manager | Booking Engine Guide](#google-tag-manager-booking-engine-guide) - [Advanced guide | Booking Engine Guide](#advanced-guide-booking-engine-guide) - [Google Analytics cross-domain tracking | Booking Engine Guide](#google-analytics-cross-domain-tracking-booking-engine-guide) - [Environments | Booking Engine Guide](#environments-booking-engine-guide) - [Images | Booking Engine Guide](#images-booking-engine-guide) - [Getting started | Booking Engine Guide](#getting-started-booking-engine-guide) - [Google Tag Manager Configuration | Booking Engine Guide](#google-tag-manager-configuration-booking-engine-guide) - [On session payments | Booking Engine Guide](#on-session-payments-booking-engine-guide) - [Payment cards | Booking Engine Guide](#payment-cards-booking-engine-guide) - [Changelog 2022 | Booking Engine Guide](#changelog-2022-booking-engine-guide) - [Supporting payment cards | Booking Engine Guide](#supporting-payment-cards-booking-engine-guide) - [Availability blocks | Booking Engine Guide](#availability-blocks-booking-engine-guide) - [Changelog 2021 | Booking Engine Guide](#changelog-2021-booking-engine-guide) - [Supported language codes | Booking Engine Guide](#supported-language-codes-booking-engine-guide) - [Changelog 2020 | Booking Engine Guide](#changelog-2020-booking-engine-guide) - [Payment card authorization | Booking Engine Guide](#payment-card-authorization-booking-engine-guide) - [Vouchers | Booking Engine Guide](#vouchers-booking-engine-guide) - [Supported currency codes | Booking Engine Guide](#supported-currency-codes-booking-engine-guide) - [Google Triggers Reference | Booking Engine Guide](#google-triggers-reference-booking-engine-guide) - [Reference | Booking Engine Guide](#reference-booking-engine-guide) - [Use cases | Booking Engine Guide](#use-cases-booking-engine-guide) - [Reservations | Booking Engine Guide](#reservations-booking-engine-guide) - [Configuration | Booking Engine Guide](#configuration-booking-engine-guide) - [Reservation groups | Booking Engine Guide](#reservation-groups-booking-engine-guide) - [Door | Open API](#door-open-api) - [Distribution | Open API](#distribution-open-api) - [Hotels | Booking Engine Guide](#hotels-booking-engine-guide) - [Revenue Management | Open API](#revenue-management-open-api) - [Guest Technology | Open API](#guest-technology-open-api) - [Services | Booking Engine Guide](#services-booking-engine-guide) - [Accounting | Open API](#accounting-open-api) - [Customer Relationship | Open API](#customer-relationship-open-api) - [Service Optimization | Open API](#service-optimization-open-api) --- # Cashiers | Connector API [](https://mews-systems.gitbook.io/connector-api/operations/cashiers#get-all-cashiers) Get all cashiers ------------------------------------------------------------------------------------------------------------ Returns all cashiers. Note this operation uses [Pagination](https://mews-systems.gitbook.io/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](https://mews-systems.gitbook.io/connector-api/concepts/multi-property) . ### [](https://mews-systems.gitbook.io/connector-api/operations/cashiers#request) Request `[PlatformAddress]/api/connector/v1/cashiers/getAll` Copy { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "Ids": [\ "9a36e3fa-2299-474b-a8a2-5ea4da317abc"\ ], "UpdatedUtc": { "StartUtc": "2023-10-01T00:00:00Z", "EndUtc": "2023-10-31T00:00:00Z" }, "ActivityStates": [\ "Active"\ ], "EnterpriseIds": [\ "3fa85f64-5717-4562-b3fc-2c963f66afa6",\ "4d0201db-36f5-428b-8d11-4f0a65e960cc"\ ], "Limitation": { "Count": 10 } } Property Type Contract Description `ClientToken` string required Token identifying the client application. `AccessToken` string required Access token of the client application. `Client` string required Name and version of the client application. `EnterpriseIds` array of string optional, max 1000 items Unique identifiers of the Enterprises. If not specified, the operation returns data for all enterprises within scope of the Access Token. `Ids` array of string optional, max 1000 items Unique identifiers of the requested [Cashier](https://mews-systems.gitbook.io/connector-api/operations/cashiers#cashier) . `UpdatedUtc` [Time interval](https://mews-systems.gitbook.io/connector-api/operations/_objects#time-interval) optional, max length 3 months Interval in which `Cashier` was updated. `ActivityStates` array of [Activity state](https://mews-systems.gitbook.io/connector-api/operations/_objects#activity-state) optional Whether to return only active, only deleted or both records. `Limitation` [Limitation](https://mews-systems.gitbook.io/connector-api/guidelines/pagination#limitation) required Limitation on the quantity of data returned and optional Cursor for the starting point of data. ### [](https://mews-systems.gitbook.io/connector-api/operations/cashiers#response) Response Copy { "Cashiers": [\ {\ "Id": "9a36e3fa-2299-474b-a8a2-5ea4da317abc",\ "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",\ "IsActive": true,\ "Name": "Main Cashier",\ "CreatedUtc": "2023-10-01T11:48:57Z",\ "UpdatedUtc": "2023-10-28T11:48:57Z"\ }\ ], "Cursor": "0b9560fb-055d-47d3-a6d4-e579c44ca558" } Property Type Contract Description `Cashiers` array of [Cashier](https://mews-systems.gitbook.io/connector-api/operations/cashiers#cashier) required Cashiers in the enterprise. `Cursor` string optional Unique identifier of the item one newer in time order than the items to be returned. If Cursor is not specified, i.e. null, then the latest or most recent items will be returned. #### [](https://mews-systems.gitbook.io/connector-api/operations/cashiers#cashier) Cashier Property Type Contract Description `Id` string required Unique identifier of the cashier. `EnterpriseId` string required Unique identifier of the [Enterprise](https://mews-systems.gitbook.io/connector-api/operations/enterprises#enterprise) . `IsActive` boolean required Whether the cashier is still active. `Name` string required Name of the cashier. `CreatedUtc` string required Creation date and time of the `Cashier` in UTC timezone in ISO 8601 format. `UpdatedUtc` string required Last update date and time of the `Cashier` in UTC timezone in ISO 8601 format. [PreviousCancellation policies](https://mews-systems.gitbook.io/connector-api/operations/cancellationpolicies) [NextCashier transactions](https://mews-systems.gitbook.io/connector-api/operations/cashiertransactions) Last updated 10 months ago Was this helpful? This site uses cookies to deliver its service and to analyze traffic. By browsing this site, you accept the [privacy policy](https://policies.gitbook.com/privacy/cookies) . AcceptReject --- # Mews Connector API | Connector API Welcome to the **Mews Connector API**! This is a general-purpose API that enables partners of Mews to access data and services in **Mews Operations**. To make a quick start and get a feel for the API, see [Getting started](https://mews-systems.gitbook.io/connector-api/getting-started) . For a full guide on how to connect, what authentication tokens you need, the meaning of error codes and much more, see our [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) . To gain deeper insights into Mews concepts, see [Concepts](https://mews-systems.gitbook.io/connector-api/concepts) . For guidance on using the API for specific scenarios, our [Use cases](https://mews-systems.gitbook.io/connector-api/use-cases) section will help you through your implementation. Detailed information on all API operations can be found in [API Operations](https://mews-systems.gitbook.io/connector-api/operations) , and information on event mechanisms like Webhooks in [API Events](https://mews-systems.gitbook.io/connector-api/events) . If you have any questions or you encounter issues, please reach out to us at [partnersuccess@mews.com](mailto:partnersuccess@mews.com) . > #### > > [](https://mews-systems.gitbook.io/connector-api#changes-to-this-api) > > Changes to this API > > * For the history of changes to the API, see the [Changelog](https://mews-systems.gitbook.io/connector-api/changelog) > . > > * For important information on deprecations, see [Deprecations](https://mews-systems.gitbook.io/connector-api/deprecations) > . > > * To track changes and updates, you can follow the [GitHub repository](https://github.com/MewsSystems/gitbook-connector-api/tree/master) > . > > #### > > [](https://mews-systems.gitbook.io/connector-api#openapi-definition) > > OpenAPI definition > > We maintain an [OpenAPI definition](https://api.mews.com/Swagger/connector/swagger.yaml) > (formerly Swagger) for the **Mews Connector API**. You can use this to build out client applications using third party tools. [NextGetting started](https://mews-systems.gitbook.io/connector-api/getting-started) Last updated 11 months ago Was this helpful? --- # Usage guidelines | Connector API This section provides important guidelines on how to use the **Mews Connector API**. For a deeper understanding of Mews concepts, see [Concepts](https://mews-systems.gitbook.io/connector-api/concepts) . For information about individual endpoints or operations, see [API Operations](https://mews-systems.gitbook.io/connector-api/operations) . > #### > > [](https://mews-systems.gitbook.io/connector-api/guidelines#terminology) > > Terminology > > Some of the terms used in the API, such as _enterprise_, _customer_ or _resource_ may not be familiar. For example, we use _resource_ to describe guest rooms and other types of bookable space. For a full description of all the terms used, see the [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) > . [](https://mews-systems.gitbook.io/connector-api/guidelines#contents) Contents ----------------------------------------------------------------------------------- * [Authentication](https://mews-systems.gitbook.io/connector-api/guidelines/authentication) Details of how API Operation requests are authenticated. * [Requests](https://mews-systems.gitbook.io/connector-api/guidelines/requests) Details of how to make API Operation requests. * [Responses](https://mews-systems.gitbook.io/connector-api/guidelines/responses) Details of API Operation responses, including error messages. * [Environments](https://mews-systems.gitbook.io/connector-api/guidelines/environments) A description of the different environments available and how to access them, including test credentials, request limits and more. * [Serialization](https://mews-systems.gitbook.io/connector-api/guidelines/serialization) Various topics related to data formats. * [Pagination](https://mews-systems.gitbook.io/connector-api/guidelines/pagination) An explanation of the pagination feature and how to use it to fetch data. * [Best practices](https://mews-systems.gitbook.io/connector-api/guidelines/best-practices) Advice on best practices for using the API. [PreviousGetting started](https://mews-systems.gitbook.io/connector-api/getting-started) [NextAuthentication](https://mews-systems.gitbook.io/connector-api/guidelines/authentication) Last updated 10 months ago Was this helpful? --- # Getting started | Connector API This page walks you through the key steps to begin developing your integration with the **Mews Connector API**. Whether you're exploring the demo environment, preparing for certification, or validating your first request, this guide covers the tools, environments and concepts you'll need. > **Ready to try a test call?** Jump to [Step 2: Make your first API call](https://mews-systems.gitbook.io/connector-api/getting-started#step-2-make-your-first-api-call) > . [](https://mews-systems.gitbook.io/connector-api/getting-started#what-youll-need) What you’ll need ------------------------------------------------------------------------------------------------------- Before making your first request, make sure you're familiar with the following: * **Authentication tokens** Every API request requires: * `ClientToken`: Identifies your application. Issued by Mews. * `AccessToken`: Identifies the enterprise or property you're connecting to. Issued by the property. * `Client`: A short string naming your application. * **Mews environments** Mews provides two environments: * [Demo environment](https://mews-systems.gitbook.io/connector-api/guidelines/environments#demo-environment) – for development and testing. * Net pricing and Gross pricing variants simulate different tax regimes used by properties in different jurisdictions. * [Production environment](https://mews-systems.gitbook.io/connector-api/guidelines/environments#production-environment) – used by live properties after certification. * **Mews Operations** You can optionally log into the UI of Mews Operations (used by hotel staff) to understand how API data maps to the product. * **Demo credentials** Mews provides shared tokens and login details for test properties. These are suitable for early development, but subject to [rate limits](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-limits) . > **Want to know more?** For full details, see [Authentication](https://mews-systems.gitbook.io/connector-api/guidelines/authentication) > and [Environments](https://mews-systems.gitbook.io/connector-api/guidelines/environments) > . [](https://mews-systems.gitbook.io/connector-api/getting-started#step-1-set-up-your-environment) Step 1: Set up your environment ------------------------------------------------------------------------------------------------------------------------------------- To begin testing: 1. **Choose a demo property** from the list in [Demo environments](https://mews-systems.gitbook.io/connector-api/guidelines/environments#demo-environments) . * Use either the Net pricing or Gross pricing variant depending on your target markets. 2. **Note the tokens** for that property: * `ClientToken` * `AccessToken` 3. **(Optional)** Log in to [Mews Operations](https://app.mews-demo.com/) using the provided email and password to explore the UI and sample data. You’ll use these credentials to make authenticated API requests. [](https://mews-systems.gitbook.io/connector-api/getting-started#step-2-make-your-first-api-call) Step 2: Make your first API call --------------------------------------------------------------------------------------------------------------------------------------- Let’s start by calling [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) , which returns details about the test property — a useful check that your setup is working. * **Endpoint URL** Copy https://api.mews-demo.com/api/connector/v1/configuration/get * **Request body** Copy { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "7059D2C25BF64EA681ACAB3A00B859CC-D91BFF2B1E3047A3E0DEC1D57BE1382", "Client": "NameOfYourCompanyOrApplication" } * **Expected response** If successful, the API will return HTTP status code `200 - OK` along with property details in the message body: Copy { "NowUtc": "2021-05-05T11:39:29Z", "Enterprise": { "Id": "c65ea6e9-2340-42f4-9136-ab3a00b6da22", "Name": "Connector API Hotel (Net Pricing) TEST", "TimeZoneIdentifier": "America/New_York", "LegalEnvironmentCode": "US-DC", "AccommodationEnvironmentCode": "US", ... }, "PaymentCardStorage": { "PublicKey": "1100016827" } } > **Requests and responses**: For more on request formatting and response codes, see [Requests](https://mews-systems.gitbook.io/connector-api/guidelines/requests) > and [Responses](https://mews-systems.gitbook.io/connector-api/guidelines/responses) > respectively. [](https://mews-systems.gitbook.io/connector-api/getting-started#step-3-learn-the-api-essentials) Step 3: Learn the API essentials --------------------------------------------------------------------------------------------------------------------------------------- ### [](https://mews-systems.gitbook.io/connector-api/getting-started#time-and-data-serialization) Time and data serialization * All dates and times are in UTC. * Dates, durations and other data types follow specific [serialization rules](https://mews-systems.gitbook.io/connector-api/guidelines/serialization) . ### [](https://mews-systems.gitbook.io/connector-api/getting-started#pagination) Pagination * Some operations (like [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-2023-06-06) ) use [pagination](https://mews-systems.gitbook.io/connector-api/guidelines/pagination) to handle large result sets. ### [](https://mews-systems.gitbook.io/connector-api/getting-started#rate-limits) Rate limits * Shared demo credentials may return `429 - Too many requests` response code if multiple developers are testing the same property. * Use a different demo property if limits are reached. ### [](https://mews-systems.gitbook.io/connector-api/getting-started#error-handling) Error handling * Check the [response code](https://mews-systems.gitbook.io/connector-api/guidelines/responses#response-codes) and [details](https://mews-systems.gitbook.io/connector-api/guidelines/responses#error-response-details) to diagnose issues. * Always validate required fields and timezones in your request payloads. > **Best practices**: For additional tips on how to get the most out of your integration, see our [best practices](https://mews-systems.gitbook.io/connector-api/guidelines/best-practices) > . [](https://mews-systems.gitbook.io/connector-api/getting-started#next-steps) Next steps -------------------------------------------------------------------------------------------- Now that you've made a successful call, here’s where to go next: * [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) – How to structure requests, handle authentication, best practices, and more. * [API Operations](https://mews-systems.gitbook.io/connector-api/operations) – Full list of API Operations. * [API Events](https://mews-systems.gitbook.io/connector-api/events) – How to receive near-real-time event notifications. * [Concepts](https://mews-systems.gitbook.io/connector-api/concepts) – Deeper insights into selected Mews concepts. * [Use cases](https://mews-systems.gitbook.io/connector-api/use-cases) – Guidance on using the API for common scenarios. * [Certification](https://mews-systems.gitbook.io/connector-api/your-journey/certification) – What’s required before going live. * [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) – Terminology for terms like _enterprise_, _customer_, and _resource_. [PreviousMews Connector API](https://mews-systems.gitbook.io/connector-api) [NextUsage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) Last updated 6 months ago Was this helpful? --- # Authentication | Connector API To interact with the **Mews Connector API**, you need to authenticate your requests using `ClientToken` and `AccessToken`. These tokens are supplied as parameters in the request body, ensuring that only authorized clients can access and manipulate data. * `ClientToken`: Unique to your application, serving as the identifier of the API client. * `AccessToken`: Unique to the connection with a property (referred to as an enterprise in the API), identifying the property or properties whose data and services you can access. * `Client`: The name and version of the client application you are integrating with Mews. > **Environment-specific**: Note that each Mews environment (e.g., demo, production) requires a different set of tokens. [](https://mews-systems.gitbook.io/connector-api/guidelines/authentication#access-tokens) Access Tokens ------------------------------------------------------------------------------------------------------------ A unique `AccessToken` is generated for each new enterprise (property) using your connection. This allows your application to access the data for that enterprise via the API. ### [](https://mews-systems.gitbook.io/connector-api/guidelines/authentication#portfolio-access-tokens) Portfolio Access Tokens Access Tokens typically allow access to a single, named enterprise. However, some tokens may be Portfolio Access Tokens, which facilitate multi-property operations. These tokens grant access to more than one enterprise with a single token. For more information, see [Multi-property](https://mews-systems.gitbook.io/connector-api/concepts/multi-property) . [](https://mews-systems.gitbook.io/connector-api/guidelines/authentication#obtaining-your-tokens) Obtaining your tokens ---------------------------------------------------------------------------------------------------------------------------- ### [](https://mews-systems.gitbook.io/connector-api/guidelines/authentication#demo-environment) Demo environment Public tokens are available for the demo environment. For more details, see [Environments](https://mews-systems.gitbook.io/connector-api/guidelines/environments) . ### [](https://mews-systems.gitbook.io/connector-api/guidelines/authentication#production-environment) Production environment To receive credentials for production usage, you must successfully complete a [certification process](https://mews-systems.gitbook.io/connector-api/your-journey) . After certification: 1. Your integration profile will be created. 2. You will automatically receive a unique `ClientToken`, which remains the same for all connections in the production environment. 3. A unique `AccessToken` will be generated and shared with you for each enterprise requesting to connect their Mews profile to your system. [PreviousUsage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) [NextRequests](https://mews-systems.gitbook.io/connector-api/guidelines/requests) Last updated 10 months ago Was this helpful? --- # Requests | Connector API The API accepts only `HTTP POST` requests with `Content-Type` set to `application/json` and JSON content depending on the operation to be performed. All operations follow this address pattern: Copy [PlatformAddress]/api/connector/v1/[Resource]/[Action] * **PlatformAddress** - Base address of the Mews Connector API, this depends on the environment (e.g. test, demo, production) * **Resource** - Resource or domain entity which is the target of the action, always pluralized (e.g. bills, reservations) * **Action** - Name of the action to be performed on the resource (e.g. getAll, add, delete) > **Exact address**: The operation address **must match the specified format exactly**. It is case-sensitive and must not include a trailing slash or any additional characters. If the address does not match the expected format, the server will return a `404 Not Found` error. [](https://mews-systems.gitbook.io/connector-api/guidelines/requests#body) Body ------------------------------------------------------------------------------------ All API operations require the inclusion of `ClientToken`, `AccessToken` and `Client` in the request. These parameters authenticate incoming requests. For more details, see [Authentication](https://mews-systems.gitbook.io/connector-api/guidelines/authentication) . Additionally, all API operations can optionally accept `LanguageCode` and `CultureCode`. These parameters enforce the language and culture of the operation, potentially affecting entity descriptions or error messages. Both values must be provided together; otherwise, default values will be used. Copy { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "LanguageCode": null, "CultureCode": null } Property Type Contract Description `ClientToken` string required Token identifying the client application. `AccessToken` string required Access token of the client application. `Client` string required Name and version of the client application. `LanguageCode` string optional Code of the [language](https://mews-systems.gitbook.io/connector-api/operations/languages#language) . `CultureCode` string optional Code of the culture. [](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-limits) Request limits -------------------------------------------------------------------------------------------------------- Mews implements API request limits in order to protect our systems against an excessive volume of calls which could compromise the service for all its users. The limits are dependent on circumstances and on the environment - see [Environments](https://mews-systems.gitbook.io/connector-api/guidelines/environments) for details of specific request limits. Regardless, your system should be prepared to receive a `429 Too Many Requests` response in cases where you hit such a limit - see [Responses](https://mews-systems.gitbook.io/connector-api/guidelines/responses) . If you receive this error response, your system can re-try after an interval time, however some care is needed in choosing the interval time. In case of a 429 error, we include the `Retry-After` HTTP header in the response to indicate how long you should wait before making a re-try attempt. Alternatively, you could implement something like an exponential backoff strategy, i.e. using a progressively longer wait between re-tries for consecutive error responses. Pausing for a fixed amount of time is never recommended. If you are receiving `429 Too Many Requests` errors, then we would also recommend examining your implementation to see if it is possible to make design changes to reduce the load on our API and prevent the errors being generated in the first place. [](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-timeouts) Request timeouts ------------------------------------------------------------------------------------------------------------ In rare circumstances, you may receive a `408 Request Timeout` response if the request puts a large demand on the system and we are unable to prepare the data within a reasonable timeframe. There are numerous scenarios in which that might occur, the most common of which are related to [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) . There can be a large number of reservations on the system, and they can carry a lot of information. You should be prepared to receive this error response and have a mitigation solution in place. What should you do if you receive a 408 error? The error indicates that the load required to prepare the response is too great, so the best solution is to lessen the load. If you are asking for reservations over a period of time, instead make multiple requests over shorter periods of time. For example, if a single request for reservation data over a period of several days returns a 408 error, instead try multiple requests, each for a separate day; if a single request for reservation data over a period of one day returns a 408 error, instead try multiple requests, each for a separate hour. [](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-minimal-response) Request minimal response ---------------------------------------------------------------------------------------------------------------------------- > #### > > [](https://mews-systems.gitbook.io/connector-api/guidelines/requests#restricted) > > Restricted! > > This functionality is currently in beta-test and as such it is subject to change. By default, in case of success the API responds to every request with a `200 OK` status code and a JSON response body containing the result of the operation. For some use cases, like polling changes and storing responses into a data lake, the client may prefer to receive an empty body where appropriate, with a `204 No Content` status code. This feature is optional, and can be achieved by setting the `Prefer` header to `return=minimal` in the request. Copy POST /api/connector/v1/reservations/getAll HTTP/1.1 Host: api.mews-demo.com Content-Type: application/json Prefer: return=minimal When the header is present, the API will return `204 No Content` for the following endpoints: * All endpoints which support [pagination](https://mews-systems.gitbook.io/connector-api/guidelines/pagination) and where the request results in an empty page. * All endpoints which normally return an empty JSON object in case of success, e.g. [Delete account notes](https://mews-systems.gitbook.io/connector-api/operations/accountnotes#delete-account-notes) . [PreviousAuthentication](https://mews-systems.gitbook.io/connector-api/guidelines/authentication) [NextResponses](https://mews-systems.gitbook.io/connector-api/guidelines/responses) Last updated 7 months ago Was this helpful? --- # Responses | Connector API [](https://mews-systems.gitbook.io/connector-api/guidelines/responses#content-type) Content-type ----------------------------------------------------------------------------------------------------- The API responds with `Content-Type` set to `application/json`, and with JSON content in the body. In case of a 204 response (see [Request minimal response](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-minimal-response) ), the `Content-Type` header is _not_ set and the response body is empty. [](https://mews-systems.gitbook.io/connector-api/guidelines/responses#response-codes) Response codes --------------------------------------------------------------------------------------------------------- In case of success, the HTTP status code is normally 200 and the content contains the result according to the nature of the request. The client may opt-in to instead receive HTTP status code 204 in certain circumstances, see [Request minimal response](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-minimal-response) . In case of error, there are multiple HTTP status codes for different types of errors. Every response contains `Request-Id` header with unique identifation of the request, that can be used in communication with [partnersuccess@mews.com](mailto:partnersuccess@mews.com) . * **200 OK** * Success response. The content contains the result according to the nature of the request. * **204 No Content** * Success response, the content is empty. Clients can opt-in to receive this response code, see [Request minimal response](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-minimal-response) . * **400 Bad Request** * Error caused by the client app, e.g. in case of malformed request or invalid identifier of a resource. In most cases, such an error signifies a bug in the client app (consumer of the API). * **401 Unauthorized** * Error caused by usage of invalid ClientToken, AccessToken, or you may not have the necessary permission to use the endpoint. * **403 Forbidden** * Server error that should be reported to the end user of the client app. Happens for example when the server-side validation fails or when a business-logic check is violated. * **404 Not found** * The server cannot find the resource requested by the client app. Verify the URL and request method. * **408 Request Timeout** * Error caused by heavy request that takes too long to process (typically tens of seconds). To get around this, request data in smaller batches. For more information, see [Request timeouts](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-timeouts) . * **409 Conflict** * The request cannot be completed because the data has changed. To get around this error, try refreshing the data on the client and resubmitting the request. * **429 Too Many Requests** * Error caused by too many requests sent in a given amount of time. Response contains `Retry-After` header indicating how long the user agent should wait before making a follow-up request. For more information, see [Request limits](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-limits) . * **500 Internal Server Error** and other **5xx** response codes * Unexpected error on the Mews side. This may be due to a software fault. If such a situation occurs, the error will be logged and the development team notified. [](https://mews-systems.gitbook.io/connector-api/guidelines/responses#error-response-details) Error response details ------------------------------------------------------------------------------------------------------------------------- In case of any error, the returned JSON object describes the error and has the following properties: Property Type Contract Description `Message` string required Description of the error. `RequestId` string optional Unique identifier of the request. You can provide this unique identifier when communicating with [partnersuccess@mews.com](mailto:partnersuccess@mews.com) for quick identification of the request. `Details` string optional Additional details about the error (request, headers, server stack trace, inner exceptions etc.). Only available on development environment. [PreviousRequests](https://mews-systems.gitbook.io/connector-api/guidelines/requests) [NextEnvironments](https://mews-systems.gitbook.io/connector-api/guidelines/environments) Last updated 4 months ago Was this helpful? --- # Pagination | Connector API Pagination is a feature introduced into the API to manage requests for large amounts of data. It enables us to deliver data in a measured way that does not put a strain on performance for all API users. We use a method called _cursor pagination_. This takes the following form: ### [](https://mews-systems.gitbook.io/connector-api/guidelines/pagination#request) Request `[PlatformAddress]/api/connector/v1/{entity}/getAll` Copy { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "Limitation":{ "Cursor": "e7f26210-10e7-462e-9da8-ae8300be8ab7", "Count": 10 } } Property Type Contract Description `ClientToken` string required Token identifying the client application. `AccessToken` string required Access token of the client application. `Client` string required Name and version of the client application. `Limitation` [Limitation](https://mews-systems.gitbook.io/connector-api/guidelines/pagination#limitation) required Limitation on the quantity of data returned (using cursor pagination). #### [](https://mews-systems.gitbook.io/connector-api/guidelines/pagination#limitation) Limitation Property Type Contract Description `Cursor` string optional Unique identifier of the item one newer in time order than the items to be returned. If Cursor is not specified, i.e. null, then the latest or most recent items will be returned. Note that the response message will include the identifier of the oldest item in the response, which can then be used in subsequent calls - see _Limitation example_ below. `Count` number required Count of items to be returned, minimum 1, maximum 1000. > **Limitation example:** A request with Cursor set to null and Count set to 10 will return the latest or most recent 10 items, and the value of Cursor in the response will reference the oldest of those 10 items returned. Let's say the value of Cursor returned is "12345", then if a subsequent request is made with Cursor set to "12345" and Count set to 10, then the next oldest 10 items will be returned. This process can be repeated as required to fetch historical data. ### [](https://mews-systems.gitbook.io/connector-api/guidelines/pagination#response) Response Copy { "Data": [\ {\ ...\ }\ ], "Cursor": "7f9325f6-ef44-4911-89a8-ae51010a5aa4" } Property Type Contract Description `Data` ... required Placeholder for response data (details will vary). `Cursor` string optional Unique identifier of the last and hence oldest datum returned. This can be used in [Limitation](https://mews-systems.gitbook.io/connector-api/guidelines/pagination#limitation) in a subsequent request to fetch the next batch of older data. If [Limitation](https://mews-systems.gitbook.io/connector-api/guidelines/pagination#limitation) is specified in the request message, then `Cursor` will always be included in the response message; this is true even when using Extents set to false so that no actual data is returned, e.g. in case of [Get all customers](https://mews-systems.gitbook.io/connector-api/operations/customers#get-all-customers) with all Extent properties set to "false". > **Cursor null:** Cursor is shown as _optional_ even though the field is always present in the response. This is because if there is no data to return then the value of Cursor is null. Cursor identifies the last datum returned, therefore it will only ever be null if there is no data returned. ### [](https://mews-systems.gitbook.io/connector-api/guidelines/pagination#how-to-request-pages) How to request pages Set a suitable value for _Count_ and request pages of data until _Cursor_ in the response is null. Alternatively, count the number of data records returned. If it is less than the number requested, this implies you have come to the end of the data. [PreviousSerialization](https://mews-systems.gitbook.io/connector-api/guidelines/serialization) [NextBest practices](https://mews-systems.gitbook.io/connector-api/guidelines/best-practices) Last updated 2 years ago Was this helpful? --- # Serialization | Connector API [](https://mews-systems.gitbook.io/connector-api/guidelines/serialization#datetimes) Datetimes --------------------------------------------------------------------------------------------------- Some operations of the API accept datetimes in their parameters or return them in their results. Datetime is represented as a `string`, following the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) formatting rules. Moreover, it should always be in [UTC](https://en.wikipedia.org/wiki/ISO_8601#UTC) so that it is clear which instant it represents and there is no room for confusion. This means the standard format for datetime used throughout the API is `YYYY-MM-DDThh:mm:ssZ`. > #### > > [](https://mews-systems.gitbook.io/connector-api/guidelines/serialization#example-1) > > Example 1 > > A date and time of 7:12am on March 22nd 2023 local time in Chicago (UTC-5), would be represented as: > > * `2023-03-22T12:12:00Z` > Where only a date is needed, this is also usually represented with standard datetime, but in this case the time component is set to zero, i.e. `00:00:00`. Note however that when adjusted from local time to UTC, the time may become non-zero. > #### > > [](https://mews-systems.gitbook.io/connector-api/guidelines/serialization#example-2) > > Example 2 > > A date-only of March 22nd 2023 local time in Chicago (UTC-5), would be represented as: > > * `2023-03-22T05:00:00Z` > Note that adjusting from local time to UTC can also shift the date. > #### > > [](https://mews-systems.gitbook.io/connector-api/guidelines/serialization#example-3) > > Example 3 > > A date-only of March 22nd 2023 local time in Beijing (UTC+8), would be represented as: > > * `2023-03-21T16:00:00Z` > The API frequently uses time intervals, i.e. periods of time defined by a start datetime and an end datetime, as usual expressed in UTC. These time intervals are inclusive, meaning that the interval includes the start and end as part of the interval. For example, an interval with start of January 1st and end of January 5th includes the 1st, 2nd, 3rd, 4th and 5th. The datetimes used to define a time interval follow all the normal rules for datetimes, as described above. > #### > > [](https://mews-systems.gitbook.io/connector-api/guidelines/serialization#example-4) > > Example 4 > > A date-only time interval of March 20th to March 23rd 2023 (including the 20th, 21st, 22nd and 23rd) local time in Beijing (UTC+8), would be represented as: > > * StartUtc `2023-03-19T16:00:00Z` > > * EndUtc `2023-03-22T16:00:00Z` > [](https://mews-systems.gitbook.io/connector-api/guidelines/serialization#durations) Durations --------------------------------------------------------------------------------------------------- Some operations of the API accept durations in their parameters or return them in their results. Duration is represented as a `string`, following the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) formatting rules. As an example, consider minimum and maximum length of the reservation: * MinLength `P0Y0M1DT0H0M0S` * MaxLength `P0Y0M3DT0H0M0S` [](https://mews-systems.gitbook.io/connector-api/guidelines/serialization#update-values) Update values ----------------------------------------------------------------------------------------------------------- Copy { "UpdateValue": { "Value": "SampleValue" } } To update or remove a value of a property, we use the structure called `Update value`, which allows us to distinguish if you want to set a new value, keep the old one or completely remove it (if the property is nullable). Therefore, there is no need to resend unchanged values. This also reduces the possibility of concurrency errors - resending all values (of which only few has actually changed) might overwrite other changes done by other users or integration partner. Example usages: * To keep a current property value, do _not_ send the `Update value` object at all. * To set a new property value, provide it as a `Value` parameter of `Update value` object. * To remove an old value, send `null` inside the `Value` parameter of `Update value` object. Copy { "PropertyWithoutChange": null, "PropertyWithNewValue": { "Value": "NewValue" }, "PropertyWithDeletedValue": { "Value": null } } [](https://mews-systems.gitbook.io/connector-api/guidelines/serialization#coproducts) Coproducts ----------------------------------------------------------------------------------------------------- Copy { "Coproduct": { "Discriminator": "TypeOfValue", "Value": { "TypeSpecificProperty": "SampleValue" } } } To model the structure of some general object, the characteristic of which can differ based on the specified type, we use `Coproducts` (also called `Discriminated unions`, `Sum types` or `Or types`). For example, take a look at bookable [Resources](https://mews-systems.gitbook.io/connector-api/operations/resources#resource) . We currently support just one subtype - spaces (rooms, beds in hotels). Looking forward, we strive to include other types of resources like objects or persons soon. This means that basic properties such as `Id` or `Name` can be shared across the different resource subtypes, but others such as `FloorNumber` only make sense in context of spaces. These specific fields are stored in the coproduct object (in this example named `Data`) which stores the type of information in the `Discriminator` property and the values as part of the `Value` property. Copy { "Id": "5ee074b1-6c86-48e8-915f-c7aa4702086f", "IsActive": true, "Name": "101", "ParentResourceId": null, "State": "Dirty", "Descriptions": {}, "Data": { "Discriminator": "Space", "Value": { "FloorNumber": "3", "LocationNotes": "A1" } }, "CreatedUtc": "2016-03-29T15:14:06Z", "UpdatedUtc": "2016-03-29T15:14:06Z" } [PreviousEnvironments](https://mews-systems.gitbook.io/connector-api/guidelines/environments) [NextPagination](https://mews-systems.gitbook.io/connector-api/guidelines/pagination) Last updated 2 years ago Was this helpful? --- # Environments | Connector API Mews supports two main environments: Demo and Production. Demo can be used for integration development and testing. Production is for live customer sites. [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#pricing-environments) Pricing environments ------------------------------------------------------------------------------------------------------------------------ Enterprises can be configured for Gross Tax or Net Tax. In the Production environment this will depend on the individual enterprise. For development and test purposes, we have set up two versions of the Demo environment, one for Gross Tax and one for Net Tax. * **Gross Pricing Environments**: These are environments in which taxes are _included_ in the pricing that is offered to the end customer, such as used by Germany, UK and Australia. * **Net Pricing Environments**: These are environments in which taxes are _excluded_ from the pricing that is offered to the end customer, such as used in the USA. [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#demo-environments) Demo environments ------------------------------------------------------------------------------------------------------------------ ### [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#security-policy) Security Policy > **IMPORTANT!** The demo environments are completely public and NO REAL DATA should be used for any reason. Failure to comply with these guidelines can result in immediate suspension of the connection or denial of certification. ### [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#platform-addresses) Platform addresses These addresses should be used for testing and development of client applications: * **PlatformAddress** - `https://api.mews-demo.com` * **WebSocketAddress** - `wss://ws.mews-demo.com` ### [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#mews-system-credentials) Mews system credentials These login credentials can be used to access **Mews Operations** (for both Gross and Net Pricing Environments): * **Mews Web Application Address** - `https://app.mews-demo.com` * **Email** - connector-api-demo@mews.com * **Password** - connector-API-2024 ### [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#api-tokens-gross-pricing-environment) API tokens (Gross Pricing Environment) The credentials below will connect with a demo enterprise configured for Gross pricing. This demo enterprise is based in the `United Kingdom` legal and tax environment. It accepts `GBP`, `EUR` and `USD` currencies (any of them may be used). Refer to [Taxations](https://mews-systems.gitbook.io/connector-api/guidelines/environments#taxations) for proper usage of the relevant [Tax rate](https://mews-systems.gitbook.io/connector-api/operations/taxations#tax-rate) codes. Use any of the four sets of tokens. **Integration:** `**Are you ready to integrate with Mews?**` * **ClientToken** - `E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D` * **AccessToken** - `C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D` **Integration:** `**Connector API Test Client 2**` * **ClientToken** - `E916C341431C4D28A866AD200152DBD3-A046EB5583FFBE94DE1172237763712` * **AccessToken** - `CC150C355D6A4048A220AD20015483AB-B6D09C0C84B09538077CB8FFBB907B4` **Integration:** `**Connector API Test Client 3**` * **ClientToken** - `2CC71B0660F345019882AD200155B4FE-4A1FC9080A4DD2A404734003674F77E` * **AccessToken** - `5F56B9903A834F199E28AD20015E58CA-5C6A1A00550634911534AD6A098E8B7` **Integration:** `**Connector API Test Client 4**` * **ClientToken** - `07AB1F14B55C49B8BDD6AD200158423B-273A4497AFF5E20566D7199DB3DC2BA` * **AccessToken** - `39E301DD5A1C4A569087AD20015F60DD-50DC28896E9090CCA0995C9BBD90351` ### [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#api-tokens-net-pricing-environment) API tokens (Net Pricing Environment) The credentials below will connect with a demo enterprise configured for Net pricing. This demo enterprise is based in the `United States - Washington DC` legal and tax environment. It accepts `GBP`, `EUR` and `USD` currencies (any of them may be used). Refer to [Taxations](https://mews-systems.gitbook.io/connector-api/guidelines/environments#taxations) for proper usage of the relevant [Tax rate](https://mews-systems.gitbook.io/connector-api/operations/taxations#tax-rate) codes. Use any of the four sets of tokens. **Integration:** `**Are you ready to integrate with Mews?**` * **ClientToken** - `E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D` * **AccessToken** - `4D6C7ABE0E6A4681B0AFB16900AE5D86-DF50CBC89E1D4FF5859DDF021649ED5` **Integration:** `**Connector API Test Client 2**` * **ClientToken** - `E916C341431C4D28A866AD200152DBD3-A046EB5583FFBE94DE1172237763712` * **AccessToken** - `1AEFA58C55E74D65BDC7AD2001564C12-66633E0B736F523379B9E5966165A55` **Integration:** `**Connector API Test Client 3**` * **ClientToken** - `2CC71B0660F345019882AD200155B4FE-4A1FC9080A4DD2A404734003674F77E` * **AccessToken** - `682C235379B64D909941AD2001577525-BFC60A026081F1350FAA99CAB9F7510` **Integration:** `**Connector API Test Client 4**` * **ClientToken** - `07AB1F14B55C49B8BDD6AD200158423B-273A4497AFF5E20566D7199DB3DC2BA` * **AccessToken** - `BFD4298010F54B069F3DAD20015D53EA-D5561FADFBA4EFC8EA4C179C6BC461F` ### [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#request-limits) Request limits * 200 requests per `AccessToken` within 30 seconds > **IMPORTANT** Number of requests and time window can be changed without prior notice. Your application must be prepared to handle `429 Too Many Requests` responses. See [Request limits](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-limits) > for more information. [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#production-environment) Production environment ---------------------------------------------------------------------------------------------------------------------------- ### [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#security-policy-1) Security Policy > **IMPORTANT!** To protect the live data of each enterprise, please store your production tokens securely and do not share them publicly. ### [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#addresses) Addresses * **PlatformAddress** - `https://api.mews.com` * **WebSocketAddress** - `wss://ws.mews.com` * **Mews Web Application Address** - `https://app.mews.com` ### [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#api-tokens) API tokens * **ClientToken** - Unique to your application, serving as the identifier of the API client. This token will be provided to you by our integration team upon successful [certification](https://mews-systems.gitbook.io/connector-api/your-journey) . * **AccessToken** - Unique token per enterprise. Can be provided to you by the enterprise admin. ### [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#request-limits-1) Request limits * 200 requests per `AccessToken` within 30 seconds > **IMPORTANT** Number of requests and time window can be changed without prior notice. Your application must be prepared to handle `429 Too Many Requests` responses. See [Request limits](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-limits) > for more information. [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#taxations) Taxations -------------------------------------------------------------------------------------------------- Each enterprise operates within a specific [Tax environment](https://mews-systems.gitbook.io/connector-api/operations/taxenvironments#tax-environment) , which defines the applicable [Taxations](https://mews-systems.gitbook.io/connector-api/operations/taxations#taxation) . The tax rates are represented by [Tax rate](https://mews-systems.gitbook.io/connector-api/operations/taxations#tax-rate) codes accepted within that environment. Instead of using numeric tax rates like `0.1`, use [Tax rate](https://mews-systems.gitbook.io/connector-api/operations/taxations#tax-rate) codes such as `AT-S` to accurately represent and calculate the correct taxation for each accounting item in Mews. To obtain the applicable codes: 1. Download the enterprise information using [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) to identify the Tax Environment. 2. Filter for the applicable [Tax rate](https://mews-systems.gitbook.io/connector-api/operations/taxations#tax-rate) codes from the tax environment information retrieved via [Get all tax environments](https://mews-systems.gitbook.io/connector-api/operations/taxenvironments#get-all-tax-environments) . 3. Be sure to note the validity intervals, and monitor any government announcements for changes to tax rates. If changes occur, re-retrieve the enterprise and tax environment information to identify the new tax rate codes. [](https://mews-systems.gitbook.io/connector-api/guidelines/environments#ip-address-allowlisting) IP address allowlisting ------------------------------------------------------------------------------------------------------------------------------ Allowlisting (formerly called 'whitelisting') is a common security measure which can be applied to a system to allow only specified external systems to talk to it. This has traditionally been achieved using IP address-based firewall rules. However, this approach does not work with modern cloud based architectures, which use dynamic and shared IP addresses, proxy servers and elastic resources. For this reason, we do not support the use of IP address allowlists for our APIs and we cannot supply a list of IP addresses for our APIs. [PreviousResponses](https://mews-systems.gitbook.io/connector-api/guidelines/responses) [NextSerialization](https://mews-systems.gitbook.io/connector-api/guidelines/serialization) Last updated 7 days ago Was this helpful? --- # Taxation | Connector API [](https://mews-systems.gitbook.io/connector-api/concepts/taxation#legal-environments-tax-environments-and-tax-codes-in-mews) Legal environments, tax environments and tax codes in Mews --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Each enterprise (i.e. property) in Mews is created with a legal and tax environment corresponding to the region in which it is located. This cannot be changed once the enterprise has been created in the system. Each tax environment contains its own set of hard-coded tax codes that are applicable for accounting items generated in the enterprise with that legal environment. Where applicable, the tax codes allow Mews to record and calculate, accurately and consistently, the tax information associated with each accounting item. If no tax codes are used, then Mews will not calculate the tax breakdown. > **Handling taxable items:** It is important to note the following when handling taxable items. Mews expects its integration partners to send the correct tax codes in combination with net or gross amounts for items that are taxed. Depending on the local government's ruling, tax environments can be subject to change, e.g. Covid tax reductions. It is expected that integration partners act independently and pull updated information from Mews. In turn, Mews will keep the legal environment and tax codes up to date. [](https://mews-systems.gitbook.io/connector-api/concepts/taxation#implementation-of-tax-codes) Implementation of tax codes -------------------------------------------------------------------------------------------------------------------------------- Integration partners should use the following operations to correctly retrieve the set of tax codes applicable to an enterprise (i.e. property): 1. Call [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) to retrieve the `TaxEnvironmentCode` that applies to the relevant enterprise. Note this information for the subsequent API request. 2. Call [Get all tax environments](https://mews-systems.gitbook.io/connector-api/operations/taxenvironments#get-all-tax-environments) and use the `TaxEnvironmentCode` retrieved earlier to find the corresponding list of `TaxationCodes`. The list of `TaxationCodes` is needed to obtain the relevant taxation information for each code in the subsequent API request. 3. Call [Get all taxations](https://mews-systems.gitbook.io/connector-api/operations/taxations#get-all-taxations) to retrieve the individual tax `Codes`, their names and values. [](https://mews-systems.gitbook.io/connector-api/concepts/taxation#tax-exempt-items) Tax exempt items ---------------------------------------------------------------------------------------------------------- Tax-exempt items should be sent with `TaxCode` value `null`. Mews in turn does not calculate any taxation amount for the item. Legal environments in which no actual 0% tax rate exists do not have a corresponding 0% tax code in Mews. [](https://mews-systems.gitbook.io/connector-api/concepts/taxation#multi-tax-environment) Multi-tax environment -------------------------------------------------------------------------------------------------------------------- Multi-tax environments have instances in which a combination of taxes is applied. In those cases, Mews does not use a single composite tax code but expects all tax codes that apply to the accounting item to be sent to Mews. Copy "TaxCodes": [ \ "US-MA-S", \ "US-MA-EXCISE-0.75%" \ ] [](https://mews-systems.gitbook.io/connector-api/concepts/taxation#validation) Validation ---------------------------------------------------------------------------------------------- To understand for which time period a set of tax codes are valid in a given tax environment, please review the `ValidityStartUtc` and `ValidityEndUtc` in [Get all tax environments](https://mews-systems.gitbook.io/connector-api/operations/taxenvironments#get-all-tax-environments) . [PreviousRestrictions](https://mews-systems.gitbook.io/connector-api/concepts/restrictions) [NextTime units](https://mews-systems.gitbook.io/connector-api/concepts/time-units) Last updated 2 years ago Was this helpful? --- # Concepts | Connector API This section delves into domain-specific topics related to the Mews system. An understanding of these will help you to make the most effective use of the API. > #### > > [](https://mews-systems.gitbook.io/connector-api/concepts#terminology) > > Terminology > > Some of the terms used in the API, such as _enterprise_, _customer_ or _resource_ may not be familiar. For example, we use _resource_ to describe guest rooms and other types of bookable space. For a full description of all the terms used, see the [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) > . [](https://mews-systems.gitbook.io/connector-api/concepts#contents) Contents --------------------------------------------------------------------------------- * [Multi-property](https://mews-systems.gitbook.io/connector-api/concepts/multi-property) An explanation of multi-property operation with Portfolio Access Tokens. * [Restrictions](https://mews-systems.gitbook.io/connector-api/concepts/restrictions) An explanation of the algorithms used to support setting and clearing restrictions. * [Taxation](https://mews-systems.gitbook.io/connector-api/concepts/taxation) An explanation of the different tax environments and how they impact your integration. * [Time units](https://mews-systems.gitbook.io/connector-api/concepts/time-units) A detailed explanation of the time units used to describe service reservations. [PreviousBest practices](https://mews-systems.gitbook.io/connector-api/guidelines/best-practices) [NextMulti-property](https://mews-systems.gitbook.io/connector-api/concepts/multi-property) Last updated 10 months ago Was this helpful? --- # Multi-property | Connector API > #### > > [](https://mews-systems.gitbook.io/connector-api/concepts/multi-property#terminology) > > Terminology > > This feature introduces terms such as _Portfolio_, _Portfolio Access Token_ and _Chain_. For a full description of all the terms used, see the [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) > . **Mews Multi-Property** is an optional feature of **Mews Operations**, which enables customers to easily manage a portfolio of multiple properties. A portfolio can be set up which allows all of the properties within the portfolio to be managed from one place, for example to centrally manage rates and vouchers. [](https://mews-systems.gitbook.io/connector-api/concepts/multi-property#portfolio-access-tokens) Portfolio Access Tokens ------------------------------------------------------------------------------------------------------------------------------ Multi-property functionality is reflected in the API through special **Portfolio Access Tokens**, these are `Access Tokens` that give API clients access to all of the enterprises or properties within scope of the portfolio, rather than just to a single enterprise. ![](https://mews-systems.gitbook.io/connector-api/~gitbook/image?url=https%3A%2F%2F850326323-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LBS6Dpna-dkV2PShmis%252Fuploads%252Fgit-blob-7c6c8fc8306e7abc3dec54f028f6a058e352e6c3%252Fmulti-property1.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=fe44c46a&sv=2) [](https://mews-systems.gitbook.io/connector-api/concepts/multi-property#enterprises) Enterprises ------------------------------------------------------------------------------------------------------ Not all API Operations support Portfolio Access Tokens. For those that do, they have an additional request parameter `EnterpriseId` (singular) or `EnterpriseIds` (plural). This enables you to specify which enterprise or enterprises you want to connect to or act upon, when using the operation. The enterprises specified must be within scope of the Portfolio Access Token you are using. If the operation supports multiple enterprises, for example [Get all payments](https://mews-systems.gitbook.io/connector-api/operations/payments#get-all-payments) , and you use a Portfolio Access Token but do not specify the `EnterpriseIds` parameter, then the operation will connect to or act upon _all_ of the enterprises within scope of the `Access Token`. Some operations, such as [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) , accept Portfolio Access Tokens but only return information for a single enterprise. In this case, you must use the `EnterpriseId` parameter to specify which enterprise you are interested in. If you do not specify the `EnterpriseId` parameter, then the functionality is undefined, or rather it depends on the individual API operation. For example, in the case of [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) , the operation returns information on the 'dummy' enterprise used to identify the portfolio. [](https://mews-systems.gitbook.io/connector-api/concepts/multi-property#chains) Chains -------------------------------------------------------------------------------------------- Independently of portfolios, properties can be grouped into chains. Chains are used to define legal relationships between enterprises, and for sharing certain data such as customer profiles. Some API operations support filtering by `ChainId`, e.g. [Get all companies](https://mews-systems.gitbook.io/connector-api/operations/companies#get-all-companies) and [Get all loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#get-all-loyalty-programs) . When used in combination with a Portfolio Access Token, `ChainId` (singular) or `ChainIds` (plural) can be used to specify which chain or chains you want to connect to or act upon when using the operation, just like with `EnterpriseIds`. If the operation supports multiple chains, and you use a Portfolio Access Token but do not specify the `ChainIds` parameter, then the operation will connect to or act upon _all_ of the chains within scope of the `Access Token`. ![](https://mews-systems.gitbook.io/connector-api/~gitbook/image?url=https%3A%2F%2F850326323-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LBS6Dpna-dkV2PShmis%252Fuploads%252Fgit-blob-4800d34e1b131749f94315d56e29ea89affa5c31%252Fmulti-property2.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=de85a922&sv=2) [](https://mews-systems.gitbook.io/connector-api/concepts/multi-property#faq) FAQ -------------------------------------------------------------------------------------- ### [](https://mews-systems.gitbook.io/connector-api/concepts/multi-property#how-can-i-obtain-a-portfolio-access-token) How can I obtain a Portfolio Access Token? The **Mews Multi-Property** feature is not available for all customers, it depends on system configuration. For more information, please get in touch via [partnersuccess@mews.com](mailto:partnersuccess@mews.com) . ### [](https://mews-systems.gitbook.io/connector-api/concepts/multi-property#how-can-i-tell-if-an-access-token-is-single-enterprise-or-multi-enterprise-in-scope) How can I tell if an Access Token is single enterprise or multi-enterprise in scope? An `Access Token` is an opaque series of random characters. You cannot tell from looking at a token whether it supports a single enterprise or a portfolio of multiple enterprises. ### [](https://mews-systems.gitbook.io/connector-api/concepts/multi-property#how-can-i-tell-if-an-api-operation-supports-portfolio-access-tokens) How can I tell if an API operation supports Portfolio Access Tokens? The description for an API operation specifies if it supports Portfolio Access Tokens, e.g. see [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) . Such operations will normally also have `EnterpriseId` or `EnterpriseIds` as a request parameter. [PreviousConcepts](https://mews-systems.gitbook.io/connector-api/concepts) [NextRestrictions](https://mews-systems.gitbook.io/connector-api/concepts/restrictions) Last updated 10 months ago Was this helpful? --- # Best practices | Connector API This is some advice on best practices for using the API, regardless of your particular use case. Follow this advice for less errors and better performance. * **4xx HTTP status codes** Follow our recommendations on handling each 4xx [response code](https://mews-systems.gitbook.io/connector-api/guidelines/responses#response-codes) . If you receive a 400 response with an 'Invalid {Parameter}' message, one possible explanation is that the resource you are referencing doesn't exist - check with the enterprise for confirmation. * **Webhooks instead of polling** Instead of periodically polling for updates using a 'get' operation, use [Webhooks](https://mews-systems.gitbook.io/connector-api/events) instead and subscribe to updates. If a Webhook for an event is not supported, reach out to us at [partnersuccess@mews.com](mailto:partnersuccess@mews.com) . For more information, see [Ways to communicate](https://mews-systems.gitbook.io/connector-api/events/communicate) . * **Limit use of extents** Limit the amount of extents you use as much as possible. You can see an example of extents in [Get all resources](https://mews-systems.gitbook.io/connector-api/operations/resources#get-all-resources) . An extent represents a related entity that requires lookup into another database table, thus significantly hindering performance. If you need to use multiple extents, instead create a separate call for each individual extent. * **Use pagination** Use [pagination](https://mews-systems.gitbook.io/connector-api/guidelines/pagination) for 'get' operations wherever possible. Responses will be smaller and easier to manage, and you won't hit those [request timeouts](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-timeouts) ! * **Use filtering** Avoid retrieving the same data repetitively. Leverage filtering to retrieve just the subset of data that's relevant to you. Data past the [Editable History Window](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US#EditableHistoryWindow) can't be changed so it doesn't make sense to pull it repeatedly. If there is no support for a filter you'd benefit from, reach out to us at [partnersuccess@mews.com](mailto:partnersuccess@mews.com) with a request to add it. * **Don't query for unchanging data** Querying for relatively static resources adds unnecessary traffic to the API and slows down the user experience. Instead, cache data that doesn't change very often, such as: * resource categories * services * products * accounting categories * business segments * configuration * taxes [PreviousPagination](https://mews-systems.gitbook.io/connector-api/guidelines/pagination) [NextConcepts](https://mews-systems.gitbook.io/connector-api/concepts) Last updated 11 months ago Was this helpful? --- # Restrictions | Connector API An explanation of the algorithms used to support [Set restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#set-restrictions) and [Clear restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#clear-restrictions) . [](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#contents) Contents ---------------------------------------------------------------------------------------------- * [What are restrictions?](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#what-are-restrictions) * [Restrictions in the API](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#restrictions-in-the-api) * [Set restrictions and Clear restrictions](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#set-restrictions-and-clear-restrictions) * [Merging algorithm](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#merging-algorithm) * [Matching conditions](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#matching-conditions) * [Time interval splicing](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#time-interval-splicing) * [Scope of restrictions](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#scope-of-restrictions) [](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#what-are-restrictions) What are restrictions? ------------------------------------------------------------------------------------------------------------------------- Restrictions give **Mews** customers more control over their reservations, by preventing guests from making bookings that meet certain conditions. Restrictions can be applied to rates and space types, to control the way guests can book them. For example: * Use restrictions to implement a promotional rate which applies only to weekend bookings during July and August * Use restrictions to prevent guests from booking a room in a particular space type category (room type) > #### > > [](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#additional-help-on-restrictions) > > Additional help on restrictions > > * [Understanding restrictions in Mews Operations](https://help.mews.com/s/article/Understanding-restrictions-in-Mews-Operations?language=en_US) > > * [How to create restrictions in Mews Operations](https://help.mews.com/s/article/How-to-create-restrictions-in-Mews-Operations?language=en_US) > > * [Search all Help articles related to restrictions](https://help.mews.com/s/global-search/restrictions?language=en_US) > [](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#restrictions-in-the-api) Restrictions in the API ---------------------------------------------------------------------------------------------------------------------------- To retrieve information about restrictions, use [Get all restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#get-all-restrictions) . To add and remove restrictions, use [Set restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#set-restrictions) and [Clear restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#clear-restrictions) respectively. 'How to' use case API Operations How to get service restrictions [Get all restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#get-all-restrictions) How to add service restrictions [Set restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#set-restrictions) How to remove service restrictions [Clear restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#clear-restrictions) > **Restrictions operations:** Older operations [Add restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#add-restrictions) > and [Delete restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#delete-restrictions) > are deprecated. They are replaced by the more efficient [Set restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#set-restrictions) > and [Clear restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#clear-restrictions) > . Refer to the documentation for the individual operations for an explanation of the workings of these operations. Do not mix them, use _Add restrictions_ with _Delete restrictions_, or _Set restrictions_ with _Clear restrictions_. Note that as an API user you can only set and clear your own restrictions, independently of restrictions set within the user interface of **Mews Operations**, or indeed by other API users. [](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#set-restrictions-and-clear-restrictions) Set restrictions and Clear restrictions ------------------------------------------------------------------------------------------------------------------------------------------------------------ When using old API operation [Add restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#add-restrictions) , if consecutive restrictions are sent with the same conditions and exceptions, no attempt is made by the system to merge the duplicate or overlapping restrictions. This means that there can be a large number of restrictions created per service, leading to sub-optimal performance. A quota limit of 150,000 was introduced. However, to mitigate the issue, API users are encouraged to migrate to new operation [Set restrictions](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#set-restrictions) instead. For improved efficiency, [Set restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#set-restrictions) merges multiple similar restrictions into a single restriction. Its sibling operation [Clear restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#clear-restrictions) uses a splicing algorithm to work out how to divide up any existing restrictions to meet the specified time interval. The following sections explain the algorithms used by these operations in more detail. These algorithms only apply to [Set restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#set-restrictions) and [Clear restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#clear-restrictions) . [](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#merging-algorithm) Merging algorithm ---------------------------------------------------------------------------------------------------------------- When using [Set restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#set-restrictions) , if a specified restriction already exists with the same conditions, or if multiple specified restrictions match in all properties but differ in time interval and follow each other chronologically, a merging algorithm is applied to combine them. This reduces the overall number of restrictions and improves system performance. The merging algorithm is as follows: * If the exceptions of the new restriction match the old restriction: * If the new interval is longer than the old one, a new restriction is created joining the two intervals. * If the new interval is shorter, no changes are made. * If the exceptions of the new restriction do _not_ match the old restriction: * If the new interval overlaps the old interval, the old restriction will be [spliced](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#time-interval-splicing) before and after the new interval. Restrictions matching the old restriction are then added at the appropriate interval along with the new restriction. * If the new interval does _not_ overlap the old interval, the new restriction is added as usual. [](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#matching-conditions) Matching conditions -------------------------------------------------------------------------------------------------------------------- The conditions specified in [Set restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#set-restrictions) and [Clear restrictions](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#clear-restrictions) must be met exactly. For example: * A bookable service has two restrictions A and B. Restriction A applies to resource category C1 and rate R1. Restriction B applies to resource category C1 and to all rates. If [Clear restrictions](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#clear-restrictions) is called, specifying a restriction condition of resource category C1 but with no rate specified (this defaults to _all_ rates), then only Restriction B is cleared, not Restriction A. [](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#time-interval-splicing) Time interval splicing -------------------------------------------------------------------------------------------------------------------------- The time interval for a specified restriction does not need to correspond to an existing restriction in the system, instead the API uses a splicing algorithm to work out how to divide up any existing restrictions to meet the specified time interval. For example: * An existing restriction in the system A applies from 5th January to 25th January. As usual, time intervals are inclusive, meaning that the time interval includes both the 5th January and the 25th January. If the [Clear restrictions](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#clear-restrictions) operation is called, specifying a restriction time interval of 10th January to 20th January, i.e. within the original restriction A, then the time interval of restriction A is split into three separate intervals. The original restriction A is deleted, and in its place new restriction B is created for the period of time from 5th January to 9th January inclusive, and new restriction C is created for the period of time from 21st January to 25th January. Thus the period 10th January to 20th January has been cleared, but without affecting other time periods. [](https://mews-systems.gitbook.io/connector-api/concepts/restrictions#scope-of-restrictions) Scope of restrictions ------------------------------------------------------------------------------------------------------------------------ Only restrictions created through the API are affected by these operations, _not_ restrictions created by the user within **Mews Operations**. Similarly, if a user creates a restriction in **Mews Operations**, this will _not_ affect restrictions created through the API. User restrictions and API restrictions are independent. > **Important**: We assume that only one third-party integration manages restrictions for a given enterprise or property. All restrictions set up in an enterprise are created either by the enterprise itself through the **Mews Operation** user interface, or uniquely by a single integration through the API. These two sources can be identified using the `Origin` field in requests and responses to [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) > . [PreviousMulti-property](https://mews-systems.gitbook.io/connector-api/concepts/multi-property) [NextTaxation](https://mews-systems.gitbook.io/connector-api/concepts/taxation) Last updated 6 months ago Was this helpful? --- # Time units | Connector API Bookable Services are booked in terms of integer multiples of standard `time units`. The length of a time unit depends on the particular service and is given by `time unit period`, which can be obtained through [Get all services](https://mews-systems.gitbook.io/connector-api/concepts/time-units#get-all-services) . For example, a service with a time unit period of "Day" can be booked in multiples of days. This is equivalent to booking a hotel room stay for a specified number of days or a specified number of nights. A monthly time unit, i.e. a time unit with time unit period of "Month", starts at midnight on the first day of the month and ends at midnight on the first day of the following month. The service is not assumed to start at the beginning of a time unit, e.g. 00:00 midnight for a "Day", nor end at the end of a time unit, e.g. the following midnight. Instead we define `StartOffset` as the offset from the beginning of the time unit at which the service starts, and `EndOffset` as the offset from the end of the time unit at which the service actually ends - see the illustrations below. Similarly, `OccupancyStartOffset` and `OccupancyEndOffset` define the offsets for which the service is considered occupied. A positive value for `EndOffset` is normal for a nightly stay and implies that the service ends on the following morning. A negative value for `EndOffset` can be used to specify a daytime service that ends before the end of the day. #### [](https://mews-systems.gitbook.io/connector-api/concepts/time-units#figure-1-illustration-of-a-nightly-service) Figure 1: Illustration of a nightly service ![](https://mews-systems.gitbook.io/connector-api/~gitbook/image?url=https%3A%2F%2F850326323-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LBS6Dpna-dkV2PShmis%252Fuploads%252Fgit-blob-747ab84a9aef8ba33ac61b71eaf4295f08997852%252Ftimeunits-connector-night.png%3Falt%3Dmedia%26token%3D26b967be-e3bf-4764-aa19-1295a4f60b33&width=768&dpr=4&quality=100&sign=b19629fb&sv=2) #### [](https://mews-systems.gitbook.io/connector-api/concepts/time-units#figure-2-illustration-of-a-daytime-service) Figure 2: Illustration of a daytime service ![](https://mews-systems.gitbook.io/connector-api/~gitbook/image?url=https%3A%2F%2F850326323-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LBS6Dpna-dkV2PShmis%252Fuploads%252Fgit-blob-f91193e6a2f2fa762d460863aab86802cfcacb69%252Ftimeunits-connector-day.png%3Falt%3Dmedia%26token%3D12c8aa05-0386-46aa-9627-4bb16e649a83&width=768&dpr=4&quality=100&sign=9a5fa778&sv=2) [PreviousTaxation](https://mews-systems.gitbook.io/connector-api/concepts/taxation) [NextUse cases](https://mews-systems.gitbook.io/connector-api/use-cases) Last updated 1 year ago Was this helpful? --- # Use cases | Connector API This section describes how to use the **Mews Connector API** in order to implement well-known scenarios. Even if you are integrating a different type of system, it serves as a good starting point for API usage patterns and practices. [](https://mews-systems.gitbook.io/connector-api/use-cases#how-to-use-cases) 'How to' use cases ---------------------------------------------------------------------------------------------------- * ['How to' use cases](https://mews-systems.gitbook.io/connector-api/use-cases/how-to) [](https://mews-systems.gitbook.io/connector-api/use-cases#business-use-cases) Business use cases ------------------------------------------------------------------------------------------------------ * [Accounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) * [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) * [Customer management](https://mews-systems.gitbook.io/connector-api/use-cases/customer-management) * [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) * [Guest technology](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology) * [Housekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) * [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) * [Point of sale](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) * [Reputation management](https://mews-systems.gitbook.io/connector-api/use-cases/reputation-management) * [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) * [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) [](https://mews-systems.gitbook.io/connector-api/use-cases#functional-use-cases) Functional use cases ---------------------------------------------------------------------------------------------------------- * [Data export](https://mews-systems.gitbook.io/connector-api/use-cases/data-export) * [Device integration](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration) * [Customer messaging](https://mews-systems.gitbook.io/connector-api/use-cases/messaging) * [Payments - Mews Payment Terminals](https://mews-systems.gitbook.io/connector-api/use-cases/mews-terminals) * [Payments - Payment automation](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation) [PreviousTime units](https://mews-systems.gitbook.io/connector-api/concepts/time-units) [Next'How to' use cases](https://mews-systems.gitbook.io/connector-api/use-cases/how-to) Last updated 11 months ago Was this helpful? --- # Accounting | Connector API Accounting systems are created to record and process accounting transactions for internal and external review and auditing. Accounting systems include core modules such as accounts payable, accounts receivable, general ledger, and billing. Additional non-core modules could include reconciliation, inventory, a document approval system, expense tracking, reporting and electronic payment processing for added value. [](https://mews-systems.gitbook.io/connector-api/use-cases/accounting#initial-configuration) Initial configuration ----------------------------------------------------------------------------------------------------------------------- An Accounting integration must first retrieve all configured accounting categories, i.e. all the IDs and codes required to ensure that revenue, payments and costs are correctly assigned to their designated accounting categories. Accounting categories should be created by the property in co-operation with their accountants. 'How to' use case API Operations How to get accounting categories [Get all accounting categories](https://mews-systems.gitbook.io/connector-api/operations/accountingcategories#get-all-accounting-categories) To ensure accuracy, only data that is no longer editable by the property can be retrieved by the integration. This is determined by a period of time called the Editable History Window, which is the length of time after a bill or invoice has been closed during which it can still be amended. In fact there are two values, one for Accounting purposes and one for Operational purposes, so take the longest of the two values to ensure the data cannot be changed. Use API operation [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) to fetch the configuration for your enterprise or property. This will include two fields representing the two windows, `AccountingEditableHistoryInterval` and `OperationalEditableHistoryInterval`. 'How to' use case API Operations How to get editable history window [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) > **Editable History Window**: For a full description and links to further information, see the [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) > . > **Debtor tracking**: If debtor tracking is to be done in the external system instead of Mews, the property must have the Accounting configuration option "Receivable tracking enabled" unchecked in Mews. See [Receivable tracking - enabled or disabled?](https://help.mews.com/s/article/Receivable-tracking-enabled-or-disabled?language=en_US) > . [](https://mews-systems.gitbook.io/connector-api/use-cases/accounting#periodic-update) Periodic update ----------------------------------------------------------------------------------------------------------- An Accounting integration should fetch accounting items and outlet items at regular intervals, at least daily. In both cases, if `Currency` is specified, the cost of the items will be converted to that currency. The integration should also fetch all bills and invoices that must be paid and reconciled within the accounting software. These can be filtered by a specific customer, by date of creation, consumption or payment, or, in the case of invoices, by due date. 'How to' use case API Operations How to get accounting items consumed over a period [Get all payments](https://mews-systems.gitbook.io/connector-api/operations/payments#get-all-payments) , [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) How to get order items consumed over a period [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) How to get payment items paid over a period [Get all payments](https://mews-systems.gitbook.io/connector-api/operations/payments#get-all-payments) How to get outlet items consumed over a period [Get all outlet items](https://mews-systems.gitbook.io/connector-api/operations/outletitems#get-all-outlet-items) How to get bills and invoices [Get all bills](https://mews-systems.gitbook.io/connector-api/operations/bills#get-all-bills) [](https://mews-systems.gitbook.io/connector-api/use-cases/accounting#accounting-items-and-reservations) Accounting items and reservations ----------------------------------------------------------------------------------------------------------------------------------------------- It is important to understand that in Mews, accounting items are posted directly to the guest profile instead of being attached to a specific reservation. Products created under the 'Stay' service (i.e. accommodation) are used to create stay packages, while products related to any other service are used for all other postings. Only Stay products can be related back to a specific reservation, by matching their `OrderId` with the unique identifier of the relevant reservation. If products are created under any other service configured at the property, they are not related to the reservation. To retrieve a complete list of revenue items for a specific reservation, use [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) and pass the Reservation ID as parameter `ServiceOrderId` (A reservation is a type of Service Order). 'How to' use case API Operations How to get a list of revenue items for a reservation [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) > **Accounting item states**: Accounting items will always be assigned one of four [accounting item states](https://mews-systems.gitbook.io/connector-api/operations/accountingitems#accounting-item-state) > (`Open`, `Closed`, `Inactive`, `Canceled`). [](https://mews-systems.gitbook.io/connector-api/use-cases/accounting#working-with-rebates) Working with rebates --------------------------------------------------------------------------------------------------------------------- If an accounting item is a rebate item, then the ID for the original order item which is rebated will be stored in the item data. Specifically, an [Order item](https://mews-systems.gitbook.io/connector-api/operations/orderitems#order-item) with `Data` `Discriminator` set to "Rebate" will have `Data` `Rebate` set to the value of the `RebatedItemId`. You can then use [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) with the `OrderItemIds` filter parameter set to this ID to fetch the details about the item. Note that a rebate item can rebate another rebate item, so it may be necessary to recursively call [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) to find the original order item in the chain. 'How to' use case API Operations How to find the original order item for a rebate item [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) > **How can I tell if an entire Bill has been rebated?** Rebates are on an individual item-by-item basis, so if every individual order item on a Bill has been rebated then this is equivalent to the entire Bill being rebated. [](https://mews-systems.gitbook.io/connector-api/use-cases/accounting#testing-your-integration) Testing your integration ----------------------------------------------------------------------------------------------------------------------------- Please follow our general [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) for testing integrations. When testing an Accounting integration, you can cross-check whether you are correctly requesting all of the accounting information via the API by matching your data with the Mews Accounting Report. For reconciliation of all bills and invoices, you can use the Bills and Invoices Report. You can easily create export schedules to a specific target and in a desired format for both of these reports. Before assisting any new enterprise client with connecting to your accounting integration, it's recommended that you check that they have first completed their configuration, to ensure a smoother onboarding experience. [](https://mews-systems.gitbook.io/connector-api/use-cases/accounting#additional-help-for-working-with-the-demo-environment) Additional help for working with the demo environment --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > **Help Guides**: > > * [Creating an accounting category](https://help.mews.com/s/article/create-an-accounting-category?language=en_US) > > * [Set up a bookable service](https://help.mews.com/s/article/set-up-a-bookable-service?language=en_US) > > * [The Accounting Report](https://help.mews.com/s/article/accounting-report?language=en_US) > > * [The Bills and Invoices Report](https://help.mews.com/s/article/bills-and-invoices-report?language=en_US) > > * [Scheduling report exports](https://help.mews.com/s/article/schedule-report-exports?language=en_US) > > * [How can I connect my accounting integration?](https://help.mews.com/s/article/how-can-i-connect-my-accounting-integration?language=en_US) > [Previous'How to' use cases](https://mews-systems.gitbook.io/connector-api/use-cases/how-to) [NextCustomer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) Last updated 11 months ago Was this helpful? --- # Customer management | Connector API Customer management integrations pull live information about reservations, customers, products and services, for specified time periods. Such systems allow properties to manage the entire customer journey, from automating targeted marketing and driving sales to guest communication and engagement. [](https://mews-systems.gitbook.io/connector-api/use-cases/customer-management#retrieving-new-and-modified-reservations) Retrieving new and modified reservations ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Although new profiles can be created in Mews without a reservation, communication with a customer typically begins the moment a new reservation is created. Integration partners can listen for newly-created reservations using [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) (`Reservation` event). A new event occurs with every change to the reservation state, meaning partners are informed of any change that might lead to communication from their side, e.g. sending a custom welcome message or a post-stay survey. Reservation events contain the unique identifiers for affected reservations, these can then be used as the filter in a call to [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) to retrieve the required information about the customer and their stay. You can test your Webhooks or WebSockets integration by creating new reservations in Mews, which will trigger these notification events. If Webhooks or WebSockets cannot be configured, reservation information can instead be requested using [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) with specified [Reservation states](https://mews-systems.gitbook.io/connector-api/operations/reservations#reservation-state) and [Reservation time filters](https://mews-systems.gitbook.io/connector-api/operations/reservations#reservation-time-filter) . For example, using the `Updated` time filter will return all reservations modified during the time interval specified in the request. 'How to' use case API Operations How to listen for changes to reservations [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) (`Reservation` event) How to get reservation and customer details [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) How to get reservations updated over a time period [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) [](https://mews-systems.gitbook.io/connector-api/use-cases/customer-management#offering-additional-products-or-services) Offering additional products or services ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Each Mews property creates a unique set of services and related products which they can offer to their guests. For details on how to retrieve product information from Mews, how to search for customers, and how to correctly post orders to their profile, see the [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) use case. [](https://mews-systems.gitbook.io/connector-api/use-cases/customer-management#testing-your-integration) Testing your integration -------------------------------------------------------------------------------------------------------------------------------------- Please ensure you follow our general [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) for testing integrations. [](https://mews-systems.gitbook.io/connector-api/use-cases/customer-management#additional-help-for-working-with-the-demo-environment) Additional help for working with the demo environment ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ > **Help Guides**: > > * [How to create a reservation](https://help.mews.com/s/article/create-a-reservation?language=en_US) > > * [How to check in a reservation](https://help.mews.com/s/article/check-in-a-reservation?language=en_US) > [PreviousCustomer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) [NextCustomer messaging](https://mews-systems.gitbook.io/connector-api/use-cases/messaging) Last updated 11 months ago Was this helpful? --- # Customer messaging | Connector API Enable guests to send messages to the property and receive replies, by connecting your chatbot or instant messaging app into the customer messaging system of **Mews Operations**. You can do this through the API with the [Messages](https://mews-systems.gitbook.io/connector-api/operations#messages) collection of API operations, in conjunction with the `MessageAdded` [General Webhook](https://mews-systems.gitbook.io/connector-api/events/wh-general) . Message threads or conversations are initiated by the customer (the guest). The customer messages are then sent through to the property, where employees are notified and can quickly respond with a message reply added to the thread. The typical workflow is as follows: 1. [Customer creates a message within your app](https://mews-systems.gitbook.io/connector-api/use-cases/messaging#1-customer-creates-a-message-within-your-app) 2. [Your app creates a new message thread in Mews](https://mews-systems.gitbook.io/connector-api/use-cases/messaging#2-your-app-creates-a-new-message-thread-in-mews) 3. [Your app listens for MessageAdded events](https://mews-systems.gitbook.io/connector-api/use-cases/messaging#3-your-app-listens-for-messageadded-events) 4. [Continue the conversation!](https://mews-systems.gitbook.io/connector-api/use-cases/messaging#4-continue-the-conversation) [](https://mews-systems.gitbook.io/connector-api/use-cases/messaging#id-1.-customer-creates-a-message-within-your-app) 1\. Customer creates a message within your app -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The customer (the guest) creates an instant message within your app, directed to the property. > **Penelope:** `"Hi! I just wanted to let you know I will be arriving late tonight"` [](https://mews-systems.gitbook.io/connector-api/use-cases/messaging#id-2.-your-app-creates-a-new-message-thread-in-mews) 2\. Your app creates a new message thread in Mews -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Your app creates a new message thread in Mews and adds the customer message to the thread. Use [Add message thread](https://mews-systems.gitbook.io/connector-api/operations/messagethreads#add-message-thread) to create a new message thread, then [Add messages](https://mews-systems.gitbook.io/connector-api/operations/messages#add-messages) to create a new message within the thread. 'How to' use case API Operations How to create a new message thread [Add message thread](https://mews-systems.gitbook.io/connector-api/operations/messagethreads#add-message-thread) How to create a new message within a thread [Add messages](https://mews-systems.gitbook.io/connector-api/operations/messages#add-messages) [](https://mews-systems.gitbook.io/connector-api/use-cases/messaging#id-3.-your-app-listens-for-messageadded-events) 3\. Your app listens for MessageAdded events ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- To get message responses in near real time, listen to the `MessageAdded` [General Webhook](https://mews-systems.gitbook.io/connector-api/events/wh-general) event. When a `MessageAdded` event is received, the event will contain the ID of the newly added message and the ID of the message thread or conversation to which the message belongs. Messages sent in reply by the property have the Sender property set to "Enterprise" (in the API, we use term 'enterprise' rather than 'property'). The text of the message can be passed on to the customer through your app. See [Webhooks](https://mews-systems.gitbook.io/connector-api/events) for details of how to set up Webhooks. 'How to' use case API Operations How to listen for new customer messages [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) (`MessageAdded` event) > **Property:** `"Hello Ms Penelope! Thank you for contacting us. What time do you expect to arrive?"` [](https://mews-systems.gitbook.io/connector-api/use-cases/messaging#id-4.-continue-the-conversation) 4\. Continue the conversation! ----------------------------------------------------------------------------------------------------------------------------------------- You can pass messages back and forth, as above, until the conversation is resolved. And if you need to search or fetch your messages or your message threads, you have the [Get all messages](https://mews-systems.gitbook.io/connector-api/operations/messages#get-all-messages) and [Get all message threads](https://mews-systems.gitbook.io/connector-api/operations/messagethreads#get-all-message-threads) API operations. 'How to' use case API Operations How to get messages for your message threads [Get all messages](https://mews-systems.gitbook.io/connector-api/operations/messages#get-all-messages) How to get your message threads [Get all message threads](https://mews-systems.gitbook.io/connector-api/operations/messagethreads#get-all-message-threads) > **Penelope:** `"Around 11pm. Please hold my room, thank you."` **Property:** `"Your room will be ready for you, travel safely and we look forward to welcoming you around 11pm."` [](https://mews-systems.gitbook.io/connector-api/use-cases/messaging#testing-your-integration) Testing your integration ---------------------------------------------------------------------------------------------------------------------------- Please refer to our general [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) for testing integrations. [](https://mews-systems.gitbook.io/connector-api/use-cases/messaging#further-information) Further information ------------------------------------------------------------------------------------------------------------------ > **Help Guides**: > > * [How to read and reply to messages](https://help.mews.com/s/article/read-and-reply-to-messages?language=en_US) > [PreviousCustomer management](https://mews-systems.gitbook.io/connector-api/use-cases/customer-management) [NextData export](https://mews-systems.gitbook.io/connector-api/use-cases/data-export) Last updated 11 months ago Was this helpful? --- # Customer loyalty | Connector API Loyalty scheme providers can use the **Mews Connector API** to synchronize their loyalty programs with **Mews Operations**. Hotel staff can then easily access a guest's membership status, including loyalty tier such as "Gold member", through the guest profile within the Mews system. > #### > > [](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty#loyalty-data-model) > > Loyalty data model > > The data model for Loyalty consists of three main entities: > > * **Loyalty Program** This is the main loyalty scheme or program. A guest can be a member of multiple programs. > > * **Loyalty Tier** You can optionally define tiers or levels of membership for your program. > > * **Loyalty Membership** A Loyalty Membership describes the relationship between a customer or guest and a loyalty program. This includes reward points, loyalty tier and membership expiration date. > [](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty#chains) Chains -------------------------------------------------------------------------------------- Loyalty programs are set up in Mews at the above-property chain level. However, this does not prevent individual properties (called _Enterprises_ in Mews) from having loyalty programs, because a property by default is in a chain of one. > #### > > [](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty#where-can-i-obtain-the-chain-identifier) > > Where can I obtain the Chain identifier? > > You can obtain the Chain identifier for an enterprise or property using [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) > . [](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty#set-up-loyalty-programs) Set up loyalty programs ------------------------------------------------------------------------------------------------------------------------ Use [Add loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#add-loyalty-programs) to create your loyalty programs in Mews. If using a normal, single enterprise Access Token, the programs will be created for the chain corresponding to the enterprise within scope of the Access Token. If using a multi-property Portfolio Access Token, you must specify the `ChainId`. The programs will then be created for the specified chain. To create a program, you must specify a program name, program code (used to match the loyalty on bookings such as those coming in to Mews from the [Mews Channel Manager API](https://mews-systems.gitbook.io/channel-manager-api) ), type of program, and subscription model (`Free` or `Paid`). To see what loyalty programs are already set up, use [Get all loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#get-all-loyalty-programs) , which can be called with various filter parameters, depending on your requirements. 'How to' use case API Operations How to add a Loyalty Program [Add loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#add-loyalty-programs) How to get a list of Loyalty Programs [Get all loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#get-all-loyalty-programs) How to get the Chain identifier for a property [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) > #### > > [](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty#how-can-i-validate-the-loyalty-programs-setup) > > How can I validate the Loyalty Programs setup? > > With access to **Mews Operations**, you can go to the Loyalty section of the Customer Profile and manually add a customer to a program. The available programs should reflect what you have configured through the API. For more information, see these articles in the [Mews Help Center](https://help.mews.com/) > : > > * [Understanding the Loyalty section in Mews Operations](https://help.mews.com/s/article/Understanding-the-Loyalty-section-in-Mews-Operations) > > * [Managing the Loyalty section in Mews Operations](https://help.mews.com/s/article/Managing-the-Loyalty-section-in-Mews-Operations) > [](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty#maintain-your-loyalty-programs) Maintain your loyalty programs -------------------------------------------------------------------------------------------------------------------------------------- To make changes to existing loyalty programs, use [Update loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#update-loyalty-programs) . To delete unwanted loyalty programs, use [Delete loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#delete-loyalty-programs) . 'How to' use case API Operations How to update a Loyalty Program [Update loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#update-loyalty-programs) How to delete a Loyalty Program [Delete loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#delete-loyalty-programs) [](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty#set-up-loyalty-tiers) Set up loyalty tiers ------------------------------------------------------------------------------------------------------------------ If any of the loyalty programs use tiers, set up those tiers and link them to the programs, using [Add loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#add-loyalty-tiers) . To see what loyalty tiers are already set up, use [Get all loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#get-all-loyalty-tiers) , which can be called with various filter parameters, depending on your requirements. To make changes to existing loyalty tiers, use [Update loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#update-loyalty-tiers) . To delete unwanted loyalty tiers, use [Delete loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#delete-loyalty-tiers) . 'How to' use case API Operations How to add a Loyalty Tier [Add loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#add-loyalty-tiers) How to get a list of Loyalty Tiers [Get all loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#get-all-loyalty-tiers) How to update a Loyalty Tier [Update loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#update-loyalty-tiers) How to delete a Loyalty Tier [Delete loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#delete-loyalty-tiers) [](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty#add-guests-to-loyalty-programs) Add guests to loyalty programs -------------------------------------------------------------------------------------------------------------------------------------- Loyalty Memberships are used to connect guests (called _Customers_ in Mews) with loyalty programs. To connect a guest or customer to a loyalty program, use [Add loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#add-loyalty-memberships) . Specify the identifier of the loyalty program, the identifier of the customer account, and optionally you can specify their reward points, a membership expiration date, a URL to an entry in your loyalty system, a loyalty tier that the customer belongs to, and/or the state of their membership, e.g. `Pending`. If the customer is a member of more than one loyalty program within scope of the chain, specify which one is the primary program against which points should be allocated, using the `isPrimary` JSON property. To fetch a list of guest memberships, use [Get all loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#get-all-loyalty-memberships) , which can be called with various filter parameters. 'How to' use case API Operations How to add a Loyalty Membership [Add loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#add-loyalty-memberships) How to get a list of Loyalty Memberships [Get all loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#get-all-loyalty-memberships) [](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty#maintain-your-guest-memberships) Maintain your guest memberships ---------------------------------------------------------------------------------------------------------------------------------------- To make changes to guest loyalty memberships, use [Update loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#update-loyalty-memberships) . To remove guest loyalty memberships, use [Delete loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#delete-loyalty-memberships) . 'How to' use case API Operations How to update a Loyalty Membership [Update loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#update-loyalty-memberships) How to delete a Loyalty Membership [Delete loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#delete-loyalty-memberships) [](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty#testing-your-integration) Testing your integration -------------------------------------------------------------------------------------------------------------------------- Ensure you follow our general [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) for testing integrations. For additional help when working with the demo environment, there is a range of helpful articles in the [Mews Help Center](https://help.mews.com/s/?language=en_US) . These are available in a number of languages. The following articles may be of interest: * [Understanding the Loyalty section in Mews Operations](https://help.mews.com/s/article/Understanding-the-Loyalty-section-in-Mews-Operations) * [Managing the Loyalty section in Mews Operations](https://help.mews.com/s/article/Managing-the-Loyalty-section-in-Mews-Operations) [PreviousAccounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) [NextCustomer management](https://mews-systems.gitbook.io/connector-api/use-cases/customer-management) Last updated 11 months ago Was this helpful? --- # Data export | Connector API The _Data export_ feature of the **Mews Connector API** provides a streamlined method for retrieving bulk data. This feature is designed for users who require access to a substantial amount of data, such as [Order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#order-item) , without the hassle of making multiple paginated requests subject to timeouts and other constraints. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/data-export#user-scenarios) User scenarios * You are a Mews partner onboarding a new property and you need an initial data sync * You are a Mews Multi-Property user and want to retrieve data shared across multiple properties * You are using a newly added API operation and are loading data for the first time * You wish to perform a cross-data sanity check ### [](https://mews-systems.gitbook.io/connector-api/use-cases/data-export#user-benefits) User benefits * Streamlined bulk data export process * Reduced API request complexity and potential timeouts * Improved scalability for large-scale data retrieval * Faster property onboarding process * Potential for future expansion to support further data entities > #### > > [](https://mews-systems.gitbook.io/connector-api/use-cases/data-export#restricted) > > Restricted! > > This feature is currently under beta test and is subject to change. If you would like to take advantage of the feature, contact us via [partnersuccess@mews.com](mailto:partnersuccess@mews.com) > . [](https://mews-systems.gitbook.io/connector-api/use-cases/data-export#initiate-the-export) Initiate the export -------------------------------------------------------------------------------------------------------------------- To initiate a bulk data export, use the [Add export](https://mews-systems.gitbook.io/connector-api/operations/exports#add-export) operation, specifying the data _Entity type_, e.g. `OrderItem`. The operation returns an [Export](https://mews-systems.gitbook.io/connector-api/operations/exports#export) object containing the Export `Id` to use in the next step. If there is already an export pending, the operation returns a 400 HTTP error code. 'How to' use case API Operations How to create a new bulk data export [Add export](https://mews-systems.gitbook.io/connector-api/operations/exports#add-export) [](https://mews-systems.gitbook.io/connector-api/use-cases/data-export#check-export-status) Check export status -------------------------------------------------------------------------------------------------------------------- To monitor the progress of the export and retrieve the exported data, use the [Get all exports](https://mews-systems.gitbook.io/connector-api/operations/exports#get-all-exports) operation. This operation returns details of exports for the `ExportIds` you specify, including their status. You can repeatedly check the status of an export while its status is `Pending` or `Processing`, for example every 5 minutes. 'How to' use case API Operations How to check on data export progress [Get all exports](https://mews-systems.gitbook.io/connector-api/operations/exports#get-all-exports) [](https://mews-systems.gitbook.io/connector-api/use-cases/data-export#download-exported-data) Download exported data -------------------------------------------------------------------------------------------------------------------------- Once the export status changes to `Success`, you can download the exported data from the provided [file URLs](https://mews-systems.gitbook.io/connector-api/operations/exports#exported-file) . For example: Copy { "Exports": [\ {\ "Id": "3fa85f64-5717-4562-b3fd-2c963f66afa6",\ "Status": "Success",\ "EntityType": "OrderItem",\ "ExpiresUtc": "2023-10-26T11:42:28Z",\ "Files": [\ {\ "Url": "https://example.com/exports/3fa85f64-5717-4562-b3fd-2c963f66afa6-1.jsonl?example=signature",\ "SizeInBytes": 1215279\ },\ {\ "Url": "https://example.com/exports/3fa85f64-5717-4562-b3fd-2c963f66afa6-2.jsonl?example=signature",\ "SizeInBytes": 1398362\ }\ ]\ },\ ] } > **Multiple files:** Note the data export may consist of multiple files. [](https://mews-systems.gitbook.io/connector-api/use-cases/data-export#frequently-asked-questions) Frequently Asked Questions ---------------------------------------------------------------------------------------------------------------------------------- ### [](https://mews-systems.gitbook.io/connector-api/use-cases/data-export#will-the-supported-entity-types-be-extended-in-future) Will the supported entity types be extended in future? Depending on user demand, the **Mews Connector API** may be expanded to support additional data entities for bulk export. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/data-export#how-often-should-i-check-for-updates) How often should I check for updates? Export duration can vary enormously, but checking status every 5 minutes is a reasonable frequency. The current mechanism is considered a trial which may be enhanced in future. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/data-export#can-i-export-data-from-multiple-enterprises-in-one-request) Can I export data from multiple enterprises in one request? Yes, you can use a Portfolio Access Token to request data from multiple enterprises. Doing so will generate an export of data for all enterprises within scope of the Access Token. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/data-export#for-how-long-are-export-files-available-to-download) For how long are export files available to download? Export files are available to download for a limited period, typically 1 week. The expiry time is specified by `ExpiresUtc` in the [Export](https://mews-systems.gitbook.io/connector-api/operations/exports#export) object. [PreviousCustomer messaging](https://mews-systems.gitbook.io/connector-api/use-cases/messaging) [NextDevice integration](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration) Last updated 2 years ago Was this helpful? --- # Guest technology | Connector API Guest technology covers a range of use cases related to guest technology, especially in-room technology, such as telephones, TV and entertainment systems, room controls and internet access. A typical use case involves posting charges for in-room telephone usage. [](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology#setup) Setup --------------------------------------------------------------------------------------------- Firstly, use [Get all services](https://mews-systems.gitbook.io/connector-api/operations/services#get-all-services) to retrieve all services the property has configured in Mews. Once all services are retrieved, you can select the service against which you would like charges to be posted. To retrieve the list of configured accounting categories or accounting codes, use [Get all accounting categories](https://mews-systems.gitbook.io/connector-api/operations/accountingcategories#get-all-accounting-categories) . This is important because a hotel may, for example, prefer to have charges for international phone calls reported with a different accounting category than for domestic phone calls. 'How to' use case API Operations How to get the list of property services [Get all services](https://mews-systems.gitbook.io/connector-api/operations/services#get-all-services) How to get the list of accounting categories [Get all accounting categories](https://mews-systems.gitbook.io/connector-api/operations/accountingcategories#get-all-accounting-categories) [](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology#checked-in-status) Checked-in status --------------------------------------------------------------------------------------------------------------------- Guest technology integrations typically require information on changes to [reservation state](https://mews-systems.gitbook.io/connector-api/operations/reservations#reservation-state) , especially when a reservation is checked-in and checked-out. Rather than polling the API for state changes, it is better to subscribe to notification events using [Webhooks](https://mews-systems.gitbook.io/connector-api/events) or [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) . Both methods support changes to reservations. Don't know which one to use? See [Ways to communicate](https://github.com/MewsSystems/gitbook-connector-api/blob/master/guidelines/communicate.md) . Once a reservation update event is received, use the reservation ID in a [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) request to retrieve information about the reservation and customer. > **No Post:** The customer classification `Cashlist` is used when charges cannot be sent to the customer bill. This is commonly known as ‘No Post’. 'How to' use case API Operations How to listen for changes to reservations [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) (`Reservation` event) How to get reservation and customer details [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) [](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology#charging-checked-in-customers) Charging checked-in customers --------------------------------------------------------------------------------------------------------------------------------------------- Once the unique identifier of the customer to be charged is obtained, the items can be posted onto their billing tab using the [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) operation. When using [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) , specify parameter `LinkedReservationId` in order to link the order to a guest reservation. This will greatly assist the property when using billing automation. 'How to' use case API Operations How to post an order item to a guest profile [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) How to link an order to a reservation [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) (use `LinkedReservationId`) [](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology#testing-your-integration) Testing your integration ----------------------------------------------------------------------------------------------------------------------------------- Please ensure you follow our general [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) for testing integrations. To confirm you are relating any product that is not configured in Mews with the correct accounting category, you can review the [Accounting Report](https://help.mews.com/s/article/accounting-report?language=en_US) . If done correctly, the product you've posted will appear under the relevant accounting category in the Revenue section of the report. [](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology#additional-help-for-working-with-the-demo-environment) Additional help for working with the demo environment --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > **Help Guides**: > > * [Understanding services](https://help.mews.com/s/article/understanding-services?language=en_US) > > * [Create or delete a product](https://help.mews.com/s/article/create-or-delete-a-product?language=en_US) > > * [Creating an accounting category](https://help.mews.com/s/article/create-an-accounting-category?language=en_US) > [PreviousEvents](https://mews-systems.gitbook.io/connector-api/use-cases/events) [NextHousekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) Last updated 8 months ago Was this helpful? --- # Device integration | Connector API Device integration is concerned with integrating with systems or devices installed 'on premise' at the property, such as printers, key encoders, or any third party system installed at the local level rather than in the cloud. Such systems are referred to as `devices` in Mews, regardless of type, and Mews uses `device commands` to communicate with them. When a relevant action happens within the Mews Hospitality Cloud, a device command is generated and put onto the device command queue. Using the API, you can pull the commands from the queue, process them as necessary and then mark them as processed. Of course, since many of the actions with devices happen in real time, you should in many cases use this in combination with [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) to avoid polling for new commands. Whenever a relevant command is created, you will receive a notification about such an event via the configured WebSocket. For more information on choosing the right option, see [Ways to communicate](https://github.com/MewsSystems/gitbook-connector-api/blob/master/guidelines/communicate.md) . 'How to' use case API Operations How to listen for new device commands [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) [](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration#adding-a-new-device) Adding a new device --------------------------------------------------------------------------------------------------------------------------- Device integrations will require two integrations to be added to a property's **Marketplace** subscriptions. One is the generic device integration, used for creating the device in Mews. The other is your integration, where the created device must be added under the **Connected devices** section in the integration settings, so that your system can begin receiving WebSocket notifications of newly created device commands for the selected devices. See [Testing your integration](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration#testing-your-integration) below for how to create the devices and link them to your integration. > **WebSockets and device changes:** If using WebSockets, when a new device has been created in Mews and linked to your integration, or removed from your integration, you should disconnect and reconnect to the WebSocket in order to receive WebSocket events for the newly added devices. Currently there is no automatic notification of this, so the property must inform you of any changes to their device set-up. [](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration#retrieving-commands) Retrieving commands --------------------------------------------------------------------------------------------------------------------------- Using [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) , first subscribe your application to receive `DeviceCommand` events and connect to the WebSockets endpoint. Once the connection has been established, you will receive notification of all `DeviceCommand` events in real time. When you get the `DeviceCommand` event notification, you can fetch details of the command using [Get all commands by ids](https://mews-systems.gitbook.io/connector-api/operations/commands#get-all-commands-by-ids) . If your application re-connects using WebSockets, or was offline for any reason and for any length of time, you should use the [Get all commands](https://mews-systems.gitbook.io/connector-api/operations/commands#get-all-commands) operation to retrieve all pending commands that were in the queue while your application was offline. This is to ensure that no commands in the queue remain unprocessed. 'How to' use case API Operations How to listen for new device commands [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) How to get details of a device command [Get all commands by ids](https://mews-systems.gitbook.io/connector-api/operations/commands#get-all-commands-by-ids) How to get all unprocessed device commands [Get all commands](https://mews-systems.gitbook.io/connector-api/operations/commands#get-all-commands) [](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration#processing-commands) Processing commands --------------------------------------------------------------------------------------------------------------------------- Once your application has successfully processed the device command, you should update the status of the command to `Processed` (or other state, if the command was _not_ successfully processed) using [Update command](https://mews-systems.gitbook.io/connector-api/operations/commands#update-command) . 'How to' use case API Operations How to update the state of a device command [Update command](https://mews-systems.gitbook.io/connector-api/operations/commands#update-command) [](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration#types-of-device-command) Types of device command ----------------------------------------------------------------------------------------------------------------------------------- The [device command data](https://mews-systems.gitbook.io/connector-api/operations/commands#command-data) depends on the [device type](https://mews-systems.gitbook.io/connector-api/operations/devices#device-type) . Mews supports several device types, including Printer, Payment Terminal, Passport Scanner, Fiscal Machine, and Key Cutter. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration#fiscal-machine-commands) Fiscal Machine commands For Fiscal Machines (whether a virtual or a physical one), you will receive a command containing [Fiscal machine command data](https://mews-systems.gitbook.io/connector-api/operations/commands#fiscal-machine-command-data) . This includes all data of the related [Bill](https://mews-systems.gitbook.io/connector-api/operations/bills#bill) , including all the payments and revenue items in the form of an [Accounting item](https://mews-systems.gitbook.io/connector-api/operations/accountingitems#accounting-item) . > **Sending fiscal codes:** Note that currently, there is no way to send fiscal codes generated by the Fiscal Machine back to Mews. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration#key-cutter-commands) Key Cutter commands For Key Cutters, you will receive a command containing [Key cutter command data](https://mews-systems.gitbook.io/connector-api/operations/commands#key-cutter-command-data) . You can then use this information to encode a physical key card. If your solution includes both physical keys and mobile or other forms of keys, you can also use the same information to send the key or door code to the guest. [](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration#testing-your-integration) Testing your integration ------------------------------------------------------------------------------------------------------------------------------------- Ensure you follow our general [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) for testing integrations. In addition to this, the following is specific to device integrations: To be able to use your integration, an additional step of configuring the device and connecting it to the relevant integration (and therefore the API `Access Token`) is required. This is done through the following steps: 1. In **Mews Operations**, open the main menu in the top left corner, scroll down and click on **Marketplace**. 2. Depending on the type of device you are connecting, click on either the Facility management category (Key Cutter integration, Passport Scanner integration, Printer integration) or Legal environment category (Fiscal Machine integration). 3. Once you have found the correct device integration, click **See more** followed by **Connect** to add this device integration to your Marketplace subscription. 4. Go into the integrations settings page and complete the required fields (if any), then click on the device type on the left side of the screen (e.g. **Key cutters**) and then the "+" button to add and configure any required fields of the device, e.g. Identifier. Be sure to save all changes. 5. Go back to your integration found in the **My subscriptions** section of the Marketplace and click on the **Settings** found on the right side of the integration listing. 6. Once inside the integration settings page, you will see a drop down menu titled **Connected devices**. Select your newly created device from that list and click **Save**, then restart your WebSocket connection. This is the same process that will be required when you assist any mutual customer with onboarding and configuration of your solution. For a full overview of device commands and their states, you can check the [device commands queue](https://help.mews.com/s/article/device-commands-queue?language=en_US) in Mews. If you are returning an unexpected error indicating there is an issue with the Data JSON, please read [this article](https://help.mews.com/s/article/data-json-incorrect-or-unsupported-device?language=en_US) to understand what this indicates, based on the type of integration you are referring to. [PreviousData export](https://mews-systems.gitbook.io/connector-api/use-cases/data-export) [NextEvents](https://mews-systems.gitbook.io/connector-api/use-cases/events) Last updated 11 months ago Was this helpful? --- # Housekeeping | Connector API A Housekeeping integration pulls live information about the physical state of rooms and other space resources, allows the housekeeping staff to update the state from the Housekeeping system and pushes this data back into Mews. [](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping#initial-configuration) Initial configuration ------------------------------------------------------------------------------------------------------------------------- The integration must first retrieve all the resources the property has configured in Mews using [Get all resources](https://mews-systems.gitbook.io/connector-api/operations/resources#get-all-resources) . The response contains all relevant information needed to map the physical configuration of the property in the external system. 'How to' use case API Operations How to get the list of rooms and spaces [Get all resources](https://mews-systems.gitbook.io/connector-api/operations/resources#get-all-resources) > **Terminology:** For an explanation of terms like `room`, `space` and `resource`, see the [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) > . [](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping#managing-resources) Managing resources ------------------------------------------------------------------------------------------------------------------- To ensure all of the information is synchronized between the two systems, a Housekeeping integration can monitor changes to the state of a resource. Rather than polling the API for state changes, you can subscribe to notification events using [Webhooks](https://mews-systems.gitbook.io/connector-api/events) or [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) . Both methods support changes to resources. Don't know which one to use? See [Ways to communicate](https://github.com/MewsSystems/gitbook-connector-api/blob/master/guidelines/communicate.md) . 'How to' use case API Operations How to listen for changes to reservations [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) (`Reservation` event) How to get reservation and customer details [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) Once a staff member has cleaned or inspected a room, the state can be updated in Mews using [Update resources](https://mews-systems.gitbook.io/connector-api/operations/resources#update-resources) , specifying the new state of the resource. 'How to' use case API Operations How to update the state of a resource [Update resources](https://mews-systems.gitbook.io/connector-api/operations/resources#update-resources) Resource blocks are blocks of rooms or resources set to 'out of order' or 'internal use'. Information about resource blocks can be requested using [Get all resource blocks](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#get-all-resource-blocks) . Housekeeping integrations can also manage blocks through [Add resource block](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#add-resource-block) and [Delete resource blocks](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#delete-resource-blocks) . 'How to' use case API Operations How to get information about resource blocks [Get all resource blocks](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#get-all-resource-blocks) How to add a resource block [Add resource block](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#add-resource-block) How to delete resource blocks [Delete resource blocks](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#delete-resource-blocks) [](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping#staff-tasks) Staff tasks ----------------------------------------------------------------------------------------------------- If you need to create a task directly in Mews, this can be done using [Add task](https://mews-systems.gitbook.io/connector-api/operations/tasks#add-task) . If a task should be assigned to a specific department, the unique identifiers required for this action can be retrieved using [Get all departments](https://mews-systems.gitbook.io/connector-api/operations/departments#get-all-departments) . A list of existing tasks can be retrieved from Mews using [Get all tasks](https://mews-systems.gitbook.io/connector-api/operations/tasks#get-all-tasks) . 'How to' use case API Operations How to add a staff task [Add task](https://mews-systems.gitbook.io/connector-api/operations/tasks#add-task) How to get information about departments [Get all departments](https://mews-systems.gitbook.io/connector-api/operations/departments#get-all-departments) How to get the list of staff tasks [Get all tasks](https://mews-systems.gitbook.io/connector-api/operations/tasks#get-all-tasks) [](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping#dirty-status) Dirty status ------------------------------------------------------------------------------------------------------- Mews allows properties to configure when a space will be marked as `Dirty`, upon check-in or check-out, in their Stay service settings. They can also configure a specific housekeeping time interval after which, if a space is vacant, it will automatically change state to `Dirty`. For example, if the field is set to two days, the space will automatically become `Dirty` after two days. Each unit represents a period of 24 hours, with automatic changes occurring between 04:00 and 05:00. The maximum amount of time for this time interval is 7 days, after which the state will automatically change to `Dirty` to adhere to regulations preventing Legionella. [](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping#testing-your-integration) Testing your integration ------------------------------------------------------------------------------------------------------------------------------- Please ensure you follow our general [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) for testing integrations. In addition to this, using the [demo environment](https://mews-systems.gitbook.io/connector-api/guidelines/environments) credentials, you can run the [Space Status Report](https://help.mews.com/s/article/space-status-report?language=en_US) (housekeeping report) to cross-check if the integration is working correctly. [](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping#additional-help-for-working-with-the-demo-environment) Additional help for working with the demo environment ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > **Help Guides**: > > * [Out-of-service and out-of-order](https://help.mews.com/s/article/what-are-house-use-out-of-service-and-out-of-order-features?language=en_US) > > * [How to set up a stay service](https://help.mews.com/s/article/set-up-a-bookable-service?language=en_US) > [PreviousGuest technology](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology) [NextKiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) Last updated 11 months ago Was this helpful? --- # Payment automation | Connector API This section describes how to use automated payments processing. We also provide links to information on Mews PCI compliance, including current certification. For connecting to Mews Payment Terminals to take payments from customers, please refer to [Mews Payment Terminals](https://mews-systems.gitbook.io/connector-api/use-cases/mews-terminals) . > #### > > [](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation#pci-compliance) > > PCI Compliance > > * [Mews PCI compliance](https://help.mews.com/s/article/pci-compliance?language=en_US) > > * [Mews PCI certificate](https://www.mews.com/en/platform-documentation) > [](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation#using-tokenized-credit-cards) Using tokenized credit cards --------------------------------------------------------------------------------------------------------------------------------------------- If the user interface of your solution involves the collection and storage of credit card details in a secure manner against the customer's profile in Mews, you can use [Add tokenized credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#add-tokenized-credit-card) and then [Charge credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#charge-credit-card) to securely take and post a payment into Mews. The workflow mimics the result of a user manually [adding a new payment card](https://mews.force.com/s/article/add-a-new-payment-card?language=en_US) in Mews Operations and then [charging the card via the Mews payment gateway](https://help.mews.com/s/article/take-a-payment?language=en_US) . 'How to' use case API Operations How to add a credit card to the guest profile [Add tokenized credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#add-tokenized-credit-card) How to charge a guest credit card using Mews Payments [Charge credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#charge-credit-card) [](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation#retrieving-tokenized-credit-cards) Retrieving tokenized credit cards ------------------------------------------------------------------------------------------------------------------------------------------------------- To check if a user's credit card is already attached to their customer profile, call [Get all credit cards](https://mews-systems.gitbook.io/connector-api/operations/creditcards#get-all-credit-cards) to search for credit cards by the `CreditCardId` or `CustomerId`. The credit cards tokenized via the Mews Payment Gateway (PCI Proxy) can be identified by the [`Credit card kind`](https://mews-systems.gitbook.io/connector-api/operations/creditcards#credit-card-kind) property, with the corresponding value being "Gateway". 'How to' use case API Operations How to check if a credit card is stored against a guest profile [Get all credit cards](https://mews-systems.gitbook.io/connector-api/operations/creditcards#get-all-credit-cards) [](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation#adding-a-tokenized-credit-card) Adding a tokenized credit card ------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation#id-1.-retrieve-publickey) 1\. Retrieve PublicKey As an integration partner, you will not need to set up your own Payment Gateway account. Rather, when automating payments via the **Mews Connector API**, you should work with Mews' own account. To do so, call [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) to obtain the `PublicKey` value, found within the [payment card storage](https://mews-systems.gitbook.io/connector-api/operations/configuration#payment-card-storage) object. This value will be used as the `merchantId` with the Mews Payment Gateway (PCI Proxy). 'How to' use case API Operations How to get the merchant ID for the Mews Payment Gateway [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) ### [](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation#id-2.-set-up-the-secure-fields-payment-form-to-collect-card-data) 2\. Set up the Secure Fields payment form to collect card data Refer to the [PCI Proxy documentation on Secure Fields](https://docs.pci-proxy.com/docs/secure-fields) for collecting card number, CVV and expiration date\* through the Secure Fields payment form. Implement Quick Start Step 1 [Set up your Payment Form](https://docs.pci-proxy.com/docs/secure-fields-quick-start) and follow the **Secure Fields Form** recipe. As part of this process, you will use the Mews `PublicKey` (obtained in the step above) as the `merchantId`. Take note of `data.transactionId` in the response, which looks like a series of numbers (e.g. `201028230732590232`). For further assistance, see [Integration Examples](https://docs.pci-proxy.com/docs/secure-fields-examples) . Note you do _not_ need to follow Step 2 [Obtain the tokens](https://docs.pci-proxy.com/docs/secure-fields-quick-start) , this step is performed instead by the Mews back-end. > **Expiration date:** Though not required by PCI Proxy, credit card expiration date is listed as a mandatory parameter on the [Add tokenized credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#add-tokenized-credit-card) > endpoint so that it can be displayed within the customer profile in Mews. This can also be used as an additional validation method for the property to know if there is an expired card on file. To handle this, we recommend that the payment form includes a field for users to input their credit card expiration date, which need not be sent to PCI Proxy, but should be cached, so that the information can be included in the [Add tokenized credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#add-tokenized-credit-card) > API request. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation#id-3.-add-the-tokenized-credit-card-to-a-customer-profile-in-mews) 3\. Add the tokenized credit card to a customer profile in Mews Add the tokenized credit card to a customer profile in Mews by calling [Add tokenized credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#add-tokenized-credit-card) . Enter the `transactionId` and obfuscated credit card details in the [credit card data](https://mews-systems.gitbook.io/connector-api/operations/creditcards#credit-card-data) object. Take note of the `CreditCardId` in the API response. > **Obfuscated number:** `ObfuscatedNumber` should only contain at most the first six digits and last four digits of a credit card. Alternatively replacing the entire string value with 16 asterisks `*` is also acceptable. The credit card will now be visible in the customer profile in Mews, under the **Payments > Credit cards** section. Note that while customer profiles are shared across all properties in a chain, credit card details are not. [](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation#charging-the-tokenized-credit-card) Charging the tokenized credit card --------------------------------------------------------------------------------------------------------------------------------------------------------- Now that you have the `CreditCardid`, you can use the [Charge credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#charge-credit-card) endpoint to charge the customer. > **Charge credit card:** Note the [Charge credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#charge-credit-card) > operation actually charges the customer's credit card, whereas the [Add credit card payment](https://mews-systems.gitbook.io/connector-api/operations/payments#add-credit-card-payment) > operation does NOT. The latter simply records a credit card payment in Mews and does not trigger any additional action beyond Mews - suitable for when the customer's credit card has already been charged from your solution. [PreviousMews Payment Terminals](https://mews-systems.gitbook.io/connector-api/use-cases/mews-terminals) [NextPoint of sale](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) Last updated 4 months ago Was this helpful? --- # Reputation management | Connector API Reputation management systems typically require reservation information, customer profile information, and the ability to update customer profiles. [](https://mews-systems.gitbook.io/connector-api/use-cases/reputation-management#retrieving-reservations) Retrieving reservations -------------------------------------------------------------------------------------------------------------------------------------- After a customer has checked out from a reservation, Reputation management systems often send a survey through to a customer's email. The integration partner can request all checked-out reservations for a given period using [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) with [reservation state](https://mews-systems.gitbook.io/connector-api/operations/reservations#reservation-state) set to `Processed`. For optimal API usage, ensure cascading time periods with short time frames, e.g. request every 4 hours for the previous 4 hour period. To receive notifications that a reservation has been checked-out, you should use [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) (`Reservation` event). 'How to' use case API Operations How to get checked-out reservations [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) How to listen for changes to reservations [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) (`Reservation` event) [](https://mews-systems.gitbook.io/connector-api/use-cases/reputation-management#updating-the-customer-profile) Updating the customer profile -------------------------------------------------------------------------------------------------------------------------------------------------- When a Reputation management system links customer feedback to a customer, use [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) to update the customer profile in Mews. The [customer classification](https://mews-systems.gitbook.io/connector-api/operations/customers#customer-classification) `PreviousComplaint` should be used when negative feedback has been received. Further to this, keywords from the complaint and a URL to the survey or Tripadvisor post can be added to the customer `Notes` field. 'How to' use case API Operations How to update the customer profile [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) [](https://mews-systems.gitbook.io/connector-api/use-cases/reputation-management#testing-your-integration) Testing your integration ---------------------------------------------------------------------------------------------------------------------------------------- Please ensure you follow our general [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) for testing integrations. [PreviousPoint of sale](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) [NextRevenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) Last updated 11 months ago Was this helpful? --- # 'How to' use cases | Connector API This page summarises all of our 'how to' use cases, together with the main use cases in which they are referenced. Search here for the task you want to perform with the API, it will take you to the appropriate API Operation or API Operations, and also link to higher level use cases for context and further information. > **Can't find what you're looking for?** 'How to' use cases are expressed in common terminology, but often different terms are used to mean the same thing. Try searching using alternative terms. We created the [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) > to explain the particular terminology used in Mews. If you still can't find what you're looking for, [let us know](mailto:partnersuccess@mews.com) > . [](https://mews-systems.gitbook.io/connector-api/use-cases/how-to#configuration) Configuration --------------------------------------------------------------------------------------------------- 'How to' use case API Operations Use cases How to get enterprise or property configuration [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) , [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to get the list of supported countries [Get all countries](https://mews-systems.gitbook.io/connector-api/operations/countries#get-all-countries) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get the list of supported currencies [Get all currencies](https://mews-systems.gitbook.io/connector-api/operations/currencies#get-all-currencies) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get the list of supported languages [Get all languages](https://mews-systems.gitbook.io/connector-api/operations/languages#get-all-languages) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) , [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to get applicable tax rates [Get all tax environments](https://mews-systems.gitbook.io/connector-api/operations/taxenvironments#get-all-tax-environments) , [Get all taxations](https://mews-systems.gitbook.io/connector-api/operations/taxations#get-all-taxations) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get editable history window [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) [Accounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) [](https://mews-systems.gitbook.io/connector-api/use-cases/how-to#finance) Finance --------------------------------------------------------------------------------------- 'How to' use case API Operations Use cases How to get configured accounting categories [Get all accounting categories](https://mews-systems.gitbook.io/connector-api/operations/accountingcategories#get-all-accounting-categories) [Accounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) , [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) , [Point of sale](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) How to get the list of accounting categories [Get all accounting categories](https://mews-systems.gitbook.io/connector-api/operations/accountingcategories#get-all-accounting-categories) [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) , [Guest technology](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology) , [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to add accounting items to a bill [Update accounting items](https://github.com/MewsSystems/gitbook-connector-api/blob/master/operations/finance.md#update-accounting-items) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to move bill items to a new bill [Update accounting items](https://mews-systems.gitbook.io/connector-api/operations/accountingitems#update-accounting-items) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to get accounting items consumed over a period [Get all payments](https://mews-systems.gitbook.io/connector-api/operations/payments#get-all-payments) , [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) [Accounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) How to get payment items paid over a period [Get all payments](https://mews-systems.gitbook.io/connector-api/operations/payments#get-all-payments) [Accounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) How to get order items consumed over a period [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) [Accounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) How to get a list of revenue items for a reservation [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) [Accounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) How to get order items linked to a reservation [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to find the original order item for a rebate item [Get all order items](https://mews-systems.gitbook.io/connector-api/operations/orderitems#get-all-order-items) [Accounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) How to get outlet items consumed over a period [Get all outlet items](https://mews-systems.gitbook.io/connector-api/operations/outletitems#get-all-outlet-items) [Accounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) How to get bills and invoices [Get all bills](https://mews-systems.gitbook.io/connector-api/operations/bills#get-all-bills) [Accounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) How to get the customer or guest bill [Get all bills](https://mews-systems.gitbook.io/connector-api/operations/bills#get-all-bills) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to create a new bill [Add bill](https://github.com/MewsSystems/gitbook-connector-api/blob/master/operations/finance.md#add-bill) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) , [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to close a bill against change [Close bill](https://github.com/MewsSystems/gitbook-connector-api/blob/master/operations/finance.md#close-bill) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) , [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to get a printable bill [Get bill PDF](https://mews-systems.gitbook.io/connector-api/operations/bills#close-bill) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to charge a guest credit card using Mews Payments [Charge credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#charge-credit-card) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) , [Payment automation](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation) How to add a credit card to the guest profile [Add tokenized credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#add-tokenized-credit-card) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) , [Payment automation](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation) How to get details of stored credit cards [Get all credit cards](https://mews-systems.gitbook.io/connector-api/operations/creditcards#get-all-credit-cards) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) , [Payment automation](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation) How to check if a credit card is stored against a guest profile [Get all credit cards](https://mews-systems.gitbook.io/connector-api/operations/creditcards#get-all-credit-cards) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) , [Payment automation](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation) How to get the merchant ID for the Mews Payment Gateway [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) [Payment automation](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation) How to record an external card payment [Add credit card payment](https://mews-systems.gitbook.io/connector-api/operations/payments#add-credit-card-payment) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to record a general external payment [Add external payment](https://mews-systems.gitbook.io/connector-api/operations/payments#add-external-payment) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to record an alternative external payment [Add alternative payment](https://mews-systems.gitbook.io/connector-api/operations/payments#add-alternative-payment) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to post end-of-day accounting items [Add outlet bill](https://mews-systems.gitbook.io/connector-api/operations/outletbills#add-outlet-bills) [Point of sale](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) [](https://mews-systems.gitbook.io/connector-api/use-cases/how-to#enterprises-and-resources) Enterprises & Resources ------------------------------------------------------------------------------------------------------------------------- 'How to' use case API Operations Use cases How to get configured rooms and spaces [Get all resources](https://mews-systems.gitbook.io/connector-api/operations/resources#get-all-resources) [Point of sale](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) , [Housekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) , [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get resource categories or room types [Get all resources](https://mews-systems.gitbook.io/connector-api/operations/resources#get-all-resources) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to update the state of a resource or room [Update resources](https://mews-systems.gitbook.io/connector-api/operations/resources#update-resources) [Housekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) How to get resource blocks (out of order, etc.) [Get all resource blocks](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#get-all-resource-blocks) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) , [Housekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) How to get information about out-of-order blocks [Get all resource blocks](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#get-all-resource-blocks) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to add a resource block [Add resource block](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#add-resource-block) [Housekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) How to delete resource blocks [Delete resource blocks](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#delete-resource-blocks) [Housekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) How to get the configured outlets [Get all outlets](https://mews-systems.gitbook.io/connector-api/operations/outlets#get-all-outlets) [Point of sale](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) How to get company profiles [Get all companies](https://mews-systems.gitbook.io/connector-api/operations/companies#get-all-companies) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to find an existing company [Get all companies](https://mews-systems.gitbook.io/connector-api/operations/companies#get-all-companies) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to add a new company [Add company](https://mews-systems.gitbook.io/connector-api/operations/companies#add-company) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get information about departments [Get all departments](https://mews-systems.gitbook.io/connector-api/operations/departments#get-all-departments) [Housekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) How to get the list of staff tasks [Get all tasks](https://mews-systems.gitbook.io/connector-api/operations/tasks#get-all-tasks) [Housekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) How to add a staff task [Add task](https://mews-systems.gitbook.io/connector-api/operations/tasks#add-task) [Housekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) How to create staff reminders [Add task](https://mews-systems.gitbook.io/connector-api/operations/tasks#add-task) [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) [](https://mews-systems.gitbook.io/connector-api/use-cases/how-to#customer-profiles) Customer Profiles ----------------------------------------------------------------------------------------------------------- 'How to' use case API Operations Use cases How to create a customer or guest profile [Add customer](https://mews-systems.gitbook.io/connector-api/operations/customers#add-customer) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to update a customer or guest profile [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) , [Reputation management](https://mews-systems.gitbook.io/connector-api/use-cases/reputation-management) How to create a Paymaster profile [Add customer](https://mews-systems.gitbook.io/connector-api/operations/customers#add-customer) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to update a profile to be a Paymaster [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to remove the Paymaster classification [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get a list of profiles created over a period of time [Get all customers](https://mews-systems.gitbook.io/connector-api/operations/customers#get-all-customers) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get checked in and checked out guests [Get all customers](https://mews-systems.gitbook.io/connector-api/operations/customers#get-all-customers) [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) How to search for a customer or guest [Search customers](https://mews-systems.gitbook.io/connector-api/operations/customers#search-customers) [Point of sale](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) How to get only checked in guests [Search customers](https://mews-systems.gitbook.io/connector-api/operations/customers#search-customers) [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) How to review already posted items [Get customer open items](https://mews-systems.gitbook.io/connector-api/operations/customers#get-customers-open-items) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get the list of open revenue items for a guest [Get customer open items](https://mews-systems.gitbook.io/connector-api/operations/customers#get-customers-open-items) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) [](https://mews-systems.gitbook.io/connector-api/use-cases/how-to#reservations) Reservations ------------------------------------------------------------------------------------------------- 'How to' use case API Operations Use cases How to listen for changes to reservations [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) (`Reservation` event) [Guest technology](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology) , [Customer management](https://mews-systems.gitbook.io/connector-api/use-cases/customer-management) , [Housekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) , [Reputation management](https://mews-systems.gitbook.io/connector-api/use-cases/reputation-management) , [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) , [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get reservation and customer details [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) [Guest technology](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology) , [Customer management](https://mews-systems.gitbook.io/connector-api/use-cases/customer-management) , [Housekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) How to get reservation details [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to get reservations updated over a time period [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) [Customer management](https://mews-systems.gitbook.io/connector-api/use-cases/customer-management) How to look up a guest reservation [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to get checked-out reservations [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) [Reputation management](https://mews-systems.gitbook.io/connector-api/use-cases/reputation-management) How to get historical reservations data [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to get a specific reservation [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) How to update the details of a reservation [Update reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to add a guest to a reservation [Add reservation companion](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservation-companion) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) , [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to remove a guest from a reservation [Delete reservation companion](https://mews-systems.gitbook.io/connector-api/operations/reservations#delete-reservation-companion) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) , [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to change the reservation owner [Update reservation customer](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservation-customer) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to modify the date or time of a reservation [Update reservation interval](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservation-interval) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to check in a guest reservation [Start reservation](https://mews-systems.gitbook.io/connector-api/operations/reservations#start-reservation) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to check out a guest reservation [Process reservation](https://mews-systems.gitbook.io/connector-api/operations/reservations#process-reservation) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to add a product to a reservation [Add reservation product](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservation-product) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to add a product order to a reservation [Add reservation product](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservation-product) [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) How to push a reservation to Mews [Add reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservations) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to make a new booking [Add reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservations) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to place an existing reservation into an availability block [Update reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to remove a reservation from an availability block [Update reservation](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to price a specific reservation [Price reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#price-reservations) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) [](https://mews-systems.gitbook.io/connector-api/use-cases/how-to#data-export) Data Export ----------------------------------------------------------------------------------------------- 'How to' use case API Operations Use cases How to create a bulk data export [Add export](https://mews-systems.gitbook.io/connector-api/operations/exports#add-export) [Data export](https://mews-systems.gitbook.io/connector-api/use-cases/data-export) , [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to check on data export progress [Get all exports](https://mews-systems.gitbook.io/connector-api/operations/exports#get-all-exports) [Data export](https://mews-systems.gitbook.io/connector-api/use-cases/data-export) , [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) [](https://mews-systems.gitbook.io/connector-api/use-cases/how-to#services-and-products) Services & Products ----------------------------------------------------------------------------------------------------------------- 'How to' use case API Operations Use cases How to get the list of property services [Get all services](https://mews-systems.gitbook.io/connector-api/operations/services#get-all-services) [Guest technology](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology) How to get the list of services offered [Get all services](https://mews-systems.gitbook.io/connector-api/operations/services#get-all-services) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) , [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) , [Point of sale](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) How to get the list of products linked to services [Get all products](https://mews-systems.gitbook.io/connector-api/operations/products#get-all-products) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) , [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) How to get the list of available products [Get all products](https://mews-systems.gitbook.io/connector-api/operations/products#get-all-products) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get configured rates [Get all rates](https://mews-systems.gitbook.io/connector-api/operations/rates#get-all-rates) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) , [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) , [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get configured rate groups [Get all rate groups](https://mews-systems.gitbook.io/connector-api/operations/rates#get-all-rate-groups) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to get rate pricing [Get rate pricing](https://mews-systems.gitbook.io/connector-api/operations/rates#get-rate-pricing) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to get the price for a given rate [Get rate pricing](https://mews-systems.gitbook.io/connector-api/operations/rates#get-rate-pricing) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get the price for a specific rate and time period [Get rate pricing](https://mews-systems.gitbook.io/connector-api/operations/rates#get-rate-pricing) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to listen for changes to rate prices [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) (`PriceUpdate` event) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to get rate package rules [Get all rules](https://mews-systems.gitbook.io/connector-api/operations/rules#get-all-rules) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to get all configured business segments [Get all business segments](https://mews-systems.gitbook.io/connector-api/operations/businesssegments#get-all-business-segments) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to get service restrictions [Get all restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#get-all-restrictions) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to add or remove restrictions (old) [Add restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#add-restrictions) , [Delete restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#delete-restrictions) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to add or remove restrictions (new) [Set restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#set-restrictions) , [Clear restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions#clear-restrictions) [Revenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) How to get availability [Get service availability](https://mews-systems.gitbook.io/connector-api/operations/services#get-service-availability) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) , [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to get room or resource availability [Get service availability](https://mews-systems.gitbook.io/connector-api/operations/services#get-service-availability) [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) How to update or amend service availability [Update service availability](https://mews-systems.gitbook.io/connector-api/operations/services#update-service-availability) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to post an order for a guest [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) How to post an order item to a guest profile [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) [Guest technology](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology) How to add a product order item to a customer profile [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to add a product order to a guest profile [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) How to post a charge to a customer profile [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) [Point of sale](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) How to link an order to a reservation [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) (use `LinkedReservationId`) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) , [Kiosk](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) , [Guest technology](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology) , [Upsell](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) , [Point of sale](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) [](https://mews-systems.gitbook.io/connector-api/use-cases/how-to#availability-blocks) Availability Blocks --------------------------------------------------------------------------------------------------------------- 'How to' use case API Operations Use cases How to create an availability block [Add availability blocks](https://mews-systems.gitbook.io/connector-api/operations/availabilityblocks#add-availability-blocks) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to get existing availability blocks [Get all availability blocks](https://mews-systems.gitbook.io/connector-api/operations/availabilityblocks#get-all-availability-blocks) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to delete an availability block [Delete availability blocks](https://mews-systems.gitbook.io/connector-api/operations/availabilityblocks#delete-availability-blocks) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to place an existing reservation into an availability block [Update reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) How to remove a reservation from an availability block [Update reservation](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) [Events](https://mews-systems.gitbook.io/connector-api/use-cases/events) > **What is an Availability Block?** Availability Blocks are fixed sets of inventory (rooms, spaces or resources) that are provisionally removed from public availability for use by private groups such as wedding parties, or for companies or travel agencies. For more information, see our Help Guide [Creating availability blocks](https://help.mews.com/s/article/Creating-availability-blocks-in-Mews?language=en_US) > . [](https://mews-systems.gitbook.io/connector-api/use-cases/how-to#customer-loyalty) Customer Loyalty --------------------------------------------------------------------------------------------------------- 'How to' use case API Operations Use cases How to add a Loyalty Program [Add loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#add-loyalty-programs) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to get a list of Loyalty Programs [Get all loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#get-all-loyalty-programs) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to get the Chain identifier for a property [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to update a Loyalty Program [Update loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#update-loyalty-programs) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to delete a Loyalty Program [Delete loyalty programs](https://mews-systems.gitbook.io/connector-api/operations/loyaltyprograms#delete-loyalty-programs) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to add a Loyalty Tier [Add loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#add-loyalty-tiers) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to get a list of Loyalty Tiers [Get all loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#get-all-loyalty-tiers) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to update a Loyalty Tier [Update loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#update-loyalty-tiers) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to delete a Loyalty Tier [Delete loyalty tiers](https://mews-systems.gitbook.io/connector-api/operations/loyaltytiers#delete-loyalty-tiers) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to add a Loyalty Membership [Add loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#add-loyalty-memberships) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to get a list of Loyalty Memberships [Get all loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#get-all-loyalty-memberships) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to update a Loyalty Membership [Update loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#update-loyalty-memberships) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) How to delete a Loyalty Membership [Delete loyalty memberships](https://mews-systems.gitbook.io/connector-api/operations/loyaltymemberships#delete-loyalty-memberships) [Customer loyalty](https://mews-systems.gitbook.io/connector-api/use-cases/loyalty) [](https://mews-systems.gitbook.io/connector-api/use-cases/how-to#customer-messaging) Customer Messaging ------------------------------------------------------------------------------------------------------------- 'How to' use case API Operations Use cases How to get your message threads [Get all message threads](https://mews-systems.gitbook.io/connector-api/operations/messagethreads#get-all-message-threads) [Customer messaging](https://mews-systems.gitbook.io/connector-api/use-cases/messaging) How to get messages for your message threads [Get all messages](https://mews-systems.gitbook.io/connector-api/operations/messages#get-all-messages) [Customer messaging](https://mews-systems.gitbook.io/connector-api/use-cases/messaging) How to create a new message thread [Add message thread](https://mews-systems.gitbook.io/connector-api/operations/messagethreads#add-message-thread) [Customer messaging](https://mews-systems.gitbook.io/connector-api/use-cases/messaging) How to create a new message within a thread [Add messages](https://mews-systems.gitbook.io/connector-api/operations/messages#add-messages) [Customer messaging](https://mews-systems.gitbook.io/connector-api/use-cases/messaging) How to listen for new customer messages [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) (`MessageAdded` event) [Customer messaging](https://mews-systems.gitbook.io/connector-api/use-cases/messaging) [](https://mews-systems.gitbook.io/connector-api/use-cases/how-to#device-commands) Device Commands ------------------------------------------------------------------------------------------------------- 'How to' use case API Operations Use cases How to listen for new device commands [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) [Device integration](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration) How to get details of a device command [Get all commands by ids](https://mews-systems.gitbook.io/connector-api/operations/commands#get-all-commands-by-ids) [Device integration](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration) How to get all unprocessed device commands [Get all commands](https://mews-systems.gitbook.io/connector-api/operations/commands#get-all-commands) [Device integration](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration) How to update the state of a device command [Update command](https://mews-systems.gitbook.io/connector-api/operations/commands#update-command) [Device integration](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration) > **What is a Device Command?** Device Commands are messages sent by Mews to on-premise devices such as printers and key encoders. For more information, see the [Device integration](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration) > use case. [PreviousUse cases](https://mews-systems.gitbook.io/connector-api/use-cases) [NextAccounting](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) Last updated 8 months ago Was this helpful? --- # Upsell | Connector API An Upsell integration pulls information about customers, reservations, products and services, for specified time intervals, in order to automate upselling of personalised room upgrades, add-ons and experiences to guests. [](https://mews-systems.gitbook.io/connector-api/use-cases/upsell#data-pull) Data pull ------------------------------------------------------------------------------------------- Each Mews property creates a unique set of services and related products based on what they offer to their guests. Upsell integrations pull the relevant product information (e.g. name, unique identifier, price) and store it in their system for future use. A list of all the services a property offers can be requested using [Get all services](https://mews-systems.gitbook.io/connector-api/operations/services#get-all-services) . The response contains a unique identifier which can then be used to pull all related products using [Get all products](https://mews-systems.gitbook.io/connector-api/operations/products#get-all-products) . 'How to' use case API Operations How to get the list of services offered [Get all services](https://mews-systems.gitbook.io/connector-api/operations/services#get-all-services) How to get the list of products linked to services [Get all products](https://mews-systems.gitbook.io/connector-api/operations/products#get-all-products) If the integration is offering room upgrades to guests, it is important to take availability of the resources into account. After mapping the configuration of the property in your system, use [Get service availability](https://mews-systems.gitbook.io/connector-api/operations/services#get-service-availability) to fetch resource availability for each resource category. 'How to' use case API Operations How to get room or resource availability [Get service availability](https://mews-systems.gitbook.io/connector-api/operations/services#get-service-availability) > **Help Guides**: > > * [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) > > * [Understanding services](https://help.mews.com/s/article/understanding-services?language=en_US) > > * [Creating products](https://help.mews.com/s/article/create-or-delete-a-product?language=en_US) > [](https://mews-systems.gitbook.io/connector-api/use-cases/upsell#adding-items) Adding items ------------------------------------------------------------------------------------------------- Once all of the products, services and related information are correctly stored in the Upsell system, the next step is the posting of a selected product into Mews. How this product should be posted into Mews depends on whether it exists as a product in Mews and which type of service it belongs to. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/upsell#adding-product-items-such-as-breakfast-or-a-room-upgrade) Adding product items such as breakfast or a room upgrade If the product is related to a Stay/Accommodation service, e.g. breakfast, an extra bed or a room upgrade, then it is useful to associate it with a specific reservation. This will lead to the correct overall count of products to be posted based on the total of nights in the reservation. First, the integration should retrieve the specific reservation using [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) . The unique identifiers of the product and the reservation are then used in [Add reservation product](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservation-product) to add the required product order to the reservation. 'How to' use case API Operations How to get a specific reservation [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) How to add a product order to a reservation [Add reservation product](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservation-product) ### [](https://mews-systems.gitbook.io/connector-api/use-cases/upsell#adding-product-items-such-as-champagne-or-a-massage) Adding product items such as champagne or a massage If the product is created under a non-Stay/Accommodation service, it will only be posted once and does not have to be attached to a reservation. Examples include a bottle of champagne, a one-hour massage, or a pool bar cocktail. Unlike with a traditional PMS, where charges are posted to a room, in Mews all charges are posted directly to the guest profile. All guests, both active and checked out, can be retrieved using [Get all customers](https://mews-systems.gitbook.io/connector-api/operations/customers#get-all-customers) . This operation offers numerous filters, including guest email and guest names. To retrieve only guests still checked in at the property, use [Search customers](https://mews-systems.gitbook.io/connector-api/operations/customers#search-customers) . The unique identifier of the chosen guest or customer is then used to add the product to the correct profile using [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) . If the product being posted already exists in Mews, then use [Product order parameters](https://mews-systems.gitbook.io/connector-api/operations/orders#product-order-parameters) . If the product does not exist in Mews then use [Item parameters](https://mews-systems.gitbook.io/connector-api/operations/orders#item-parameters) . > #### > > [](https://mews-systems.gitbook.io/connector-api/use-cases/upsell#linking-orders-to-reservations) > > Linking orders to reservations > > When using [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) > , specify parameter `LinkedReservationId` in order to link the order to a guest reservation. This will greatly assist the property when using billing automation. 'How to' use case API Operations How to get checked in and checked out guests [Get all customers](https://mews-systems.gitbook.io/connector-api/operations/customers#get-all-customers) How to get only checked in guests [Search customers](https://mews-systems.gitbook.io/connector-api/operations/customers#search-customers) How to add a product order to a guest profile [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) How to link an order to a reservation [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) (use `LinkedReservationId`) ### [](https://mews-systems.gitbook.io/connector-api/use-cases/upsell#accounting-categories-and-staff-reminders) Accounting categories and staff reminders To ensure correct reporting, all revenue items posted into Mews must be associated with their correct accounting category by sending the unique identifier in the [Item parameters](https://mews-systems.gitbook.io/connector-api/operations/orders#item-parameters) of the [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) request. Information about all the categories configured at each property can be obtained with [Get all accounting categories](https://mews-systems.gitbook.io/connector-api/operations/accountingcategories#get-all-accounting-categories) . If a product being added to a reservation requires further action from hotel staff, create reminders and assign responsiblities using [Add task](https://mews-systems.gitbook.io/connector-api/operations/tasks#add-task) to ensure no aspect of the guest experience is forgotten. 'How to' use case API Operations How to get the list of accounting categories [Get all accounting categories](https://mews-systems.gitbook.io/connector-api/operations/accountingcategories#get-all-accounting-categories) How to create staff reminders [Add task](https://mews-systems.gitbook.io/connector-api/operations/tasks#add-task) > **Help Guides**: > > * [Creating an accounting category](https://help.mews.com/s/article/create-an-accounting-category?language=en_US) > > * [how tasks are created and managed](https://help.mews.com/s/article/create-and-manage-tasks?language=en_US) > [](https://mews-systems.gitbook.io/connector-api/use-cases/upsell#testing-your-upsell-integration) Testing your Upsell integration --------------------------------------------------------------------------------------------------------------------------------------- Ensure you follow our general [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) for testing integrations. In addition to this, and specific to Upsell integrations, check whether you are correctly managing the Stay product postings by reviewing the _Items_ tab of the reservation you have posted it to, or review the _Product_ column of the [Reservation report](https://help.mews.com/s/article/reservation-report?language=en_US) which has `Include products` selected in the _Options_ section. To confirm you are relating any product that is not configured in Mews with the correct accounting category, you can review the [Accounting Report](https://help.mews.com/s/article/accounting-report?language=en_US) . If done correctly, the product you've posted will be listed under the relevant accounting category. [PreviousRevenue management](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) [NextAPI Operations](https://mews-systems.gitbook.io/connector-api/operations) Last updated 8 months ago Was this helpful? --- # Events | Connector API Event management systems streamline the planning, organization and execution of events such as weddings or conferences. An Events integration can pull live information about rates and availability, create availability blocks (also known as room blocks or group blocks), affect property inventory, push contracted revenue to the relevant guest’s profile in Mews, and allow users to manage the group reservations already pushed into Mews. [](https://mews-systems.gitbook.io/connector-api/use-cases/events#enterprise-information) Enterprise information --------------------------------------------------------------------------------------------------------------------- To automate the onboarding of a new property as much as possible, use a combination of [Configuration](https://mews-systems.gitbook.io/connector-api/operations#configuration) operations, [Enterprises](https://mews-systems.gitbook.io/connector-api/operations#enterprises) operations and [Services](https://mews-systems.gitbook.io/connector-api/operations#services) operations to pull information about a property or enterprise, including, but not limited to, resources configuration (including rooms and other spaces), applicable tax rates, services and products, and company profiles. 'How to' use case API Operations How to get property configuration [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) How to get rooms and resources configuration [Get all resources](https://mews-systems.gitbook.io/connector-api/operations/resources#get-all-resources) How to get applicable tax rates [Get all tax environments](https://mews-systems.gitbook.io/connector-api/operations/taxenvironments#get-all-tax-environments) , [Get all taxations](https://mews-systems.gitbook.io/connector-api/operations/taxations#get-all-taxations) How to get the list of services offered [Get all services](https://mews-systems.gitbook.io/connector-api/operations/services#get-all-services) How to get the list of products linked to services [Get all products](https://mews-systems.gitbook.io/connector-api/operations/products#get-all-products) How to get company profiles [Get all companies](https://mews-systems.gitbook.io/connector-api/operations/companies#get-all-companies) How to get the list of supported countries [Get all countries](https://mews-systems.gitbook.io/connector-api/operations/countries#get-all-countries) How to get the list of supported currencies [Get all currencies](https://mews-systems.gitbook.io/connector-api/operations/currencies#get-all-currencies) How to get the list of supported languages [Get all languages](https://mews-systems.gitbook.io/connector-api/operations/languages#get-all-languages) [](https://mews-systems.gitbook.io/connector-api/use-cases/events#rates-and-availability) Rates and availability --------------------------------------------------------------------------------------------------------------------- Use [Get all rates](https://mews-systems.gitbook.io/connector-api/operations/rates#get-all-rates) and [Get rate pricing](https://mews-systems.gitbook.io/connector-api/operations/rates#get-rate-pricing) to pull data about rates offered in the property or enterprise. Use [Get service availability](https://mews-systems.gitbook.io/connector-api/operations/services#get-service-availability) to pull resource category availability and related adjustments from Mews. 'How to' use case API Operations How to get rates [Get all rates](https://mews-systems.gitbook.io/connector-api/operations/rates#get-all-rates) How to get the price for a given rate [Get rate pricing](https://mews-systems.gitbook.io/connector-api/operations/rates#get-rate-pricing) How to get availability [Get service availability](https://mews-systems.gitbook.io/connector-api/operations/services#get-service-availability) > **Availability blocks:** The `Availabilities` array returned by [Get service availability](https://mews-systems.gitbook.io/connector-api/operations/services#get-service-availability) > refers to inventory that is available to the general public and therefore does not include inventory that has been reserved for Availability Blocks. Likewise, the array of adjustments are those _not_ associated with Availability Blocks. [](https://mews-systems.gitbook.io/connector-api/use-cases/events#managing-billing) Managing billing --------------------------------------------------------------------------------------------------------- In Mews, billing is managed at the customer/guest profile level, instead of being charged to a specific room or reservation. If applicable, create a new company via [Add company](https://mews-systems.gitbook.io/connector-api/operations/companies#add-company) or find an existing company via [Get all companies](https://mews-systems.gitbook.io/connector-api/operations/companies#get-all-companies) and attach the company to both the reservation(s) and the customer bill(s) for more accurate billing and reporting. 'How to' use case API Operations How to add a new company [Add company](https://mews-systems.gitbook.io/connector-api/operations/companies#add-company) How to find an existing company [Get all companies](https://mews-systems.gitbook.io/connector-api/operations/companies#get-all-companies) ### [](https://mews-systems.gitbook.io/connector-api/use-cases/events#paymaster-accounts) Paymaster accounts Use a [Paymaster](https://mews-systems.gitbook.io/connector-api/operations/customers#customer-classification) customer profile to centrally manage charges and billing related to the company/event. This also allows any additional orders (e.g. F&B spending) to be added via the POS system, if needed. If the relevant customer profile does not already exist in Mews, first use [Add customer](https://mews-systems.gitbook.io/connector-api/operations/customers#add-customer) to create a profile. > **Mews tip:** Make sure that only active [Paymaster](https://mews-systems.gitbook.io/connector-api/operations/customers#customer-classification) > profiles exist in Mews. In order to keep data clean in the Mews system, only mark a profile with the [Paymaster](https://mews-systems.gitbook.io/connector-api/operations/customers#customer-classification) classification when the event management system starts posting charges to the customer profile. Use [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) to mark the profile as a [Paymaster](https://mews-systems.gitbook.io/connector-api/operations/customers#customer-classification) account. Similar to the concept of _fake rooms_ in traditional Property Management Systems that are deleted at the end of an event, remove the [Paymaster](https://mews-systems.gitbook.io/connector-api/operations/customers#customer-classification) classification from the customer profile once the relevant event has concluded, e.g. event ended, all billing settled, and/or the event is canceled. Use the [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) operation to remove the [Paymaster](https://mews-systems.gitbook.io/connector-api/operations/customers#customer-classification) classification. Refer to the [Update values](https://mews-systems.gitbook.io/connector-api/guidelines/serialization#update-values) section on how to change or remove a value. You can also use [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) to amend other customer profile details. Should you need to retrieve a list of all customer profiles created within a certain interval, use the [Get all customers](https://mews-systems.gitbook.io/connector-api/operations/customers#get-all-customers) operation with the relevant time filters. 'How to' use case API Operations How to create a Paymaster profile [Add customer](https://mews-systems.gitbook.io/connector-api/operations/customers#add-customer) How to update a profile to be a Paymaster [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) How to remove the Paymaster classification [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) How to get a list of profiles created over a period of time [Get all customers](https://mews-systems.gitbook.io/connector-api/operations/customers#get-all-customers) [](https://mews-systems.gitbook.io/connector-api/use-cases/events#adding-revenue-and-payment-items) Adding revenue and payment items ----------------------------------------------------------------------------------------------------------------------------------------- One of the expected functions of an Events integration is to push product order items to the correct customer profile in Mews. This can be done using the operation [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) . If the product item that is being posted already exists in Mews, use [Product order parameters](https://mews-systems.gitbook.io/connector-api/operations/orders#product-order-parameters) . If the product is a custom item that does not exist in Mews then use [Item parameters](https://mews-systems.gitbook.io/connector-api/operations/orders#item-parameters) . Note that in order to use [Product order parameters](https://mews-systems.gitbook.io/connector-api/operations/orders#product-order-parameters) , the property must first set up products under an Additional Service. Then, you will need to retrieve the products by calling [Get all products](https://mews-systems.gitbook.io/connector-api/operations/products#get-all-products) . To ensure correct reporting, all revenue items posted into Mews using [Item parameters](https://mews-systems.gitbook.io/connector-api/operations/orders#item-parameters) must be associated with their correct accounting category by sending the unique identifier of the accounting category in the request. Information about all the categories configured at each property can be retrieved using [Get all accounting categories](https://github.com/MewsSystems/gitbook-connector-api/blob/master/operations/finance.md#get-all-accounting-categories) . > #### > > [](https://mews-systems.gitbook.io/connector-api/use-cases/events#linking-orders-to-reservations) > > Linking orders to reservations > > When using [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) > , specify parameter `LinkedReservationId` in order to link the order to a guest reservation. This will greatly assist the property when using billing automation. 'How to' use case API Operations How to add a product order item to a customer profile [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) How to get the list of available products [Get all products](https://mews-systems.gitbook.io/connector-api/operations/products#get-all-products) How to get accounting categories [Get all accounting categories](https://mews-systems.gitbook.io/connector-api/operations/accountingcategories#get-all-accounting-categories) How to link an order to a reservation [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) (use `LinkedReservationId`) ### [](https://mews-systems.gitbook.io/connector-api/use-cases/events#recording-external-payments) Recording external payments In case payment was taken outside of Mews, or directly in the event management system, use [Finance operations](https://mews-systems.gitbook.io/connector-api/operations#finance) to record the payment items in Mews, so that all accounting items are centralised in Mews for further reporting and/or exporting to the property's accounting system. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/events#further-automation-possibilities) Further automation possibilities Call [Get customer open items](https://mews-systems.gitbook.io/connector-api/operations/customers#get-customers-open-items) to review the revenue and payment items that have already been posted to a customer profile. You can then further automate the management of billing/invoicing by creating a specific bill using [Add bill](https://github.com/MewsSystems/gitbook-connector-api/blob/master/operations/finance.md#add-bill) for a certain group of revenue and payment items. Use [Update accounting items](https://github.com/MewsSystems/gitbook-connector-api/blob/master/operations/finance.md#update-accounting-items) to redirect these items to the relevant bill and then use [Close bill](https://github.com/MewsSystems/gitbook-connector-api/blob/master/operations/finance.md#close-bill) to finalise the financial document. 'How to' use case API Operations How to review already posted items [Get customer open items](https://mews-systems.gitbook.io/connector-api/operations/customers#get-customers-open-items) How to create a new bill [Add bill](https://github.com/MewsSystems/gitbook-connector-api/blob/master/operations/finance.md#add-bill) How to add accounting items to a bill [Update accounting items](https://github.com/MewsSystems/gitbook-connector-api/blob/master/operations/finance.md#update-accounting-items) How to close a bill against change [Close bill](https://github.com/MewsSystems/gitbook-connector-api/blob/master/operations/finance.md#close-bill) > **Attaching a company to a bill:** Currently, attaching a company to a bill must be done manually in **Mews Operations**. If being able to do this via the API is important to your solution, please consider adding your vote to [this feature request](https://feedback.mews.com/forums/932131-mews-open-api/suggestions/43041963-attach-company-id-to-bills) > . [](https://mews-systems.gitbook.io/connector-api/use-cases/events#managing-group-reservations-with-availability-blocks) Managing group reservations with availability blocks --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Availability blocks are used for reserving a certain portion of resource category availability in Mews for a specific group of reservations, as well as the subsequent management of reservations that are created in Mews for such groups. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/events#creating-availability-blocks) Creating availability blocks First call [Add availability blocks](https://mews-systems.gitbook.io/connector-api/operations/availabilityblocks#add-availability-blocks) to add a new block with the relevant parameters. Note the returned availability block `Id`, which is used as the unique identifier in all interactions with Mews. There is no expectation to create availability blocks and allocate inventory in Mews straight away for events in the early, tentative, stages of a sales cycle. It is up to the integration partner to decide at which stage of an event order to create an availability block and start allocating inventory in Mews. 'How to' use case API Operations How to create an availability block [Add availability blocks](https://mews-systems.gitbook.io/connector-api/operations/availabilityblocks#add-availability-blocks) ### [](https://mews-systems.gitbook.io/connector-api/use-cases/events#allocating-inventory-to-an-availability-block) Allocating inventory to an availability block Now that you have created an availability block, you can allocate capacity for different dates and resource categories, i.e. create room night blocks. Use [Update service availability](https://mews-systems.gitbook.io/connector-api/operations/services#update-service-availability) to push availability adjustments into Mews. Send a _negative_ value for the `UnitCountAdjustment` parameter and include the aforementioned `AvailabilityBlockId` in the [availability update](https://mews-systems.gitbook.io/connector-api/operations/services#availability-update) parameter to reserve units of availability for the availability block you have just created. The availability adjustments must fall within the `StartUtc` and `EndUtc` of the availability block. * _Example: If you wish to reserve 10 units of availability for certain dates, send -10 in the_ `_UnitCountAdjustment_` _parameter._ * _Example: Original adjustment was -5 to reserve 5 units of availability for 1st of May. User now wishes to increase inventory for the availability block for that date by 2 (to 7 total). In this case, send adjustment -7 to override the original adjustment._ 'How to' use case API Operations How to update or amend service availability [Update service availability](https://mews-systems.gitbook.io/connector-api/operations/services#update-service-availability) > **Overbooking:** Note it is possible to allow overbooking by allocating more inventory than there are resources physically available at the property, e.g. an adjustment of -10 when there are 9 units. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/events#adding-reservations-to-an-availability-block) Adding reservations to an availability block When a new reservation is created within the event management system, it needs to be synced with Mews, and vice versa. Reservations can be pushed into Mews using the [Add reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservations) operation. To ensure that the reservations consume availability reserved for the availability block, instead of from the property's overall availability, include `AvailabilityBlockId` in the [reservations parameters](https://mews-systems.gitbook.io/connector-api/operations/reservations#reservation-parameters) when you add reservations into an existing group block. It is also possible to place an existing reservation in Mews into an availability block with the [Update reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) operation, by including `AvailabilityBlockId` in the [reservations parameters](https://mews-systems.gitbook.io/connector-api/operations/reservations#reservation-parameters) . If applicable, you can attach a company to a reservation when calling [Add reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservations) or [Update reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) . 'How to' use case API Operations How to push a reservation to Mews [Add reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservations) How to place an existing reservation into an availability block [Update reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) > **Availability block capacity:** Note that it is currently not possible to exceed the availability block capacity, i.e. the inventory allocated to an availability block through the [Update service availability](https://mews-systems.gitbook.io/connector-api/operations/services#update-service-availability) > operation. However, it is possible to add reservations with arrival or departure times that extend beyond the interval in a given availability block (see [availability block parameters](https://mews-systems.gitbook.io/connector-api/operations/availabilityblocks#availability-block-parameters) > ). Should there be a need to accommodate more reservations in an availability block, you must first update the adjustments to increase the allocated inventory in that block. ### [](https://mews-systems.gitbook.io/connector-api/use-cases/events#managing-reservations-and-guests) Managing reservations and guests To ensure that the property can further manage individual guests linked to the group reservation, via the integration, use [Add reservation companion](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservation-companion) or [Delete reservation companion](https://mews-systems.gitbook.io/connector-api/operations/reservations#delete-reservation-companion) to assign or unassign guests to rooms. 'How to' use case API Operations How to add a guest to a reservation [Add reservation companion](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservation-companion) How to remove a guest from a reservation [Delete reservation companion](https://mews-systems.gitbook.io/connector-api/operations/reservations#delete-reservation-companion) > **Terminology:** Note that the API uses the term _customer_ rather than _guest_. The term _companion_ is used to indicate a guest profile linked to a reservation. For an explanation of all terms, see the [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) > . ### [](https://mews-systems.gitbook.io/connector-api/use-cases/events#managing-availability-block-inventory-and-pickup) Managing availability block inventory and pickup Call [Get all availability blocks](https://mews-systems.gitbook.io/connector-api/operations/availabilityblocks#get-all-availability-blocks) to retrieve information about existing availability blocks, as well as all associated reservations and availability adjustments. To avoid the need of regular polling, you can make use of [Webhooks](https://mews-systems.gitbook.io/connector-api/events#general-message) for Service Order events to automatically receive information about reservation creation and reservation updates. Make a note of the `AvailabilityBlockId` in the reservation object to record pickup of the relevant availability block in your system and in Mews. When a reservation no longer belongs to the availability block, follow the format described in [Update reservation](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) to remove the `AvailabilityBlockId`. When an availability block is no longer needed, remove it from Mews by calling [Delete availability blocks](https://mews-systems.gitbook.io/connector-api/operations/availabilityblocks#delete-availability-blocks) . The availability adjustments associated with the availability block will automatically be removed. Note that is it not possible to delete an availability block containing active reservations. 'How to' use case API Operations How to get existing availability blocks [Get all availability blocks](https://mews-systems.gitbook.io/connector-api/operations/availabilityblocks#get-all-availability-blocks) How to listen for changes to reservations [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) (`ServiceOrderUpdated` event) How to delete an availability block [Delete availability blocks](https://mews-systems.gitbook.io/connector-api/operations/availabilityblocks#delete-availability-blocks) How to remove a reservation from an availability block [Update reservation](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) [](https://mews-systems.gitbook.io/connector-api/use-cases/events#testing-your-integration) Testing your integration ------------------------------------------------------------------------------------------------------------------------- Ensure you follow our general [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) for testing integrations. If you'd like to double-check that you are correctly creating all the reservations you want to retrieve, you can do so by [searching for the reservation or related customer profile](https://help.mews.com/s/article/search-in-mews-operations?language=en_US) , or using the [Reservation Report](https://help.mews.com/s/article/reservation-report?language=en_US) . To confirm you are relating any product that is not configured in Mews with the correct accounting category, you can review the [Accounting Report](https://help.mews.com/s/article/accounting-report?language=en_US) . If done correctly, the product you've posted will appear under the relevant accounting category. [](https://mews-systems.gitbook.io/connector-api/use-cases/events#additional-help-for-working-with-the-demo-environment) Additional help for working with the demo environment ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > **Help Guides**: > > * [Availability blocks and reporting in Mews](https://help.mews.com/s/article/Availability-block-report?language=en_US) > > * [How to create an accounting category](https://help.mews.com/s/article/create-an-accounting-category?language=en_US) > > * [How to create rates](https://help.mews.com/s/article/create-a-rate?language=en_US) > > * [How to update rates](https://help.mews.com/s/article/update-or-remove-a-rate?language=en_US) > > * [How to manage rate prices](https://help.mews.com/s/article/rate-management?language=en_US) > > * [Managing companions in a reservation](https://help.mews.com/s/article/how-to-add-a-companion-to-a-reservation?language=en_US) > > * [How to manage group billing](https://help.mews.com/s/article/group-billing-how-to-move-bill-items?language=en_US) > > * [Manually add, move, or remove items from open bills](https://help.mews.com/s/article/new-billing-procedure-add-move-or-remove-items-from-open-bills?language=en_US) > > * [Finding bills and invoices assigned to a company](https://help.mews.com/s/article/how-to-find-bills-and-invoices-assigned-to-a-company?language=en_US) > > * [Create a Paymaster account](https://help.mews.com/s/article/create-a-paymaster?language=en_US) > > * [Create a company profile](https://help.mews.com/s/article/create-a-company-profile?language=en_US) > [PreviousDevice integration](https://mews-systems.gitbook.io/connector-api/use-cases/device-integration) [NextGuest technology](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology) Last updated 8 months ago Was this helpful? --- # Kiosk | Connector API Some properties employ kiosk solutions that allow guests to self-manage aspects of their stay. Typically, this includes check-in and check-out, but it can extend to walk-in bookings, stay management and all aspects of the guest journey. Functionality can include updating the guest profile, viewing the guest bill and making payments, thus the kiosk category of integration covers a number of use cases. Here we consider the most common use cases, although kiosks need not be limited to these. > #### > > [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#kiosk-devices) > > Kiosk devices > > Kiosks can be apps running on off-the-shelf devices such as tablets, or they can consist of custom hardware, incorporating devices such as key encoders, printers and passport scanners. If such devices are integrated into the kiosk, then only one integration is made between the kiosk and Mews, the connections with the devices are handled internally by the kiosk. [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#initial-configuration) Initial configuration ------------------------------------------------------------------------------------------------------------------ To help configure your kiosk for a specific property, perform an initial pull of configuration data, including supported currencies and the default language code. To offer multiple languages, you can retrieve the list of languages supported by the API. You will want to fetch the list of supported guest services and associated products, as properties can configure additional services as well as the default Stay accommodation service. 'How to' use case API Operations How to get property configuration [Get configuration](https://mews-systems.gitbook.io/connector-api/operations/configuration#get-configuration) How to get the list of supported languages [Get all languages](https://mews-systems.gitbook.io/connector-api/operations/languages#get-all-languages) How to get the list of services and products [Get all services](https://mews-systems.gitbook.io/connector-api/operations/services#get-all-services) , [Get all products](https://mews-systems.gitbook.io/connector-api/operations/products#get-all-products) [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#guest-check-in) Guest check-in ---------------------------------------------------------------------------------------------------- To look up a guest reservation, use the general-purpose operation [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) and specify the required search filters. To check in a reservation, use [Start reservation](https://mews-systems.gitbook.io/connector-api/operations/reservations#start-reservation) . Note Mews uses the phrase "start reservation" rather than "check-in", and "process reservation" rather than "check-out". 'How to' use case API Operations How to look up a guest reservation [Get all reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) How to check in a guest reservation [Start reservation](https://mews-systems.gitbook.io/connector-api/operations/reservations#start-reservation) [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#working-with-guest-profiles) Working with guest profiles ------------------------------------------------------------------------------------------------------------------------------ If the guest doesn't have a Mews customer profile, you can add one with [Add customer](https://mews-systems.gitbook.io/connector-api/operations/customers#add-customer) . If the guest already has a profile, but the information in it needs updating (e.g. address, passport or driver's licence), then use [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) . To relate a guest profile to a specific reservation, use [Add reservation companion](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservation-companion) . Note that "guests" are always referred to as "customers" in the Mews API. 'How to' use case API Operations How to create a guest profile [Add customer](https://mews-systems.gitbook.io/connector-api/operations/customers#add-customer) How to update a guest profile [Update customer](https://mews-systems.gitbook.io/connector-api/operations/customers#update-customer) How to add a guest to a reservation [Add reservation companion](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservation-companion) [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#guest-bill) Guest bill -------------------------------------------------------------------------------------------- You can fetch a list of revenue and payment items linked to a guest profile, or if there is a bill prepared you can request the guest bill. To split a bill, use the operations to add a new bill and move accounting items between bills. Once a bill is balanced to zero, it can be closed against further change. A PDF version of the bill can be fetched for printing or display purposes. 'How to' use case API Operations How to get the guest bill [Get all bills](https://mews-systems.gitbook.io/connector-api/operations/bills#get-all-bills) How to get a printable bill [Get bill PDF](https://mews-systems.gitbook.io/connector-api/operations/bills#get-bill-pdf) How to get the list of open revenue items for a guest [Get customer open items](https://mews-systems.gitbook.io/connector-api/operations/customers#get-customers-open-items) How to create a new bill [Add bill](https://mews-systems.gitbook.io/connector-api/operations/bills#add-bill) How to move bill items to a new bill [Update accounting items](https://mews-systems.gitbook.io/connector-api/operations/accountingitems#update-accounting-items) How to close a bill against change [Close bill](https://mews-systems.gitbook.io/connector-api/operations/bills#close-bill) > #### > > [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#payment-automation) > > Payment automation > > At the end of the reservation, Mews payment automation may have been enacted, so before taking payment from a guest to settle a bill, confirm the outstanding balance as described above. [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#taking-payments) Taking payments ------------------------------------------------------------------------------------------------------ Once you have confirmed the outstanding balance, you have three options for handling customer payments to settle the bill: * [Gateway payments](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#gateway-payments) * [Non-Mews terminal payments](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#non-mews-terminal-payments) * [Mews terminal payments](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#mews-terminal-payments) ### [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#gateway-payments) Gateway payments You can make payments using **Mews Payments**, which uses an online payment gateway. If the guest has a credit card on file, you can charge the card — just specify the card and the amount. The payment will be taken by Mews and recorded on the guest bill. If the guest doesn't have a credit card on file, you can add one to their profile. You can also see what cards are registered against a guest profile. 'How to' use case API Operations How to charge a guest credit card using Mews Payments [Charge credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#charge-credit-card) How to add a credit card to the guest profile [Add tokenized credit card](https://mews-systems.gitbook.io/connector-api/operations/creditcards#add-tokenized-credit-card) How to get details of stored credit cards [Get all credit cards](https://mews-systems.gitbook.io/connector-api/operations/creditcards#get-all-credit-cards) ### [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#non-mews-terminal-payments) Non-Mews terminal payments You can take an external payment from a guest using a payment terminal, i.e. outside of Mews. In this case, the payment just needs to be recorded against the guest bill. To record the payment, use the appropriate external payment operation. 'How to' use case API Operations How to record an external card payment [Add credit card payment](https://mews-systems.gitbook.io/connector-api/operations/payments#add-credit-card-payment) How to record a general external payment [Add external payment](https://mews-systems.gitbook.io/connector-api/operations/payments#add-external-payment) How to record an alternative external payment [Add alternative payment](https://mews-systems.gitbook.io/connector-api/operations/payments#add-alternative-payment) > #### > > [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#adding-external-payments) > > Adding external payments > > * Use [Add credit card payment](https://mews-systems.gitbook.io/connector-api/operations/payments#add-credit-card-payment) > for a card payment specifically — specify the amount, the credit card details (including obfuscated number) and the customer identifier. > > * Use [Add external payment](https://mews-systems.gitbook.io/connector-api/operations/payments#add-external-payment) > for a general payment of any type — specify the amount, the type of payment (e.g. cash) and the customer identifier. > > * Use [Add alternative payment](https://mews-systems.gitbook.io/connector-api/operations/payments#add-alternative-payment) > for supported alternative payment types, such as "Ideal" — specify the amount, the method of payment, the customer identifier, and any special requirements for that payment type. > ### [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#mews-terminal-payments) Mews terminal payments We also support the option to connect to Mews payment terminals, for which see our detailed use case [Mews Payment Terminals](https://mews-systems.gitbook.io/connector-api/use-cases/mews-terminals) . [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#guest-check-out) Guest check-out ------------------------------------------------------------------------------------------------------ Once the bill is settled, the guest can be checked-out. Note Mews uses the phrase "process reservation" rather than "check-out", and "customer" rather than "guest". 'How to' use case API Operations How to check out a guest reservation [Process reservation](https://mews-systems.gitbook.io/connector-api/operations/reservations#process-reservation) [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#modifying-reservations) Modifying reservations -------------------------------------------------------------------------------------------------------------------- A number of API operations are available to support modifications to reservations. [Update reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) offers the widest range of fields to update simultaneously for a specified reservation, e.g. adult count, assigned resource, company, rate. You can remove a companion (i.e. an additional guest) from a reservation using [Delete reservation companion](https://mews-systems.gitbook.io/connector-api/operations/reservations#delete-reservation-companion) , or change the primary guest or owner of the reservation with [Update reservation customer](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservation-customer) . To add additional products to a reservation, use [Add reservation product](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservation-product) . To modify only the start and/or end of the reservation, use [Update reservation interval](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservation-interval) . Products from additional services that may not be configured in Mews can be posted to the guest profile using [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) . If using [Item parameters](https://mews-systems.gitbook.io/connector-api/operations/orders#item-parameters) , it is highly recommended to specify the accounting category that the posting belongs to, for the sake of financial reporting. The list of accounting categories configured at a property is obtained using [Get all accounting categories](https://mews-systems.gitbook.io/connector-api/operations/accountingcategories#get-all-accounting-categories) . > #### > > [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#linking-orders-to-reservations) > > Linking orders to reservations > > When using [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) > , specify parameter `LinkedReservationId` in order to link the order to a guest reservation. This will greatly assist the property when using billing automation. 'How to' use case API Operations How to update the details of a reservation [Update reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservations) How to remove an additional guest from a reservation [Delete reservation companion](https://mews-systems.gitbook.io/connector-api/operations/reservations#delete-reservation-companion) How to change the reservation owner [Update reservation customer](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservation-customer) How to add a product to a reservation [Add reservation product](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservation-product) How to modify the date or time of a reservation [Update reservation interval](https://mews-systems.gitbook.io/connector-api/operations/reservations#update-reservation-interval) How to post an order for a guest [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) How to link an order to a reservation [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order) (use `LinkedReservationId`) How to get the list of accounting categories [Get all accounting categories](https://mews-systems.gitbook.io/connector-api/operations/accountingcategories#get-all-accounting-categories) [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#walk-in-bookings) Walk-in bookings -------------------------------------------------------------------------------------------------------- This section is relevant if your kiosk allows guests to create new reservations, rather than simply fetching existing reservations. The API supports operations to facilitate the process, but consider also looking at the [Mews Booking Engine API](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api) which is optimized for this task. Use [Get all resources](https://mews-systems.gitbook.io/connector-api/operations/resources#get-all-resources) to map out the physical configuration of the property. This will give you the names and descriptions of different resource categories, including room types. Use [Get service availability](https://mews-systems.gitbook.io/connector-api/operations/services#get-service-availability) to fetch availability. This availability does not consider resource blocks temporarily taken out of service, so you will also want to use [Get all resource blocks](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#get-all-resource-blocks) to get this information. Use [Get all rates](https://mews-systems.gitbook.io/connector-api/operations/rates#get-all-rates) to retrieve all the rates configured at the property, and [Get rate pricing](https://mews-systems.gitbook.io/connector-api/operations/rates#get-rate-pricing) to request the related prices for specified dates and times. Rate packages apply rules to automatically post specified products when certain rates are selected. Use [Get all rules](https://mews-systems.gitbook.io/connector-api/operations/rules#get-all-rules) to get the full list of rate rules. To calculate the price of a reservation with specific parameters, i.e. obtain a specific quotation, use [Price reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#price-reservations) . This can be used, for example, during check-in or check-out to get the new price of a reservation if you select a different resource category or room type, or to check if a selected or pre-booked product should have its price included or not. Finally, to make a new booking for the guest, use [Add reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservations) . Note you will need to specify the unique customer identifier for the guest profile (see [Working with guest profiles](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#working-with-guest-profiles) above). 'How to' use case API Operations How to get resource categories (room types) [Get all resources](https://mews-systems.gitbook.io/connector-api/operations/resources#get-all-resources) How to get availability [Get service availability](https://mews-systems.gitbook.io/connector-api/operations/services#get-service-availability) How to get resource blocks (out of order, etc.) [Get all resource blocks](https://mews-systems.gitbook.io/connector-api/operations/resourceblocks#get-all-resource-blocks) How to get configured rates [Get all rates](https://mews-systems.gitbook.io/connector-api/operations/rates#get-all-rates) How to get rate pricing [Get rate pricing](https://mews-systems.gitbook.io/connector-api/operations/rates#get-rate-pricing) How to price a specific reservation [Price reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#price-reservations) How to get rate package rules [Get all rules](https://mews-systems.gitbook.io/connector-api/operations/rules#get-all-rules) How to make a new booking [Add reservations](https://mews-systems.gitbook.io/connector-api/operations/reservations#add-reservations) [](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk#testing-your-integration) Testing your integration ------------------------------------------------------------------------------------------------------------------------ Ensure you follow our general [Usage guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) for testing integrations. For additional help when working with the demo environment, there is a range of helpful articles in the [Mews Help Center](https://help.mews.com/s/?language=en_US) , including [Understanding services](https://help.mews.com/s/article/understanding-services?language=en_US) . These are available in a number of languages. [PreviousHousekeeping](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) [NextMews Payment Terminals](https://mews-systems.gitbook.io/connector-api/use-cases/mews-terminals) Last updated 8 months ago Was this helpful? --- # Certification | Connector API The **Mews Connector API** is completely open and self-service - free of charge for integration partners and Mews customers alike to access, build against, and use. Only during certification and pilot confirmation would it require a member of the Mews Marketplace team to evaluate API activities generated by the integration in Demo. In the spirit of self-service, Mews does not provide a dedicated technical contact for each integration project. Instead, we aim to provide all materials and documentation you may need in order to develop, test, and certify your integration(s) through an automated workflow. To do this, the Mews Marketplace team continuously maintains the documentation. If you encounter bugs or incorrect documentation, please reach out to [partnersuccess@mews.com](mailto:partnersuccess@mews.com) . [](https://mews-systems.gitbook.io/connector-api/your-journey/certification#access-to-a-sandbox-demo-environment) Access to a sandbox demo environment ----------------------------------------------------------------------------------------------------------------------------------------------------------- Mews provides a sandbox demo environment that is available to the general public. You are free to experiment with our API using the [demo environment](https://mews-systems.gitbook.io/connector-api/guidelines/environments#demo-environments) credentials at any time in your integration partner journey with Mews. Furthermore, you can also use the demo environment to understand how a user interacts with Mews and where the data exchanged between your solution and Mews would appear in the Mews system. If you are considering building an integration, make sure you or your colleague has already completed the [Marketplace registration form](https://www.mews.com/en/partners/new-partnerships) to be registered in our integration partners database. [](https://mews-systems.gitbook.io/connector-api/your-journey/certification#developing-your-integration) Developing your integration ----------------------------------------------------------------------------------------------------------------------------------------- While we have a full list of [API operations](https://mews-systems.gitbook.io/connector-api/operations) you can freely choose from, you can also refer to the [Use cases](https://mews-systems.gitbook.io/connector-api/use-cases) to see how various common types of integration use the API to deliver a core set of functionality. Depending on the specificities of your solution and your customers' requirements, you may choose to implement a different flow from what has been described in the various use cases. [](https://mews-systems.gitbook.io/connector-api/your-journey/certification#testing-your-integration) Testing your integration ----------------------------------------------------------------------------------------------------------------------------------- Once your integration is developed, make sure that you have tested your integration against relevant use cases, acceptance criteria, and/or customer's needs. This should be done directly in the aforementioned demo environment. It is the integration partner's responsibility to ensure the quality and accuracy of data exchanged between the third-party system and Mews, for example that data is sent correctly to Mews, the desired set of data is pulled successfully from Mews, and the number of API requests made are within the request limits for the [Demo or Production environment](https://mews-systems.gitbook.io/connector-api/guidelines/environments) . Note that the features and functionality seen in the Demo environment mirrors that in the Production environment. [](https://mews-systems.gitbook.io/connector-api/your-journey/certification#certifying-your-integration) Certifying your integration ----------------------------------------------------------------------------------------------------------------------------------------- Once you have finished building and testing your integration, complete the [certification form](https://mews.typeform.com/to/ehTUz7) to launch the certification process. The certification process aims to confirm that the integration's API requests are accurate according to the Mews Connector API specifications, but does not question processes on the partner side. Evaluation of the integration for certification will be based on the information provided in the [certification form](https://mews.typeform.com/to/ehTUz7) regarding selected API operations and their purpose of use. The type of integration and the suggested implementation flow outlined in the [Use cases](https://mews-systems.gitbook.io/connector-api/use-cases) will be used as a general baseline as part of the evaluation. * Read more about [what you can expect during the certification process](https://help.mews.com/s/article/connector-api-certification-what-to-expect?language=en_US) [](https://mews-systems.gitbook.io/connector-api/your-journey/certification#further-information) Further information ------------------------------------------------------------------------------------------------------------------------- For more information about the integration partner journey, as well as any related marketing or commercial topics, please refer to the [Mews Help Center](https://help.mews.com/s/?language=en_US) . [PreviousYour integration journey](https://mews-systems.gitbook.io/connector-api/your-journey) [NextDeprecations](https://mews-systems.gitbook.io/connector-api/deprecations) Last updated 7 months ago Was this helpful? --- # API Events | Connector API API Events allow you to receive near-real-time notifications about key activities in the Mews system. These notifications are delivered via Webhooks or WebSockets, offering flexible solutions for various use cases. For an overview and guidance on selecting the best method for your needs, see [Ways to communicate](https://mews-systems.gitbook.io/connector-api/events/communicate) . To start using API Events, configure your system to receive event notifications and contact the Mews team at [partnersuccess@mews.com](mailto:partnersuccess@mews.com) to register your Webhook or WebSocket. [](https://mews-systems.gitbook.io/connector-api/events#webhooks) Webhooks ------------------------------------------------------------------------------- Mews currently supports two types of Webhook: **General Webhooks** and **Integration Webhooks**. Both types of Webhook message are sent as `HTTP POST` requests with the event details in the JSON body, just like standard requests to API endpoints. For guidance on setting up a Webhooks server, registering the URL, and responding to Webhook messages, see our [Webhooks FAQ](https://mews-systems.gitbook.io/connector-api/events/wh-faq) . [](https://mews-systems.gitbook.io/connector-api/events#contents) Contents ------------------------------------------------------------------------------- * [Ways to communicate](https://mews-systems.gitbook.io/connector-api/events/communicate) – an explanation of API Operations, Webhooks and WebSockets * [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) – a single Webhook that consolidates multiple event types * [Integration Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-integration) – individual Webhooks focused on integration state changes * [Webhooks FAQ](https://mews-systems.gitbook.io/connector-api/events/wh-faq) – answers to common questions about Webhooks * [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) – an alternative form of API Event for special use cases [PreviousVoucher codes](https://mews-systems.gitbook.io/connector-api/operations/vouchercodes) [NextWays to communicate](https://mews-systems.gitbook.io/connector-api/events/communicate) Last updated 11 months ago Was this helpful? --- # Ways to communicate | Connector API The purpose of this page is to provide an overview of the three different ways to interact with the API and suggest when you might use each particular one. The main way to integrate with Mews is to use API Operations to make requests, e.g. to fetch data or to request some other action. However, we also support Webhooks and WebSockets for special cases where polling is not efficient or not real-time enough. > #### > > [](https://mews-systems.gitbook.io/connector-api/events/communicate#three-ways-to-communicate) > > Three ways to communicate > > * [API Operations](https://mews-systems.gitbook.io/connector-api/events/communicate#API-operations) > > * [Webhooks](https://mews-systems.gitbook.io/connector-api/events/communicate#webhooks) > > * [WebSockets](https://mews-systems.gitbook.io/connector-api/events/communicate#websockets) > [](https://mews-systems.gitbook.io/connector-api/events/communicate#api-operations) API Operations ------------------------------------------------------------------------------------------------------- Most of the functionality in the API is in the form of API Operations. These operations work on a stateless, request-response basis. That means when you want to interact, you choose the moment and send a request, to which you will receive a response. If the request is for information, then the response will normally contain the requested information. If the request is to make an action of some sort, then the response may just be a success message to tell you the action was performed by Mews ok. * For the details of individual API operations, see [API Operations](https://mews-systems.gitbook.io/connector-api/operations) . But what if you want to know when some event happens in the Mews system? Using the standard request-response model, you would need to keep asking "has this event happened yet?". This is called polling, and is not very efficient. And that's where Webhooks and WebSockets come in. [](https://mews-systems.gitbook.io/connector-api/events/communicate#webhooks) Webhooks ------------------------------------------------------------------------------------------- A Webhook is the equivalent of Mews saying "don't keep asking if this event has happened yet, instead we'll let you know when it's happened. Give us your contact details and we'll call you." The contact details in this case is an accessible URL, provided by you. ![](https://mews-systems.gitbook.io/connector-api/~gitbook/image?url=https%3A%2F%2F850326323-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LBS6Dpna-dkV2PShmis%252Fuploads%252Fgit-blob-d3f845cb8a8a2a626469dd83c9f9c0b05cd7811a%252Fwebhooks-sequence.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=8476f16b&sv=2) In summary, API Operations are hosted on the Mews side of the integration and they follow the on-demand request model, whereas Webhooks are hosted on the partner side of the integration, and they follow the event model. Of course a Webhook is still a web API using request-response because that is how HTTP works, but in this case Mews is doing the requesting; and rather than making the request to get information, Mews is making the request to provide you with information based on some event that occurred in the Mews system. * For the details of individual Webhooks, the events that generate them and the structure of the data that's sent, see [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) and [Integration Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-integration) . ### [](https://mews-systems.gitbook.io/connector-api/events/communicate#when-are-webhooks-generated) When are Webhooks generated? A Webhook is generated when some event occurs in the system, however note these are not true real-time events, there may be a lag of up to several minutes (typically up to 2 to 5 minutes, depending on circumstances and on system parameters) between the event occurring and the Webhook being generated. For most use cases that is absolutely fine, but there are some use cases that require true real-time event information, e.g. generating digital keys. For this case, we have WebSockets. [](https://mews-systems.gitbook.io/connector-api/events/communicate#websockets) WebSockets ----------------------------------------------------------------------------------------------- A WebSocket is a technology for creating a semi-permanent connection over the web between a client and server, along which messages can pass simultaneously in both directions (called full-duplex). The connection is actually a TCP connection or 'socket' but over the web, hence the name. WebSockets thus don't follow the normal request-response pattern on which HTTP, the protocol of the web, is based. Indeed WebSockets have their own protocol WS which is distinct from HTTP (although cleverly it is compatible with HTTP, which enables a socket connection to be set up over the web). The advantage of using WebSockets to communicate is that the connection is already set up and ready to go, so it's quick to send a new message. If you really need low latency messages, i.e. real time messages, WebSockets may be the way to go. However, there are also disadvantages with using a form of communication that the web wasn't really designed for. As a result, Mews provides limited WebSocket support, and it should be considered a special case for rare use cases. * For details of our WebSockets support, including the list of events and the structure of the data that's sent, see [WebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) . ![](https://mews-systems.gitbook.io/connector-api/~gitbook/image?url=https%3A%2F%2F850326323-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LBS6Dpna-dkV2PShmis%252Fuploads%252Fgit-blob-3f27a962fd7a2d3854bbcc89f9051076c43cfc0d%252Fwebsockets.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=6ca6faf0&sv=2) [PreviousAPI Events](https://mews-systems.gitbook.io/connector-api/events) [NextGeneral Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) Last updated 5 months ago Was this helpful? --- # Your integration journey | Connector API For a general overview and step-by-step guide to the integration process for all **Mews Open API** integrations, see [Your journey with Mews](https://mews-systems.gitbook.io/open-api/your-journey) . The content below focuses specifically on developing a **Mews Connector API** integration. [](https://mews-systems.gitbook.io/connector-api/your-journey#contents) Contents ------------------------------------------------------------------------------------- * [Certification](https://mews-systems.gitbook.io/connector-api/your-journey/certification) Information about the process of certifying your integration and gaining access to the Mews Marketplace. [PreviousWebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) [NextCertification](https://mews-systems.gitbook.io/connector-api/your-journey/certification) Last updated 11 months ago Was this helpful? --- # Webhooks FAQ | Connector API * [How do I register a Webhook with Mews?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#how-do-i-register-a-webhook-with-mews) * [Are there special considerations for setting up a Webhook server?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#are-there-special-considerations-for-setting-up-a-webhook-server) * [How can I authenticate Mews?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#how-can-i-authenticate-mews) * [How should the server respond to a Webhook request?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#how-should-the-server-respond-to-a-webhook-request) * [Do you attempt to resend failed Webhook messages?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#do-you-attempt-to-resend-failed-webhook-messages) * [When should I use Webhooks?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#when-should-i-use-webhooks) * [How are Webhooks different to WebSockets?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#how-are-webhooks-different-to-websockets) * [What events can I create Webhooks for?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#what-events-can-i-create-webhooks-for) * [What does an event message look like?](https://github.com/MewsSystems/gitbook-connector-api/blob/master/events/what-does-an-event-message-look-like/README.md) * [What is the frequency of event generation?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#what-is-the-frequency-of-event-generation) * [Can I see what Webhooks are configured?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#can-i-see-what-webhooks-are-configured) * [Can I set up multiple Webhooks?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#can-i-set-up-multiple-webhooks) * [Can I use Webhooks in an on-premise application?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#can-i-use-webhooks-in-an-on-premise-application) * [Is it possible to disable sending some messages to Webhooks?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#is-it-possible-to-disable-sending-some-messages-to-webhooks) * [Can you give me a specific use case for Webhooks?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#can-you-give-me-a-specific-use-case-for-webhooks) * [Is there a limit on the number of events in one Webhook?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#is-there-a-limit-on-the-number-of-events-in-one-webhook) * [I want an event not currently supported](https://mews-systems.gitbook.io/connector-api/events/wh-faq#i-want-an-event-not-currently-supported) [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#how-do-i-register-a-webhook-with-mews) How do I register a Webhook with Mews? ------------------------------------------------------------------------------------------------------------------------------------------------- Email [partnersuccess@mews.com](mailto:partnersuccess@mews.com) with details of your Webhook endpoint URL. [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#are-there-special-considerations-for-setting-up-a-webhook-server) Are there special considerations for setting up a Webhook server? ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The server must expose an endpoint accessible from the Mews infrastructure and can receive incoming `POST` HTTP requests with JSON content type. No special `content-type` headers are used. The server must respond in a timely manner (within 5 seconds). [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#how-can-i-authenticate-mews) How can I authenticate Mews? ----------------------------------------------------------------------------------------------------------------------------- To confirm that a request to your Webhook endpoint originates from Mews, we can add a shared secret token to the URL, as follows: ### [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#figure-1-webhook-authentication) Figure 1: Webhook Authentication ![](https://mews-systems.gitbook.io/connector-api/~gitbook/image?url=https%3A%2F%2F850326323-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252F-LBS6Dpna-dkV2PShmis%252Fuploads%252Fgit-blob-17a6ca0b1b99f1dad367a0449b67f221acffe28b%252Fwebhook-auth.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=7bca9dbc&sv=2) Webhook authentication To use this authentication, send us the token you wish to use via [partnersuccess@mews.com](mailto:partnersuccess@mews.com) . The token should be kept secret and not shared with anyone except Mews. [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#how-should-the-server-respond-to-a-webhook-request) How should the server respond to a Webhook request? --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The server must respond with an HTTP status code indicating a success (e.g. `200 OK`, `202 Accepted`, or `204 No Content`). The server can respond with a redirection status code which doesn't change the request method (e.g. `307 Temporary Redirect` or `308 Permanent Redirect`) and the event message will be sent to the new location. If the server cannot process the request, it should respond with an appropriate error status code (i.e. `4xx` or `5xx` status codes). When the server responds with an error status code, the event message delivery will be retried, see [Do you attempt to resend failed Webhook messages?](https://mews-systems.gitbook.io/connector-api/events/wh-faq#do-you-attempt-to-resend-failed-webhook-messages) . [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#do-you-attempt-to-resend-failed-webhook-messages) Do you attempt to resend failed Webhook messages? ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- If an event message fails to be delivered (either HTTP error code is received or the server doesn't respond within 5 seconds), the message will be re-sent after a few minutes. If the message isn't received after repeated attempts, it will be discarded. [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#when-should-i-use-webhooks) When should I use Webhooks? --------------------------------------------------------------------------------------------------------------------------- See [Ways to communicate](https://mews-systems.gitbook.io/connector-api/events/communicate) . [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#how-are-webhooks-different-to-websockets) How are Webhooks different to WebSockets? ------------------------------------------------------------------------------------------------------------------------------------------------------- See [Ways to communicate](https://mews-systems.gitbook.io/connector-api/events/communicate) . [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#what-events-can-i-create-webhooks-for) What events can I create Webhooks for? ------------------------------------------------------------------------------------------------------------------------------------------------- See the Webhook reference pages for the list of currently supported events: * [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) * [Integration Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-integration) [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#what-does-an-event-message-look-like) What does an event message look like? ----------------------------------------------------------------------------------------------------------------------------------------------- See the Webhook reference pages for details of the request body: * [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) * [Integration Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-integration) [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#what-is-the-frequency-of-event-generation) What is the frequency of event generation? --------------------------------------------------------------------------------------------------------------------------------------------------------- The frequency at which events are created in the Mews system depends on the type of event and on the level of activity. Note however there may be a time lag of up to several minutes from when the event occurs to when the actual Webhook request is made. See [When are Webhooks generated?](https://mews-systems.gitbook.io/connector-api/events/communicate#when-are-webhooks-generated) . [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#can-i-see-what-webhooks-are-configured) Can I see what Webhooks are configured? --------------------------------------------------------------------------------------------------------------------------------------------------- Webhooks are set up in the system administration, please contact [partnersuccess@mews.com](mailto:partnersuccess@mews.com) for information about what Webhooks are configured on the system for your application. [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#can-i-set-up-multiple-webhooks) Can I set up multiple Webhooks? ----------------------------------------------------------------------------------------------------------------------------------- Only one endpoint URL for [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) and one endpoint URL for [Integration Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-integration) can be set up per integration client, i.e. per partner application. If you wish, you can use the same endpoint URL for both types of Webhook. [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#can-i-use-webhooks-in-an-on-premise-application) Can I use Webhooks in an on-premise application? --------------------------------------------------------------------------------------------------------------------------------------------------------------------- Although possible, it is generally not recommended to use Webhooks for on-premise solutions. The webhooks endpoint must be accessible from Mews infrastructure and we may update the API multiple times a year, which may require updates to your application. If pushing the updates to the on-premise solution is difficult then the solution won't scale well. [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#is-it-possible-to-disable-sending-some-messages-to-webhooks) Is it possible to disable sending some messages to Webhooks? --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Yes. Event messages are configured for each integration, please contact [partnersuccess@mews.com](mailto:partnersuccess@mews.com) with your requirements and they can configure only the messages you want to receive. [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#can-you-give-me-a-specific-use-case-for-webhooks) Can you give me a specific use case for Webhooks? ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- A specific use case for Webhooks is described in [Event management - Managing availability block inventory and pickup](https://mews-systems.gitbook.io/connector-api/use-cases/events#managing-availability-block-inventory-and-pickup) , but Webhooks are relevant to many use cases and are discussed in the relevant section - see [Use cases](https://mews-systems.gitbook.io/connector-api/use-cases) . [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#is-there-a-limit-on-the-number-of-events-in-one-webhook) Is there a limit on the number of events in one Webhook? ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [General Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-general) carry multiple events that have occurred at the same time. Yes, there is an upper limit on the number of messages carried, before rolling over to a new message. This number is a system parameter, currently in the order of hundreds, but Mews reserves the right to adjust this value for performance reasons. [](https://mews-systems.gitbook.io/connector-api/events/wh-faq#i-want-an-event-not-currently-supported) I want an event not currently supported ---------------------------------------------------------------------------------------------------------------------------------------------------- The list of supported events is always under review and may be extended in future. If there is a system event that you are particularly interested in, please submit your request via the Mews [Product Ideas Forum](https://feedback.mews.com/) . We can't provide any guarantees, but we are very interested to know what kind of features our customers and partners are requesting. [PreviousIntegration Webhooks](https://mews-systems.gitbook.io/connector-api/events/wh-integration) [NextWebSockets](https://mews-systems.gitbook.io/connector-api/events/websockets) Last updated 3 months ago Was this helpful? --- # Mews Channel Manager API | Channel Manager API Welcome to the **Mews Channel Manager API**. This is the Mews API for distribution and sales channels, supporting two main use cases: distributing availability, rates and inventory data to sales channels, and accepting reservations from sales channels. To fully implement the API, you need to both make requests to Mews and also create your own endpoints to accept data from Mews. > #### > > [](https://mews-systems.gitbook.io/channel-manager-api#two-way-functionality) > > Two-way functionality > > * The [Mews side](https://mews-systems.gitbook.io/channel-manager-api/mews-operations) > handles requests from Channel Managers, including new reservations. > > * The [Channel Manager side](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations) > handles requests from Mews, including availability updates. > For detailed information on connecting, authentication tokens, error codes, and more, see our [Usage guidelines](https://mews-systems.gitbook.io/channel-manager-api/guidelines) . To gain deeper insights into Mews concepts, see [Concepts](https://mews-systems.gitbook.io/channel-manager-api/concepts) . For specific scenarios, see [Use cases](https://mews-systems.gitbook.io/channel-manager-api/use-cases) . If you have any questions or encounter issues, reach out to us at [partnersuccess@mews.com](mailto:partnersuccess@mews.com) . > #### > > [](https://mews-systems.gitbook.io/channel-manager-api#changes-to-this-api) > > Changes to this API > > * For the history of changes, see the [Changelog](https://mews-systems.gitbook.io/channel-manager-api/changelog) > . > > * For important information on deprecations, see [Deprecations](https://mews-systems.gitbook.io/channel-manager-api/deprecations) > . > > * To track changes and updates, follow the [GitHub repository](https://github.com/MewsSystems/gitbook-channel-manager-api/tree/master) > . > [NextUsage guidelines](https://mews-systems.gitbook.io/channel-manager-api/guidelines) Last updated 11 months ago Was this helpful? --- # Booking Engine API | Booking Engine Guide The **Mews Booking Engine API** is a web API that allows external applications such as booking widgets to interact programmatically with Mews to get information about offered rooms or spaces for a given property, to check availability of those rooms or spaces, and to create reservations. Use this option if you want to create your own custom booking engine. > #### > > [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api#openapi-definition) > > OpenAPI definition > > We maintain an [OpenAPI definition](https://api.mews.com/swagger/distributor/swagger.json) > (formerly Swagger) for the **Mews Booking Engine API**. You can use this to build out client applications using third party tools. At this stage we consider this a Beta test version, but please use it and get in touch to let us know how you get on. * [Usage guidelines](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines) * [Use cases](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases) * [API Operations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations) * [Deprecations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/deprecations) [PreviousTroubleshooting](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/troubleshooting) [NextUsage guidelines](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines) Last updated 9 months ago Was this helpful? --- # Your journey with Mews | Open API > #### > > [](https://mews-systems.gitbook.io/open-api/your-journey#partner-id) > > Partner ID > > You will be given a Partner ID at the start of the process (e.g. INT123456), please keep this safe as you will need this ID when it is time to certify your integration. Not got one yet? [Register to join the Marketplace](https://www.mews.com/en/partners/new-partnerships) > . We want your experience working with Mews to be quick and simple, so we make the process as automated and self-service as possible and minimise touchpoints with the Mews team. You just need to follow these steps: * [Step 1: Explore the APIs](https://mews-systems.gitbook.io/open-api/your-journey#step-1-exploration) * [Step 2: Let us know what you plan to do](https://mews-systems.gitbook.io/open-api/your-journey#step-2-qualification) * [Step 3: Develop and test your solution](https://mews-systems.gitbook.io/open-api/your-journey#step-3-development) * [Step 4: Get certified](https://mews-systems.gitbook.io/open-api/your-journey#step-4-certification) * [Step 5: Go live with a pilot](https://mews-systems.gitbook.io/open-api/your-journey#step-5-pilot) * [Step 6: Join the Marketplace!](https://mews-systems.gitbook.io/open-api/your-journey#step-6-publication) If you have questions about the process, drop us a line to [partnersuccess@mews.com](mailto:partnersuccess@mews.com) . > #### > > [](https://mews-systems.gitbook.io/open-api/your-journey#booking-engine-integrations) > > Booking Engine integrations > > Booking Engine API integrations are the exception as they do not need to be certified, do not need a pilot property, and will not normally be listed on the Marketplace. See [Booking Engine integrations](https://mews-systems.gitbook.io/open-api/your-journey/booking-engine-integrations) > . [](https://mews-systems.gitbook.io/open-api/your-journey#step-1-exploration) Step 1: Exploration ----------------------------------------------------------------------------------------------------- First find out [which of our APIs you should be using](https://mews-systems.gitbook.io/open-api/the-mews-apis) . If you're not sure, take a look at the [use cases](https://mews-systems.gitbook.io/open-api/use-cases) for suggestions. Each API has its own body of documentation, so you'll want to familiarize yourself with the guidelines and operations for the API you'll be using. [](https://mews-systems.gitbook.io/open-api/your-journey#step-2-qualification) Step 2: Qualification --------------------------------------------------------------------------------------------------------- Once you've had a chance to familiarize yourself with the APIs and the process, you will be asked to complete a short Qualification step to answer some basic questions: * Which API or APIs will you be developing against? * Is this a private integration (for just one enterprise customer) or a public integration (available through the Mews Marketplace)? * If this is a public integration, then what will be the pilot property? * What is your estimated timescale for development? [](https://mews-systems.gitbook.io/open-api/your-journey#step-3-development) Step 3: Development ----------------------------------------------------------------------------------------------------- When you've decided which API operations to use and how, you'll see each API has its own demo credentials for you to try them out, connecting to our demo servers. All of the information you need to start developing and testing is in the documentation. For example, if you're working with the Mews Connector API, the [guidelines](https://mews-systems.gitbook.io/connector-api/guidelines) include details of the [URLs and access credentials](https://mews-systems.gitbook.io/connector-api/guidelines/environments) . [](https://mews-systems.gitbook.io/open-api/your-journey#step-4-certification) Step 4: Certification --------------------------------------------------------------------------------------------------------- When you are finished developing and testing, it's time to get certified! Complete the [certification form](https://mews.typeform.com/to/ehTUz7) and we'll send you further instructions by email. As part of the certification process, you will be asked for some details about your integration, such as the endpoints you will be using and the request message frequency. You can find more information about certification in the following resources: * **Connector API integrations** * API Documentation: [Certification](https://mews-systems.gitbook.io/connector-api/guidelines/certification) * Mews Help: [Connector API Certification: What to expect](https://help.mews.com/s/article/connector-api-certification-what-to-expect?language=en_US) * **Channel Manager API integrations** * API Documentation: [Certification](https://mews-systems.gitbook.io/channel-manager-api/certification) * Mews Help: [Channel API Certification: What to expect](https://help.mews.com/s/article/channel-api-certification-what-to-expect?language=en_US) [](https://mews-systems.gitbook.io/open-api/your-journey#step-5-pilot) Step 5: Pilot ----------------------------------------------------------------------------------------- After successful certification, you will be sent a `Client Token` for connection to production sites - this token is unique to your application. To connect to a customer property, you will also need an `Access Token` (for the Connector API) or `Connection Token` (for the Channel Manager API) - this token is unique to the property. > **Important:** Tokens are your security keys to access customer data in Mews, please store them safely and securely, do not share them and do not put them into email communication. * **Public integration** If your integration is intended to be listed publicly in the Mews Marketplace, Mews will add the integration to the agreed pilot property and you will be automatically sent the relevant token for that property (either `Access Token` for a Connector API integration, or `Connection Token` for a Channel Manager API integration). The integration will need to run successfully for a period of time(\*1) on the pilot site before you can progress to [Step 6: Publication](https://mews-systems.gitbook.io/open-api/your-journey#step-6-publication) . * **Private integration** If this is a private integration to a single enterprise, Mews will add the integration to the relevant properties and you will automatically be sent the relevant token or tokens (`Access Tokens` for Connector API integrations, or `Connection Tokens` for Channel Manager API integrations). Although there is no pilot site, we will still monitor the performance of the integration for a period of time(\*1) just to confirm everything is ok. [](https://mews-systems.gitbook.io/open-api/your-journey#step-6-publication) Step 6: Publication ----------------------------------------------------------------------------------------------------- If your integration is intended to be listed publicly in the Mews Marketplace, then after an agreed period(\*1) of successful operation at the pilot site, you will automatically be notified by email with final instructions. Your solution will be listed in the Mews Marketplace and on the [Mews website](https://www.mews.com/en/products/marketplace) , and you can roll it out to all properties that want to integrate. For further information, see the [Connector API onboarding guide](https://help.mews.com/s/article/connector-api-integrations-onboarding-mutual-customers?language=en_US) and the [Channel Manager API onboarding guide](https://help.mews.com/s/article/channel-manager-onboarding-guide?language=en_US) . > \*1 The monitoring period will depend on circumstances, but typically this will be 2 weeks for a Connector API integration or 4 weeks for a Channel Manager API integration. [PreviousMews Marketplace](https://mews-systems.gitbook.io/open-api/mews-marketplace) [NextBooking Engine integrations](https://mews-systems.gitbook.io/open-api/your-journey/booking-engine-integrations) Last updated 6 months ago Was this helpful? --- # Concepts | Channel Manager API This section delves into domain-specific topics related to the **Mews** system. An understanding of these will help you to make the most effective use of the API. > #### > > [](https://mews-systems.gitbook.io/channel-manager-api/concepts#terminology) > > Terminology > > Some of the terms used in the API, such as _Space Type_ or _Client Token_, may not be familiar. For a full description of all the terms used, see the [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) > . [](https://mews-systems.gitbook.io/channel-manager-api/concepts#contents) Contents --------------------------------------------------------------------------------------- * [Restrictions](https://mews-systems.gitbook.io/channel-manager-api/concepts/restrictions) An explanation of what restrictions are and how they are described in the API. [PreviousCompliance](https://mews-systems.gitbook.io/channel-manager-api/guidelines/compliance) [NextRestrictions](https://mews-systems.gitbook.io/channel-manager-api/concepts/restrictions) Last updated 1 year ago Was this helpful? --- # Use cases | Channel Manager API This section describes how to use the **Mews Channel Manager API** to fulfil specific use cases, including managing sales channels and handling inventory updates. * [Channels](https://mews-systems.gitbook.io/channel-manager-api/use-cases/channels) How to manage the list of supported sales channels. * [Inventory updates](https://mews-systems.gitbook.io/channel-manager-api/use-cases/inventory-updates) An explanation of inventory update modes. [PreviousRestrictions](https://mews-systems.gitbook.io/channel-manager-api/concepts/restrictions) [NextChannels](https://mews-systems.gitbook.io/channel-manager-api/use-cases/channels) Last updated 11 months ago Was this helpful? --- # Deprecations | Channel Manager API Deprecations are features of the API which you are discouraged from using, even though they may still be supported for a period of time for the sake of backwards compatibility. Such features are normally deprecated because they are superseded by a better alternative. They can include object properties, entire objects or entire API operations. The list of deprecations is as follows. Individual items are also highlighted in the [Changelog](https://mews-systems.gitbook.io/channel-manager-api/changelog) when they occur. Historic deprecations that have already been discontinued may not be listed. For more information, see our [Deprecations Policy](https://mews-systems.gitbook.io/open-api/staying-up-to-date/deprecations-policy) . > **Important:** We strongly advise you to review this list and if you are using any of the deprecated items in your integration, to update your implementation accordingly. If the feature change requires re-certification, please [contact Mews](mailto://partnersuccess@mews.com) > before making the change. The table columns have the following meanings: * **Feature** - What entity or feature is being deprecated * **Comments** - Additional information, such as the reason for the deprecation and what the replacement is * **Deprecated** - The date at which the deprecation notice was given (see the [Changelog](https://mews-systems.gitbook.io/channel-manager-api/changelog) ) * **Discontinued** - The date at which it is planned to discontinue support completely; a value of '-' indicates no date has been set [](https://mews-systems.gitbook.io/channel-manager-api/deprecations#deprecated-operations) Deprecated operations --------------------------------------------------------------------------------------------------------------------- Feature Comments Deprecated Discontinued \- \- \- \- [](https://mews-systems.gitbook.io/channel-manager-api/deprecations#deprecated-properties) Deprecated properties --------------------------------------------------------------------------------------------------------------------- Feature Comments Deprecated Discontinued `grossAmount` in [Rate](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#rate) object in [Mews: Process availability block](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#process-availability-block) Replaced by `prices` collection of [`Price`](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/inventory#price) 12 March 2025 \- `loyaltyCode` in [Customer](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#customer) object in [Mews: Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) Replaced by `loyaltyInfo` 4 Nov 2024 \- `releasedDate` in [Dates](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/availabilityblock#dates) object in [CHM: Availability block](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/availabilityblock#availability-block) Replaced by `fixedDate` in [`Release strategy`](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#release-strategy) of [`Availability block`](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/availabilityblock#availability-block) 11 Oct 2024 \- `error` in [Synchronous error response](https://mews-systems.gitbook.io/channel-manager-api/guidelines/responses#synchronous-error-response) Replaced by `errors` (plural and an `array`) 15 May 2024 \- `paymentType` in [`RatePlan`](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/configuration#rate-plan) returned by [Mews: Get configuration](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/configuration#get-configuration) May yield incorrect value. More info below (\*1). 16 May 2024 \- `channel` in [Mews: Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) Replaced by `sources` 26 Sep 2022 \- `iata` in [Company](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#company) in [Mews: Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) Replaced by `iata` in the [Travel Agency](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#travel-agency) object 26 Sep 2022 \- `adultCount` and `childCount` in [`Reservation`](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#reservation) object in [Mews: Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) Replaced by `guestCounts`; **Requires re-certification** 29 Apr 2022 \- `code` in [`Payment card`](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#payment-card) object in [Mews: Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) Replaced by `type` 08 Mar 2018 End Apr 2018 `accessToken` in all API calls on both Mews side and CHM side Replaced by `clientToken` 10 Jan 2018 End Mar 2018 `connectionCode` in all API calls on both Mews side and CHM side Replaced by `connectionToken` 10 Jan 2018 End Mar 2018 `code` in [`Connection Info`](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/configuration#connection-info) object in [Mews: Get properties](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/configuration#get-properties) Replaced by `token` 10 Jan 2018 End Mar 2018 `distributor` in [`Reservation`](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#reservation) object in [Mews: Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) Replaced by `channel` 10 Jan 2018 End Mar 2018 > **(\*1) paymentType**: We are introducing enhancements that elevate settlement rules to the enterprise level, allowing them to be assigned either to a rate group or directly to a rate. Due to the complex nature of settlement rules, which can vary within a rate group, `paymentType` is now obsolete as the value may vary depending on reservation dates, which can't be reflected in this field. [](https://mews-systems.gitbook.io/channel-manager-api/deprecations#deprecated-functionality) Deprecated functionality --------------------------------------------------------------------------------------------------------------------------- Feature Comments Deprecated Discontinued [Error response codes](https://mews-systems.gitbook.io/channel-manager-api/guidelines/responses#error-codes) 4 and 5 Use codes 9 and 10 instead 11 Aug 2022 \- [PreviousCertification tests](https://mews-systems.gitbook.io/channel-manager-api/your-journey/certification-tests) [NextChangelog](https://mews-systems.gitbook.io/channel-manager-api/changelog) Last updated 8 months ago Was this helpful? --- # Your integration journey | Channel Manager API For a general overview and step-by-step guide to the integration process for all **Mews Open API** integrations, see [Your journey with Mews](https://mews-systems.gitbook.io/open-api/your-journey) . This page provides guidance specific to integrating with the **Mews Channel Manager API**. [](https://mews-systems.gitbook.io/channel-manager-api/your-journey#step-1-exploration) Step 1: Exploration ---------------------------------------------------------------------------------------------------------------- Before you begin, review the documentation to understand the available API Operations and their uses: * [API Operations (Mews)](https://mews-systems.gitbook.io/channel-manager-api/mews-operations) * [API Operations (CHM)](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations) [](https://mews-systems.gitbook.io/channel-manager-api/your-journey#step-2-registration) Step 2: Registration ------------------------------------------------------------------------------------------------------------------ To register your integration, follow the process outlined in the main onboarding guide [Your journey with Mews](https://mews-systems.gitbook.io/open-api/your-journey) . **Obtain your Client Token**: Once approved, you will receive a `Client Token` that uniquely identifies your application. This token remains the same across all properties but differs by environment (i.e. Demo vs. Production). [](https://mews-systems.gitbook.io/channel-manager-api/your-journey#step-3-development) Step 3: Development ---------------------------------------------------------------------------------------------------------------- ### [](https://mews-systems.gitbook.io/channel-manager-api/your-journey#channel-manager-system-setup) Channel Manager system setup 1. **Set up inbound endpoints** Prepare your Channel Manager-side API endpoints to accept requests from Mews, using the same `Client Token` provided for Mews-side authentication. > While you can use a different token, we recommend using the same one for simplicity. 1. **Share your endpoints with Mews** Send Mews the endpoint URLs for each supported Channel Manager API Operation. > You can submit the URLs incrementally during development. Production URLs can be shared later if preferred. ### [](https://mews-systems.gitbook.io/channel-manager-api/your-journey#property-connection-for-testing) Property connection for testing For testing in the [Demo environment](https://mews-systems.gitbook.io/channel-manager-api/guidelines/environments) , Mews integration specialists will handle the connection setup to a test property. To understand how property connections work in general, see [Connecting a property](https://mews-systems.gitbook.io/channel-manager-api/your-journey#connecting-a-property) . [](https://mews-systems.gitbook.io/channel-manager-api/your-journey#step-4-certification) Step 4: Certification -------------------------------------------------------------------------------------------------------------------- Before going live in Production, your integration must be certified by Mews. The process depends on your registration pathway: * **Partner Portal:** Log in and go to **Integrations** → **Certify Existing Applications**. * **No Partner Portal access:** Complete the [Certification Form](https://mews.typeform.com/to/ehTUz7) . Learn more: * [Certification](https://mews-systems.gitbook.io/channel-manager-api/your-journey/certification) * [Certification tests](https://mews-systems.gitbook.io/channel-manager-api/your-journey/certification-tests) * [Channel API Certification: What to expect](https://help.mews.com/s/article/channel-api-certification-what-to-expect?language=en_US) [](https://mews-systems.gitbook.io/channel-manager-api/your-journey#step-5-go-live) Step 5: Go live -------------------------------------------------------------------------------------------------------- After successful certification: * You will receive a `Client Token` for the Production environment. * Mews will activate the connection at the agreed pilot property. * Your integration will be monitored for a short period (typically 4 weeks). Following a successful pilot, your integration can be published to other properties or listed on the [Mews Marketplace](https://www.mews.com/en/products/marketplace) (if public). For general support, visit the [Mews Help Center](https://help.mews.com/) . [](https://mews-systems.gitbook.io/channel-manager-api/your-journey#connecting-a-property) Connecting a property --------------------------------------------------------------------------------------------------------------------- To connect an individual property to your system, follow these steps: 1. **Create the connection in Mews**: A connection must first be established in Mews Operations. This can be done by the property. * All spaces and rates are automatically assigned default mapping codes. * If your system requires specific mapping codes, communicate them in advance so the property can adjust accordingly. 2. **Obtain the Connection Token**: The Connection Token identifies the specific link between the property and your system. You can get it in two ways: * Use the [Get properties](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/configuration#get-properties) API operation to retrieve all connections and identify new ones. * Or request the token directly from the property. 3. **Retreive the connection configuration**: Fetch the connection’s configuration to complete the setup: * Use the [Get configuration](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/configuration#get-configuration) API operation. * Or request configuration details manually from the property. 4. **Configure the connection**: Configure the connection on your channel manager system to finalize the integration. > **Demo environment**: For integrations in the [Demo environment](https://mews-systems.gitbook.io/channel-manager-api/guidelines/environments) > , Mews integration specialists handle all connection requests. [PreviousNotifications](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/notifications) [NextCertification](https://mews-systems.gitbook.io/channel-manager-api/your-journey/certification) Last updated 5 months ago Was this helpful? --- # Usage guidelines | Channel Manager API This section provides important guidelines on how to use the **Mews Channel Manager API**. Unless specified otherwise, the guidelines apply to both the Mews side of the API and the Channel Manager side of the API. For information on the partner journey and on the certification process, see [Your integration journey](https://mews-systems.gitbook.io/channel-manager-api/your-journey) . For information about individual endpoints or operations, see [API Operations (Mews)](https://mews-systems.gitbook.io/channel-manager-api/mews-operations) and [API Operations (CHM)](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations) . > #### > > [](https://mews-systems.gitbook.io/channel-manager-api/guidelines#terminology) > > Terminology > > We use the term _Property_ to describe the hotel, hostel or other enterprise; we use the term _Space_ to refer to a hotel room, dormitory bed or other type of bookable space, and _Space Type_ to refer to the category of _Space_ offered by the _Property_. Although typically a room in a hotel, this could be for example a squash court in a sports facility. For a full description of all the terms used in the API, see the [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) > . [](https://mews-systems.gitbook.io/channel-manager-api/guidelines#contents) Contents ----------------------------------------------------------------------------------------- * [Authentication](https://mews-systems.gitbook.io/channel-manager-api/guidelines/authentication) Details of how API Operation requests are authenticated. * [Requests](https://mews-systems.gitbook.io/channel-manager-api/guidelines/requests) Details of how to make API Operation requests. * [Responses](https://mews-systems.gitbook.io/channel-manager-api/guidelines/responses) Details of API Operation responses, including error messages. * [Environments](https://mews-systems.gitbook.io/channel-manager-api/guidelines/environments) A description of the different environments available and how to access them. * [Compliance](https://mews-systems.gitbook.io/channel-manager-api/guidelines/compliance) Information about PCI compliance. [PreviousMews Channel Manager API](https://mews-systems.gitbook.io/channel-manager-api) [NextAuthentication](https://mews-systems.gitbook.io/channel-manager-api/guidelines/authentication) Last updated 11 months ago Was this helpful? --- # API Operations (Mews) | Channel Manager API This section describes the Mews side of the **Mews Channel Manager API**, i.e. API Operations hosted by Mews. The Mews side receives requests from external Channel Managers, including requests to process reservations (new, updated and cancelled). The list of supported operations is as follows, organised here by theme. [](https://mews-systems.gitbook.io/channel-manager-api/mews-operations#configuration) Configuration -------------------------------------------------------------------------------------------------------- Operation Description [Get properties](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/configuration#get-properties) Get the list of available properties and their connection details [Get configuration](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/configuration#get-configuration) Get the configuration of the given property connection [Get channels](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/configuration#get-channels) Get the list of all channels with assigned mapping codes [](https://mews-systems.gitbook.io/channel-manager-api/mews-operations#inventory) Inventory ------------------------------------------------------------------------------------------------ Operation Description [Set inventory](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/inventory#set-inventory) Update the 'rate plan - space type' inventory mapping [Request ARI update](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/inventory#request-ari-update) \[`async`\] Request an ARI data update for certain space types and rate plans (ARI is `Availability, Rates and Inventory`) [Confirm availability update](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/inventory#confirm-availability-update) Confirms availability update was processed succesfully or with errors. [Confirm price update](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/inventory#confirm-price-update) Confirms price update was processed succesfully or with errors. [Confirm restriction update](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/inventory##confirm-reistriction-update) Confirms restriction update was processed succesfully or with errors. [Confirm availability block synchronization](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock##confirm-availability-block-confirmation) Confirms availability block synchronization was processed succesfully or with errors. [Process availability block](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#process-availability-block) Add, update or cancel an availability block. [](https://mews-systems.gitbook.io/channel-manager-api/mews-operations#reservations) Reservations ------------------------------------------------------------------------------------------------------ Operation Description [Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) \[`async`\] Process a group of reservations, which can be new bookings, modifications or cancellations. [Confirm reservations group synchronization](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#confirm-group-confirmation) Confirms reservations group synchronization was processed succesfully or with errors. [PreviousInventory updates](https://mews-systems.gitbook.io/channel-manager-api/use-cases/inventory-updates) [NextConfiguration](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/configuration) Last updated 11 months ago Was this helpful? --- # API Operations (CHM) | Channel Manager API This section describes the Channel Manager side of the **Mews Channel Manager API**, i.e. API Operations hosted by the Channel Manager. The Channel Manager side receives requests from Mews, including inventory updates (prices, availability and restrictions) and booking confirmations. The list of supported operations is as follows, organised here by theme. > #### > > [](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations#inventory-update-modes) > > Inventory update modes > > Mews pushes inventory to the Channel Manager side in one of two modes, both using the same API Operations, either **Full Inventory Update Mode** or **Delta Inventory Update Mode**. For more information, see [Use cases > Inventory updates](https://mews-systems.gitbook.io/channel-manager-api/use-cases/inventory-updates) > . [](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations#inventory) Inventory ----------------------------------------------------------------------------------------------------------- Operation Description [Update prices](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/inventory#update-prices) This method is used when Mews updates prices of rate plans [Update availability](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/inventory#update-availability) This method is used when Mews updates availability of space types [Update restrictions](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/inventory#update-restrictions) This method is used when Mews updates restrictions [Process availability block](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/availabilityblock) This method is used when Mews sends availability blocks [](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations#reservations) Reservations ----------------------------------------------------------------------------------------------------------------- Operation Description [Process group](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/reservations#process-group) \[`async`\] Process a group of reservations, which can be new bookings, modifications or cancellations. [Confirm booking](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/reservations#confirm-booking) This method is used when Mews confirms a booking sent via [Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) [](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations#notifications) Notifications ------------------------------------------------------------------------------------------------------------------- Operation Description [Change notification](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/notifications#change-notification) This operation is used by Mews to notify the channel manager when there is a change in the connection configuration [PreviousReservations](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations) [NextAvailability blocks](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/availabilityblock) Last updated 11 months ago Was this helpful? --- # Changelog | Channel Manager API [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-25th-july-2025) 25th July 2025 ------------------------------------------------------------------------------------------------------- * [CHM: Process group](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/reservations#process-group) : * Extended request object with new `booker` property. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-29th-may-2025) 29th May 2025 ----------------------------------------------------------------------------------------------------- * Further refinements to the partner journey, including [Your integration journey](https://mews-systems.gitbook.io/channel-manager-api/your-journey) and [Environments](https://mews-systems.gitbook.io/channel-manager-api/guidelines/environments) . Documentation-only, no change to API. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-16th-april-2025) 16th April 2025 --------------------------------------------------------------------------------------------------------- * Minor refinements to [Your integration journey](https://mews-systems.gitbook.io/channel-manager-api/your-journey) and [Certification](https://mews-systems.gitbook.io/channel-manager-api/your-journey/certification) pages. Documentation-only, no changes to API. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-15th-april-2025) 15th April 2025 --------------------------------------------------------------------------------------------------------- * [Mews: Process availability block](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#process-availability-block) : * Extended [Rate](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#rate) object with `occupancyAdjustments` property to specify extra occupancy adjustments for various age categories. * Improvements to [Your integration journey](https://mews-systems.gitbook.io/channel-manager-api/your-journey) and [Certification](https://mews-systems.gitbook.io/channel-manager-api/your-journey/certification) pages. Documentation-only, no changes to API. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-17th-march-2025) 17th March 2025 --------------------------------------------------------------------------------------------------------- * [Mews: Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) : * Extended request object with new `booker` property. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-12th-march-2024) 12th March 2024 --------------------------------------------------------------------------------------------------------- * [Mews: Process availability block](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#process-availability-block) : * Extended request object with `paymentCard` property. * Extended [Rate](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#rate) object with `prices` property to specify occupancy-based prices. * **Deprecated** `grossAmount` property in the [Rate](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#rate) object. Use `prices` instead. * **Breaking!** Endpoint URL changed to be sent via PCI proxy. **You must update the URL used for this operation**. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-13th-december-2024) 13th December 2024 --------------------------------------------------------------------------------------------------------------- * Refresh of entire site. Documentation-only, no changes to API. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-7th-november-2024) 7th November 2024 ------------------------------------------------------------------------------------------------------------- * [Mews: Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) – added recommended limit of 100 reservations per group. Documentation-only. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-4th-november-2024) 4th November 2024 ------------------------------------------------------------------------------------------------------------- * Deprecated `loyaltyCode` in [Mews: Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) . This is replaced by `loyaltyInfo`. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-11th-october-2024) 11th October 2024 ------------------------------------------------------------------------------------------------------------- * [Mews: Process availability block](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#process-availability-block) – Added `Rolling` to release strategy type; added `offset` property to release strategy object, and updated contract and description for `fixedDate` property (NOT a breaking change) * [CHM: Process availability block](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/availabilityblock) – Added `releasedStrategy` property to availability block object and deprecated `releasedDate` property – see [Deprecations](https://mews-systems.gitbook.io/channel-manager-api/deprecations) . [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-10th-october-2024) 10th October 2024 ------------------------------------------------------------------------------------------------------------- * [Availability block](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/availabilityblock#availability-block) extended with `pickupType` field. * [Availability block](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#availability-block) extended with `pickupType` field. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-8th-october-2024) 8th October 2024 ----------------------------------------------------------------------------------------------------------- * New operation [Mews: Process availability block](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/availabilityblock#process-availability-block) . [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-4th-october-2024) 4th October 2024 ----------------------------------------------------------------------------------------------------------- * [CHM: Update prices](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/inventory) extended with `dependent rates`. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-2nd-oct-2024) 2nd Oct 2024 --------------------------------------------------------------------------------------------------- * Updated [Usage guidelines](https://mews-systems.gitbook.io/channel-manager-api/guidelines#channels) to advise how to add new sales channels or sources through the API. Documentation-only. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-11th-september-2024) 11th September 2024 ----------------------------------------------------------------------------------------------------------------- * [Restrictions](https://mews-systems.gitbook.io/channel-manager-api/concepts/restrictions) explanations re-written and moved to new section [Concepts](https://mews-systems.gitbook.io/channel-manager-api/concepts) . [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-25th-july-2024) 25th July 2024 ------------------------------------------------------------------------------------------------------- * Moved integration process documentation into new section [Your integration journey](https://mews-systems.gitbook.io/channel-manager-api/your-journey) . Documentation-only. * Added [Re-certification](https://mews-systems.gitbook.io/channel-manager-api/your-journey/certification#re-certification) to the [Certification](https://mews-systems.gitbook.io/channel-manager-api/your-journey/certification) page. Documentation-only. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-23rd-july-2024) 23rd July 2024 ------------------------------------------------------------------------------------------------------- * Re-worded [error code](https://mews-systems.gitbook.io/channel-manager-api/guidelines/responses#error-codes) descriptions for improved clarity, and updated [Certification Error Tests](https://mews-systems.gitbook.io/channel-manager-api/your-journey/certification-tests#error-tests) . Documentation-only. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-24th-june-2024) 24th June 2024 ------------------------------------------------------------------------------------------------------- * [Availability block](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/availabilityblock#availability-block) extended with `notes` field. * [Loyalty info](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#loyalty-info) extended with `tierCode` field. * [Reservation](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#reservation) extended with `timeState` field and [`paymentCardData`](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#payment-card-data) object. Note these properties are only used by [CHM: Process group](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/reservations#process-group) , _not_ by [Mews: Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) . * Correction: Minor corrections to examples in [CHM: Process group](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/reservations#process-group) and [Mews: Process group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) . * Correction: `paymentType` removed from Request in [CHM: Process group](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/reservations#process-group) . This is only used on the Mews side. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-16th-may-2024) 16th May 2024 ----------------------------------------------------------------------------------------------------- * Clarified [Synchronous error response](https://mews-systems.gitbook.io/channel-manager-api/guidelines/responses#synchronous-error-response) * Deprecated `error` (singular) in [Synchronous error response](https://mews-systems.gitbook.io/channel-manager-api/guidelines/responses#synchronous-error-response) , use `errors` (plural, array) instead. See [Deprecations](https://mews-systems.gitbook.io/channel-manager-api/deprecations) * Deprecated `paymentType` in [`RatePlan`](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/configuration#rate-plan) , see [Deprecations](https://mews-systems.gitbook.io/channel-manager-api/deprecations) . [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-19th-april-2024) 19th April 2024 --------------------------------------------------------------------------------------------------------- * Clarified dates in ARI pushes, Availability blocks and Reservation Push and delivery. [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-11th-april-2024) 11th April 2024 --------------------------------------------------------------------------------------------------------- * Added loyalty info to Request in [CHM: Process Availability block](https://mews-systems.gitbook.io/channel-manager-api/channel-manager-operations/availabilityblock#availability-block) . [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-26th-march-2024) 26th March 2024 --------------------------------------------------------------------------------------------------------- * Minor changes to highlight the need for re-certification when replacing deprecated features, see [Deprecations](https://mews-systems.gitbook.io/channel-manager-api/deprecations) (documentation only) [](https://mews-systems.gitbook.io/channel-manager-api/changelog#id-9th-january-2024) 9th January 2024 ----------------------------------------------------------------------------------------------------------- * Added [Age Category Code](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#age-category-code) in [Mews: Process Group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) (documentation only). * Added explanations to [Mews: Process Group](https://mews-systems.gitbook.io/channel-manager-api/mews-operations/reservations#process-group) for the consequences of using negative extra product amounts (documentation only). Changelog by year [Changelog 2023](https://mews-systems.gitbook.io/channel-manager-api/changelog/changelog2023) [Changelog 2022](https://mews-systems.gitbook.io/channel-manager-api/changelog/changelog2022) [Changelog 2021](https://mews-systems.gitbook.io/channel-manager-api/changelog/changelog2021) [Changelog 2020](https://mews-systems.gitbook.io/channel-manager-api/changelog/changelog2020) [Changelog 2019](https://mews-systems.gitbook.io/channel-manager-api/changelog/changelog2019) [Changelog 2018](https://mews-systems.gitbook.io/channel-manager-api/changelog/changelog2018) [Changelog 2017](https://mews-systems.gitbook.io/channel-manager-api/changelog/changelog2017) [PreviousDeprecations](https://mews-systems.gitbook.io/channel-manager-api/deprecations) [NextChangelog 2023](https://mews-systems.gitbook.io/channel-manager-api/changelog/changelog2023) Last updated 4 months ago Was this helpful? --- # Mews Booking Engine Guide | Booking Engine Guide Welcome to the online documentation for the **Mews Booking Engine**. We're here to guide you through the process of integrating the Mews Booking Engine into your website, so your guests can create reservations in your properties directly in **Mews Operations**. You can do this in one of three ways: * [Booking Engine Standalone](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-standalone) Redirect to a standalone booking page hosted by Mews * [Booking Engine Widget](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget) Embed a JavaScript widget into your own website * [Booking Engine API](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api) Create your own custom booking engine using the Booking Engine API Not sure which option is right for you? See [Ways to integrate](https://mews-systems.gitbook.io/booking-engine-guide/faq/ways-to-integrate) . If you need further assistance, or have any questions or special requests, please open a ticket from Mews Operations via our Mews Digital Assistant. > #### > > [](https://mews-systems.gitbook.io/booking-engine-guide#terminology) > > Terminology > > You may see reference to the term _Distributor_, either in the Guide, in URLs or in code snippets, this is the old name for the _Mews Booking Engine_ before it was re-branded. So if you see _Distributor_, this is synonymous with _Mews Booking Engine_. For a full description of all the terms used in the Guide, see the [Mews Glossary for Open API users](https://help.mews.com/s/article/Mews-Glossary-for-Open-API-users?language=en_US) > . > #### > > [](https://mews-systems.gitbook.io/booking-engine-guide#changes-to-this-guide) > > Changes to this Guide > > * For the history of changes to the Guide, see the [Changelog](https://mews-systems.gitbook.io/booking-engine-guide/changelog) > > * For important information on deprecations in the API, see [Deprecations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/deprecations) > > * To track changes and updates to any part of the Guide, you can follow the [GitHub repository](https://github.com/MewsSystems/gitbook-booking-engine/tree/master) > [NextBooking Engine Standalone](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-standalone) Last updated 1 year ago Was this helpful? --- # Booking Engine Standalone | Booking Engine Guide Booking Engine Standalone is a version of the Booking Engine hosted by Mews. It's the simplest way to connect your website with a booking engine, enabling your guests to make direct bookings in your properties. This section describes how to use it. * [Getting started](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-standalone/getting-started) * [Deeplinks](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-standalone/deeplinks) [PreviousMews Booking Engine Guide](https://mews-systems.gitbook.io/booking-engine-guide) [NextGetting started](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-standalone/getting-started) Last updated 2 years ago Was this helpful? --- # FAQ | Booking Engine Guide Here we address some Frequently Asked Questions concerning the Mews Booking Engine integration. * [Which method should I use to integrate?](https://mews-systems.gitbook.io/booking-engine-guide/faq#which-method-should-i-use-to-integrate) * [Where can I get Configuration ID?](https://mews-systems.gitbook.io/booking-engine-guide/faq#where-can-i-get-configuration-id) * [Why doesn't the Booking Engine use the Configuration IDs I've provided?](https://mews-systems.gitbook.io/booking-engine-guide/faq#why-doesnt-the-booking-engine-use-the-configuration-ids-ive-provided) * [Where can I get City ID?](https://mews-systems.gitbook.io/booking-engine-guide/faq#where-can-i-get-city-id) * [Where can I get Age Category ID?](https://mews-systems.gitbook.io/booking-engine-guide/faq#where-can-i-get-age-category-id) [](https://mews-systems.gitbook.io/booking-engine-guide/faq#which-method-should-i-use-to-integrate) Which method should I use to integrate? ------------------------------------------------------------------------------------------------------------------------------------------------ See [Ways to integrate](https://mews-systems.gitbook.io/booking-engine-guide/faq/ways-to-integrate) . [](https://mews-systems.gitbook.io/booking-engine-guide/faq#where-can-i-get-configuration-id) Where can I get Configuration ID? ------------------------------------------------------------------------------------------------------------------------------------ The Booking Engine Configuration ID is a unique identifier for your particular Booking Engine implementation. You can find it in **Mews Operations**. * Start on the **Dashboard** (the main screen). * In the left-hand menu, select **Settings** -> **Services**. * In the section **Bookable services**, select the service which has the Booking Engine configuration. If there's just one service, select that one. * On the left, select **Booking engines**. * Select the configuration you want to use. * In the upper section there is a field **Identifier**. This is your Configuration ID. It has the format `aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`. ![](https://mews-systems.gitbook.io/booking-engine-guide/~gitbook/image?url=https%3A%2F%2F3292240558-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FtIc30XOAP46ahd8X73va%252Fuploads%252Fgit-blob-81c9875a1f24a7148ab82076b5214d5acbada394%252Fcommander-configuration-id.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=2d5eff0b&sv=2) Configuration ID in Mews Operations [](https://mews-systems.gitbook.io/booking-engine-guide/faq#why-doesnt-the-booking-engine-use-the-configuration-ids-ive-provided) Why doesn't the Booking Engine use the Configuration IDs I've provided? -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If the Booking Engine is not using the Configuration IDs provided, it could be that some of those IDs are not valid Configuration IDs. Please check that: * All used Configuration IDs are really Configuration IDs, not chain, enterprise or other IDs * All used Configuration IDs are defined in **Mews Operations** from the same [environment](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/environments) as the Booking Engine you are using. * You are using only one Configuration ID per enterprise. [](https://mews-systems.gitbook.io/booking-engine-guide/faq#where-can-i-get-city-id) Where can I get City ID? ------------------------------------------------------------------------------------------------------------------ You can find the Mews City ID in **Mews Operations**: * Start on the **Dashboard** (the main screen). * In the left-hand menu, select **Settings** -> **Services**. * In the section **Bookable services**, select the service which has the Booking Engine configuration. If there's just one service, select that one. * On the left, select **Booking engines**. * Select the configuration you want to use. * In the upper section there ia a field **City Identifier**. This is your City ID. It has a format `aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`. ![](https://mews-systems.gitbook.io/booking-engine-guide/~gitbook/image?url=https%3A%2F%2F3292240558-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FtIc30XOAP46ahd8X73va%252Fuploads%252Fgit-blob-1968fcc9e08bbfffb38f7e719cde1d1293054e05%252Fcommander-city-id.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=d47e8b22&sv=2) City ID in Mews Operations [](https://mews-systems.gitbook.io/booking-engine-guide/faq#where-can-i-get-age-category-id) Where can I get Age Category ID? ---------------------------------------------------------------------------------------------------------------------------------- You can find the AgeCategory ID in **Mews Operations**: * Start on the **Dashboard** (the main screen). * In the left-hand menu, select **Settings** -> **Services**. * In the section **Bookable services**, select the service which has the Booking Engine configuration. If there's just one service, select that one. * On the left, select **Age categories**. * Select the age category you want. * In the URL there is an ID at the end, right after `/Detail/`. This is the age category ID. It has the format `aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`. ![](https://mews-systems.gitbook.io/booking-engine-guide/~gitbook/image?url=https%3A%2F%2Fgithub.com%2FMewsSystems%2Fgitbook-booking-engine%2Fassets%2F22661032%2F8d69a7ad-d641-4021-b9f1-788c9bb07df0&width=768&dpr=4&quality=100&sign=446619ac&sv=2) ageCategoryId [PreviousGoogle Analytics cross-domain tracking](https://mews-systems.gitbook.io/booking-engine-guide/integrations/ga-cross-domain-tracking) [NextWays to integrate](https://mews-systems.gitbook.io/booking-engine-guide/faq/ways-to-integrate) Last updated 1 year ago Was this helpful? --- # Changelog | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/changelog#id-31st-october-2025) 31st October 2025 -------------------------------------------------------------------------------------------------------------- * Integrations: Added `reservationOwnerEmail` field to GTM purchase event in [Google Triggers Reference](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#purchase) . This field provides the email address of the reservation owner and requires booking engine configuration to be enabled. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog#id-29th-august-2025) 29th August 2025 ------------------------------------------------------------------------------------------------------------ * API: [Get services pricing](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#get-services-pricing) * Added `OccupancyData` request parameter. * Clarified the default behavior of `OccupancyPrices` property in [Category price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#category-price) response object. Documentation-only, no change to the API. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog#id-16th-july-2025) 16th July 2025 -------------------------------------------------------------------------------------------------------- * API: [Get promoted services](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#get-promoted-services) * Added new operation (restricted). [](https://mews-systems.gitbook.io/booking-engine-guide/changelog#id-10th-february-2025) 10th February 2025 ---------------------------------------------------------------------------------------------------------------- * API: Renamed and rewritten [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) page, and other small changes. Documentation-only, no change to the API. Changelog by year [Changelog 2024](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2024) [Changelog 2023](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2023) [Changelog 2022](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2022) [Changelog 2021](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021) [Changelog 2020](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020) [PreviousMigration off the mews.li domain](https://mews-systems.gitbook.io/booking-engine-guide/faq/mews-li-migration) [NextChangelog 2024](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2024) Last updated 19 days ago Was this helpful? --- # Usage guidelines | Booking Engine Guide This section provides guidelines and general information on how to use the **Mews Booking Engine API**. For information about individual endpoints or operations, see [API Operations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations) . > **Important:** The Mews Booking Engine API is designed to be consumed directly by front-end clients. It is unsuitable for continuous polling by a single server due to its built-in anti-scraping protection and such requests can fail. For server to server communication, please refer to the [Mews Connector API](https://mews-systems.gitbook.io/connector-api/) > . * [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) * [Requests](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/requests) * [Responses](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/responses) * [Environments](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/environments) * [Images](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/images) * [Supported currency codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-currency-codes) * [Supported language codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-language-codes) [PreviousBooking Engine API](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api) [NextAuthentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) Last updated 9 months ago Was this helpful? --- # Booking Engine Widget | Booking Engine Guide The Booking Engine JavaScript Widget allows guests to book directly from the website of your property without being redirected elsewhere. It's a more advanced way of integrating the Mews Booking Engine into your website. This section describes how to use it. * [Getting started](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started) * [Use cases](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/use-cases) * [Advanced Guide](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/advanced-guide) * [Reference](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference) * [Troubleshooting](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/troubleshooting) [PreviousDeeplinks](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-standalone/deeplinks) [NextGetting started](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started) Last updated 1 year ago Was this helpful? --- # Integrations | Booking Engine Guide The Booking Engine Widget supports direct integration with [Google Tag Manager](https://marketingplatform.google.com/about/tag-manager/) and [Google Analytics](https://marketingplatform.google.com/about/analytics/) . The integration with Google Tag Manager is intended only to serve data to Google Analytics. > #### > > [](https://mews-systems.gitbook.io/booking-engine-guide/integrations#disclaimer-regarding-google-analytics-data-accuracy) > > 🚨 Disclaimer regarding Google Analytics data accuracy > > We understand that some property owners have expressed concerns about discrepancies between the data they see in Google Analytics (GA) and the actual reality. It’s essential to be aware of the following factors: > > **Ad Blockers impact** > > * Approximately 33% of internet users utilize ad blockers, which can block Google Analytics and Google Tag Manager (GTM) scripts. See for example this article for a reference: [https://backlinko.com/ad-blockers-users](https://backlinko.com/ad-blockers-users) > . > > * Consequently, the data received from these services may not be 100% accurate. > > * Metrics such as revenue and the number of bookings may appear lower than the actual figures, due to ad-blocking behavior. > > > **Consent and tracking** > > * If a guest declines cookies or tracking, their interactions won’t be tracked in Google Analytics. > > > Please remember to address these considerations when interpreting GA data and making business decisions. * [Google Tag Manager](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-tag-manager) * [Google Triggers Reference](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference) * [Google Tag Manager - Configuration](https://mews-systems.gitbook.io/booking-engine-guide/integrations/gtm-skeleton) * [Google Analytics cross-domain tracking](https://mews-systems.gitbook.io/booking-engine-guide/integrations/ga-cross-domain-tracking) [PreviousDeprecations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/deprecations) [NextGoogle Tag Manager](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-tag-manager) Last updated 1 year ago Was this helpful? --- # Deprecations | Booking Engine Guide Deprecations are features of the API which you are discouraged from using, even though they may still be supported for a period of time for the sake of backwards compatibility. Such features are normally deprecated because they are superseded by a better alternative. They can include object properties or entire API operations. The list of deprecations is as follows. Individual items are also highlighted in the [Changelog](https://mews-systems.gitbook.io/booking-engine-guide/changelog) when they occur. Historic deprecations that have already been discontinued may not be listed. **For more information, see our** [**Deprecations Policy**](https://mews-systems.gitbook.io/open-api/staying-up-to-date/deprecations-policy) **.** > **Important:** We strongly advise you to review this list and if you are using any of the deprecated items in your integration, to update your implementation accordingly. The table columns have the following meanings: * **Object** - JSON data object containing the deprecated field or property * **Property** - Field or property which is deprecated * **Replaced by** - What the replacement is, if applicable * **Context** - The context in which the property is used, usually the API operation * **Deprecated** - The date at which the deprecation notice was given (see the [Changelog](https://mews-systems.gitbook.io/booking-engine-guide/changelog) ) * **Discontinued** - The date at which it is planned to discontinue the feature completely; a value of '-' indicates no date has been set [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/deprecations#deprecated-object-properties) Deprecated object properties ------------------------------------------------------------------------------------------------------------------------------------------------------- Object Property Replaced by Context Deprecated Discontinued [Room occupancy availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-occupancy-availability) `AdultCount`, `ChildCount` [OccupancyData](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-occupancy-availability) [Get availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-availability) 18 Mar 2024 \- Request object `AdultCount`, `ChildCount` [OccupancyData](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-availability) [Get availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-availability) 18 Mar 2024 \- [Occupancy](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#occupancy) `AdultCount`, `ChildCount` [OccupancyData](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#occupancy) [Get reservations pricing](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#get-reservations-pricing) 18 Mar 2024 \- [Reservation](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#reservation) `AdultCount`, `ChildCount` [OccupancyData](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#reservation) [Get reservation price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#get-reservation-price) 18 Mar 2024 \- [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#amount) `TaxValues` [Breakdown](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#amount) [Get reservation price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#get-reservation-price) 19 Oct 2022 \- [Room category](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-category) `ImageIds` [Category image assignment](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#category-image-assignment) ([Get configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#get-configuration) ) [Get configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#get-configuration) , [Get hotels](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-hotels) 21 Oct 2021 \- [Room price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-price) `AverageAmountPerNight` `AverageAmountPerTimeUnit` [Get availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-availability) , [Get reservations pricing](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#get-reservations-pricing) 21 Jul 2021 \- [Rate group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#rate-group) `SettlementMaximumNights` `SettlementMaximumTimeUnits` [Get availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-availability) 21 Jul 2021 \- [Product](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product) `Charging` `ChargingMode` [Get hotels](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-hotels) , [Get configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#get-configuration) 21 Jul 2021 \- [Product](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product) `Posting` `PostingMode` [Get hotels](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-hotels) , [Get configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#get-configuration) 21 Jul 2021 \- [Product](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product) `Amounts`, `RelativePrice` `Pricing` [Get hotels](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-hotels) , [Get configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#get-configuration) 01 Jul 2021 \- [Configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#configuration-1) `PaymentCardInput` `PaymentCardRequirement` [Get configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#get-configuration) 18 Apr 2021 \- [PreviousVouchers](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/vouchers) [NextIntegrations](https://mews-systems.gitbook.io/booking-engine-guide/integrations) Last updated 9 months ago Was this helpful? --- # API Operations | Booking Engine Guide This section describes all operations supported by the API, organised by theme. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations#availability) Availability --------------------------------------------------------------------------------------------------------------------- Operation or Endpoint Description [Get availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-availability) Get availability and pricing options for the specified hotel for the specified date interval [Get availability blocks](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/availability-blocks#get-availability-blocks) Get details of the availability blocks for the given hotel. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations#configuration) Configuration ----------------------------------------------------------------------------------------------------------------------- Operation or Endpoint Description [Get configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#get-configuration) Get configuration data for the specified booking engine instances; this operation can be called initially to fetch data which may be important during the booking workflow [Get hotels](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-hotels) Get hotels data for a single specified hotel; this operation can be called initially to fetch data which may be important during the booking workflow [Get payment configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-payment-configuration) Fetch payment configuration parameters for the specified hotel [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations#payment-cards) Payment cards ----------------------------------------------------------------------------------------------------------------------- Operation or Endpoint Description [Get payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#get-payment-cards) Fetch details about the listed payment cards, in particular the Authorization state [Authorize payment card](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorize-payment-card) Request authorization of the specified payment card [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations#reservations) Reservations --------------------------------------------------------------------------------------------------------------------- Operation or Endpoint Description [Get reservations pricing](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#get-reservations-pricing) Get a price quotation for a specific hotel, date interval, room category and person count [Get reservation price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#get-reservation-price) Get final price of the specified reservations [Create reservation group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#create-reservation-group) Create a group of one or more reservations, i.e. make a reservation [Get reservation group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#get-reservation-group) Fetch details of the specified reservation group [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations#services) Services ------------------------------------------------------------------------------------------------------------- Operation or Endpoint Description [Get services availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#get-services-availability) Get availability for the specified service for each time unit in the specified date interval [Get services pricing](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#get-services-pricing) Get pricing for the specified service for each time unit in the specified date interval [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations#vouchers) Vouchers ------------------------------------------------------------------------------------------------------------- Operation or Endpoint Description [Validate voucher](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/vouchers#validate-voucher) Determine if the specified voucher code is valid or not [PreviousSupporting payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/supporting-payment-cards) [NextAvailability blocks](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/availability-blocks) Last updated 3 years ago Was this helpful? --- # Use cases | Booking Engine Guide This section describes how to use the Booking Engine API to implement some well-known scenarios. * [On session payments](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/on-session-payments) * [Payment card authorization](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/payment-card-authorization) * [Supporting payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/supporting-payment-cards) * [Availability blocks](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/availability-blocks) [PreviousSupported language codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-language-codes) [NextAvailability blocks](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/availability-blocks) Last updated 3 years ago Was this helpful? --- # Troubleshooting | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/troubleshooting#booking-engine-shows-an-error-api.mews.com-refused-to-connect) Booking Engine shows an error "api.mews.com refused to connect" --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/troubleshooting#fault-description) Fault description The browser says it can't open the page because of security, or there's a console error mentioning `api.mews.com` and `X-Frame-Options`. **Example 1 (Chrome browser):** ![](https://mews-systems.gitbook.io/booking-engine-guide/~gitbook/image?url=https%3A%2F%2F3292240558-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FtIc30XOAP46ahd8X73va%252Fuploads%252Fgit-blob-108fe5738d60aa9da9dc3705be53c575ed871b77%252Fapi-mews-com-refused-connect-chrome.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=8da369e5&sv=2) api.mews.com refused error Google Chrome **Example 2 (Firefox browser):** ![](https://mews-systems.gitbook.io/booking-engine-guide/~gitbook/image?url=https%3A%2F%2F3292240558-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FtIc30XOAP46ahd8X73va%252Fuploads%252Fgit-blob-a0fa6318ecedf3ba38f58ad414b78837d2754f8a%252Fapi-mews-com-refused-connect-firefox.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=2f13b3d1&sv=2) api.mews.com refused error Mozilla Firefox **Example 3 (Console errors):** * `[Error] Refused to display 'https://api.mews.com/distributor' in a frame because it set 'X-Frame-Options' to 'sameorigin'.` * `The loading of "https://api.mews.com/distributor" in a frame is denied by "X-Frame-Options" directive set to "sameorigin".` ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/troubleshooting#fault-explanation) Fault explanation The Booking Engine Widget is not working because it is not installed correctly on your page. Installing the Booking Engine Widget in any other way than as described in this Guide is not supported and can cause errors such as "api.mews.com refused to connect". You can try to confirm the Booking Engine Widget is not installed correctly by inspecting the DOM of the page, as follows: * Open the page with the Booking Engine Widget and make it show the error * Open your browser developer tools with 'DOM/elements inspector' * In the inspector, look for any tags like ` > **Warning:** Please double-check that you've added the script as instructed and followed all the requirements above. If the script tag is not used correctly, it can cause unexpected problems even when it seems everything is working. See [Disabling widget caching](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/use-cases/disable-widget-caching) ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started#content-security-policy) Content Security Policy If you have a Content Security Policy (CSP) set up on your website, the following domains should be enabled for the booking engine to function correctly: Copy *.mews.com https://www.recaptcha.net https://www.google.com/recaptcha/ https://recaptcha.google.com/recaptcha/ https://www.gstatic.com/recaptcha/ https://pay.datatrans.com/upp/payment/js/secure-fields-1.0.0.js The last URL (pay.datatrans.com) is for [PCI Proxy](https://www.pci-proxy.com/) , which is the secure, PCI-DSS compliant solution that is used by **Mews Payments** to process payment cards. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started#verifying-content-security-policy-configuration) Verifying Content Security Policy Configuration Once you have configured the Content Security Policy (CSP) for your website to include the necessary domains for the booking engine, it is crucial to ensure that the setup is correct to avoid any operational disruptions. Follow the steps below to verify the configuration: #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started#step-1-open-the-browser-console) Step 1: Open the Browser Console 1. **Access the Booking Engine Widget on your website:** Navigate through your website to the booking engine. 2. **Open Developer Tools:** Use the keyboard shortcut `Ctrl+Shift+I` (or `Cmd+Option+I` on Mac) to open the developer tools in your browser. 3. **Select the Console Tab:** Focus on the console tab to observe any errors that appear as you proceed through the booking steps. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started#step-2-simulate-a-booking) Step 2: Simulate a Booking 1. **Perform Test Transactions:** Go through all the steps of the booking engine, from selection to the checkout screen. 2. **Monitor for Errors:** Carefully monitor the console for any CSP-related errors, specifically looking for messages that indicate a refusal to load resources. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started#step-3-confirm-error-free-configuration) Step 3: Confirm Error-Free Configuration 1. **Check for 'Refused to Frame' Errors:** Ensure there are no errors such as `Refused to frame '_URL_' because it violates the following Content Security Policy directive: '....'`. Such errors suggest that the '\_URL\_' URL needs to be included in your CSP under the correct directive. 2. **Validate Functionality:** If no relevant CSP errors appear and the booking process completes successfully, your CSP is configured correctly. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started#critical-errors) Critical Errors Pay particular attention to any errors related to key functionalities such as reCAPTCHA and payment processing scripts, which are essential for booking security and integrity: * **reCAPTCHA:** Ensure domains related to Google’s reCAPTCHA are not blocked: Copy https://www.recaptcha.net https://www.google.com/recaptcha/ https://recaptcha.google.com/recaptcha/ https://www.gstatic.com/recaptcha/ * **Payment Processing:** Verify that the PCI Proxy script is allowed: Copy https://pay.datatrans.com/upp/payment/js/secure-fields-1.0.0.js This URL is critical for Mews Payments' PCI-DSS compliant processing capabilities via PCI Proxy. By following these steps, you can confirm that your Content Security Policy settings are correctly implemented, ensuring the booking engine operates smoothly and securely. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started#step-2-initialize-booking-engine-widget) Step 2: Initialize Booking Engine Widget ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ After the website has loaded, and the booking engine loader script has prepared the global `Mews.Distributor` object, you can initialize the Booking Engine Widget by calling global `Mews.Distributor` with some arguments. > **Warning:** Make sure you initialize the Booking Engine Widget by calling `Mews.Distributor` only _after_ the website is loaded, otherwise the initialization will fail or will not fully complete. The easiest way to achieve this is to place the initialization code inside a ` This call creates an isolated (iframe based) overlay on your website and loads the booking engine into it. > Note: The overlay and booking engine is not visible by default - we're going to solve this in the next section. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started#step-3-set-up-overlay-opening) Step 3: Set up overlay opening ---------------------------------------------------------------------------------------------------------------------------------------------------------------- To display the booking engine overlay, you should bind its opening to some action, e.g. clicking on a button. The booking engine can set this binding automatically for you, if you provide the second option `openElements` to `Mews.Distributor` and prepare the HTML elements which will be binded. You can find more information about `openElements` in the [Options Reference](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#options-reference) . The binding is delegated, so the elements and selectors don't need to exist during load of the website, but you still need to add the HTML elements yourself. Knowing that, you can for example add the following HTML button with class `distributor-open` (the class name we've used in the initialization code from the previous section), and it will open the Booking Engine Widget overlay upon a click: Copy This is just an example, the automatic binding can attach a click event listener to any HTML element. > Note: Closing of the booking engine is provided in the overlay by default, no configuration is needed from your side. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started#step-4-all-done) Step 4: All done! ------------------------------------------------------------------------------------------------------------------------------------- This is all you need for the basic setup of the Mews Booking Engine. Here's a summary of what you've done: * On the web page with this setup, the loader script will prepare `Mews.Distributor` * After the web page loads, your code will call `Mews.Distributor` - this will initialize the Booking Engine Widget, create an overlay (hidden for now) and bind opening actions to selected HTML elements such as buttons * When users click these HTML elements, the Booking Engine Widget overlay will open, and they can book through it * Users can close the overlay at any time and see your web page again [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started#use-callback-function-to-control-widget) Use callback function to control Widget ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- > This step is optional If you want to have a more customized setup, or you want to call some Javascript API functions on a booking engine instance to control it, you can provide a callback function as the second argument to the initialization call. This callback is later called asynchronously with an argument - booking engine instance. By calling methods on this instance you can control the booking engine. A very common example of this is using custom start and end date selectors that are part of your website and then passing the user’s selection to the booking engine - see [Using your own date inputs](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/use-cases/using-your-own-date-inputs) : Copy > Note: To see a list of all available Javascript API functions, please consult the Booking Engine Widget [Javascript API reference](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#javascript-api-reference) > . [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started#set-up-as-multi-enterprise) Set up as multi-enterprise --------------------------------------------------------------------------------------------------------------------------------------------------------- > This step is optional The booking engine can run in two basic modes - single enterprise or multiple enterprise. The mode is chosen automatically during initialization, based on the count of configuration ids you have provided in the options. Whenever two or more hotels are loaded, the booking engine will start in the multi-enterprise mode. That means that it will add one more step to the booking flow - hotel selection. To add more hotels, simply pass their Configuration IDs into the`configurationIds` array option, as follows. For details of how to obtain booking engine Configuration ID, see the [FAQ](https://mews-systems.gitbook.io/booking-engine-guide/faq#where-can-i-get-configuration-id) . Copy [PreviousBooking Engine Widget](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget) [NextUse cases](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/use-cases) Last updated 1 year ago Was this helpful? --- # Google Tag Manager Configuration | Booking Engine Guide This guide provides a streamlined process for exporting and configuring a Google Tag Manager (GTM) skeleton suitable for booking engine. Follow these precise steps to efficiently adapt your GTM setup to new requirements. [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/gtm-skeleton#prepare-your-configuration) Prepare your configuration --------------------------------------------------------------------------------------------------------------------------------------------- 1. **Download the configuration file:** * Access the prepared skeleton configuration file: [Google Tag Manager - Configuration.json](https://github.com/MewsSystems/gitbook-booking-engine/blob/master/.gitbook/assets/GTM-Mews.json) . 2. **IMPORTANT: Customize the configuration:** * Open the downloaded JSON file in your preferred text editor. * Replace all occurrences of `_GA4_ID_` with your actual Google Analytics 4 (GA4) tracking ID. 3. **Prepare for import:** * Save the changes to the JSON file, ensuring it is ready to be imported into your GTM account. [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/gtm-skeleton#import-configuration-into-google-tag-manager) Import configuration into Google Tag Manager --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/gtm-skeleton#import-the-modified-file) Import the modified file: * **Navigate to import options:** * In your GTM account, go to the **Admin** tab. * Under the container options, select **Import Container**. * **Select and upload file:** * Click on **Choose file** and select your modified JSON file. * Decide how to merge this configuration with any existing setup. Options include: * **Overwrite**: Replaces the current container with the imported one. * **Merge**: Combines the imported configuration with the existing one, with options to resolve conflicts. * **Rename**: Adds the imported configuration while renaming any conflicts. * **Complete the import:** * Follow prompts to finalize the import process. ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/gtm-skeleton#update-and-publish) Update and publish: * **Review configuration:** * Thoroughly check all tags, triggers, and variables to ensure they are correctly configured. * **Test before publishing:** * Utilize GTM's preview mode to test the setup. Ensure that all configurations perform as expected. * **Publish changes:** * Once verified, publish the container to apply your configurations live. [PreviousGoogle Triggers Reference](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference) [NextGoogle Analytics cross-domain tracking](https://mews-systems.gitbook.io/booking-engine-guide/integrations/ga-cross-domain-tracking) Last updated 9 months ago Was this helpful? --- # On session payments | Booking Engine Guide Whenever a user creates a reservation, there is an option to allow them to pay directly. This needs to be correctly configured via settlement rules on `RateGroup`. We provide this functionality only for `Rates` where the payment card is charged automatically at the time of creating the reservation. In order to simplify the whole payment processing workflow we offer this functionality in our applications via a feature called "Payment request". [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/on-session-payments#creating-a-reservation-group) Creating a reservation group ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ The first step of the entire workflow is to create a reservation group via the API, using [Create reservation group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#create-reservation-group) . The response contains a field `PaymentRequestId` which we will use for a redirect to an application that can handle the payment. The payment gateway supports an optional query parameter `returnUrl` which will be used to return the user into your booking engine after successful payment or in case the user decides to abandon the flow. The `returnUrl` value should be a Base64-encoded absolute URL, e.g. in JavaScript via the `btoa` function. After the user returns to your booking engine, you can verify the state of the payment request by calling [Get reservation group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#get-reservation-group) with `Extent` for `PaymentRequests` and optionally for `Payments` which you want to validate. Validation should be done mainly on the [Payment request state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-request-state) and optionally [Payment state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-state) . [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/on-session-payments#step-by-step-workflow) Step by step workflow ---------------------------------------------------------------------------------------------------------------------------------------------------------- 1. [Create reservation group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#create-reservation-group) . 2. Get `PaymentRequestId` from the response. 3. Create a `ReturnUrl`, encoding your URL with `Base64` e.g. JavaScript example would be `btoa(urlWhereUserShouldReturn)`. 4. Redirect the user to the gateway with URL `https://[MewsApplicationsBaseUrl]/navigator/payment-requests/detail/[PaymentRequestId]?returnUrl=[ReturnUrl]` (you can find the value of `MewsApplicationBaseUrl` in the [Environments](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/environments) section). 5. After the user returns to the `ReturnUrl` in your booking engine you can verify the state by using [Get reservation group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#get-reservation-group) with a specified [Reservation group extent](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#reservation-group-extent) . 6. Validate the state of the Payment request in the response. > **Note:** Until the Payment request enters its finite state (see [Payment request state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-request-state) > ) you can re-direct the user again, for example with a "Try to pay again" button. [PreviousAvailability blocks](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/availability-blocks) [NextPayment card authorization](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/payment-card-authorization) Last updated 3 years ago Was this helpful? --- # Payment cards | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#get-payment-cards) Get payment cards --------------------------------------------------------------------------------------------------------------------------------------------- Fetch details about the listed payment cards, in particular the Authorization state. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#request) Request `[ApiBaseUrl]/api/distributor/v1/paymentCards/getAll` Copy { "Client": "My Client 1.0.0", "PaymentCardIds": [\ "dc2f8608-9d71-47fd-9d41-ad1a009913c6"\ ] } Property Type Contract Description `PaymentCardIds` array of string required Unique identifiers of the [Payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#payment-card) . ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#response) Response Copy { "PaymentCards": [\ {\ "Id": "dc2f8608-9d71-47fd-9d41-ad1a009913c6",\ "AuthorizationState": "Authorizable"\ }\ ] } Property Type Contract Description `PaymentCards` array of [Payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#payment-card) required The payment cards. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#payment-card) Payment card Property Type Contract Description `Id` string required Unique identifier of the payment card. `AuthorizationState` string [Authorization state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorization-state) required Authorization state of the card. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorization-state) Authorization state * `Authorized` - Finite state. The payment card has been authorized. * `Authorizable` - Non-finite state. The payment card can be authorized. * `Unauthorizable` - Finite state. The payment card cannot be authorized. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorize-payment-card) Authorize payment card ------------------------------------------------------------------------------------------------------------------------------------------------------- Request authorization of the specified payment card. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#request-1) Request `[ApiBaseUrl]/api/distributor/v1/paymentCards/authorize` Copy { "Client": "My Client 1.0.0", "EnterpriseId": "8a51f050-8467-4e92-84d5-abc800c810b8", "PaymentCardId": "dc2f8608-9d71-47fd-9d41-ad1a009913c6", "BrowserInfo": { "ScreenWidth": 2560, "ScreenHeight": 1440, "ColorDepth": 24, "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.85 Safari/537.36", "Language": "cs", "JavaEnabled": false, "TimeZoneOffset": -120 } } Property Type Contract Description `EnterpriseId` string required Unique identifier of the enterprise which has access to the payment card. `PaymentCardId` string required Unique identifier of the payment card. `BrowserInfo` [Browser info](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#browser-info) required Information about the user's browser. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#browser-info) Browser info Property Type Contract Description `ScreenWidth` number required Integer value of the [user screen width](https://developer.mozilla.org/en-US/docs/Web/API/Screen/width) . `ScreenHeight` number required Integer value of the [user screen height](https://developer.mozilla.org/en-US/docs/Web/API/Screen/height) . `ColorDepth` number required Integer value of the [user screen color depth](https://developer.mozilla.org/en-US/docs/Web/API/Screen/colorDepth) . `UserAgent` string required Value of the browser [user agent](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorID/userAgent) . `Language` string required Value of the browser [language](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorLanguage/language) . `JavaEnabled` boolean required Value of the browser information on whether [Java is enabled](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorPlugins/javaEnabled) . This will always be `false`. `TimeZoneOffset` number required Integer value of the user [timezone offset](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTimezoneOffset) . ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#response-1) Response Copy { "Id": "94835eb5-24e1-421f-9915-ad1a009de562", "PaymentCardId": "dc2f8608-9d71-47fd-9d41-ad1a009913c6", "State": "Authorized" } Property Type Contract Description `Id` string required Unique identifier of the payment card authorization attempt. `PaymentCardId` string required Unique identifier of the payment card being authorized. `State` string [Authorization request state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorization-request-state) required State of the card authorization attempt. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorization-request-state) Authorization request state * `Authorized` - Finite state. The payment card authorization has been successfully completed. * `Requested` - Non-finite state. The payment card authorization is requested from the user. * `Pending` - Non-finite state. The payment card authorization is waiting to be requested from the user. * `Declined` - Finite state. The payment card authorization has been declined. * `Canceled` - Finite state. The payment card authorization has been canceled. [PreviousHotels](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels) [NextReservations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations) Last updated 3 years ago Was this helpful? --- # Changelog 2022 | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2022#id-13th-december-2022) 13th December 2022 ------------------------------------------------------------------------------------------------------------------------------ * API: Added [OpenAPI definition](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api#openapi-definition) [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2022#id-9th-november-2022) 9th November 2022 ---------------------------------------------------------------------------------------------------------------------------- * API: Changed [SettlementValue](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#rate-group) to optional field and added `SettlementFlatValue` property of absolute settlement amount [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2022#id-25th-october-2022) 25th October 2022 ---------------------------------------------------------------------------------------------------------------------------- * Widget: Added new [Google Analytics 4](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#google-analytics-4-ga4-events) documentation * Widget: Enhanced [Google Tag Manager (GTM)](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-tag-manager#google-tag-manager-gtm) documentation [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2022#id-20th-october-2022) 20th October 2022 ---------------------------------------------------------------------------------------------------------------------------- * API: Added new operation [Get services availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#get-services-availability) * API: Added new operation [Get services pricing](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#get-services-pricing) [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2022#id-19th-october-2022) 19th October 2022 ---------------------------------------------------------------------------------------------------------------------------- * API: Added new operation [Get reservation price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#get-reservation-price) [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2022#id-1st-july-2022) 1st July 2022 -------------------------------------------------------------------------------------------------------------------- * API: Added new operation [Get availability blocks](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/availability-blocks#get-availability-blocks) * API: `AvailabilityBlockId` property added to [Get availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-availability) , [Create reservation groups](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#create-reservation-groups) and [Get reservation pricing](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#get-reservation-pricing) * API: Added new [Availability Blocks Use Case](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/availability-blocks) * API: Added new [Supported currency codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-currency-codes) documentation. * API: Added new [Supported language codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-language-codes) documentation. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2022#id-7th-june-2022) 7th June 2022 -------------------------------------------------------------------------------------------------------------------- * General: Launch of **Mews Booking Engine Guide** at new URL [https://mews-systems.gitbook.io/booking-engine-guide/](https://mews-systems.gitbook.io/booking-engine-guide/) , based on the old Distributor Guide * Entire documentation re-structured and re-worded, for improved navigation and readability, and for consistency with other Mews APIs * Product re-branded from 'Distributor' to 'Mews Booking Engine' * No changes to API functionality [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2022#id-28th-march-2022) 28th March 2022 ------------------------------------------------------------------------------------------------------------------------ * API: Password for test environment changed to _Distributor-api1_ [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2022#id-18th-january-2022) 18th January 2022 ---------------------------------------------------------------------------------------------------------------------------- * Widget: Introduced new API methods to Distributor instance: [`setAdultCount`](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference) and [`setChildCount`](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference) . * Standalone: Introduced new deeplinks `mewsAdultCount` and `mewsChildCount` to set initial occupancy. Next [Changelog 2021](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021) [PreviousChangelog 2023](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2023) [NextChangelog 2021](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021) Last updated 1 year ago Was this helpful? --- # Supporting payment cards | Booking Engine Guide When creating a reservation, it is possible to attach a payment card to the reservation. As part of creating your own custom booking engine, you may want to have a form within your application where customers can enter their payment card data and send this data to the Booking Engine API for further use. Payment card data can then be used by Mews for charging the customer. To do that, some Booking Engine API operations support or require [Credit card data](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#credit-card-data) in the request. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/supporting-payment-cards#where-to-get-creditcarddata-values) Where to get `CreditCardData` values * Confirm that the hotel or property supports PCI Proxy by checking the field [Payment card storage type](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#payment-card-storage-type) in the configuration data returned from [Get hotels](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-hotels) . Also refer to the [Payment gateway](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#payment-gateway) documentation to see what other API data you could potentially use for your implementation. * Follow the [PCI Proxy Secure Fields](https://docs.pci-proxy.com/docs/secure-fields) guide to handle the sensitive card data and obtain `PaymentGatewayData`. Use [PublicKey](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#payment-gateway) as the `merchantId` while implementing PCI Proxy fields. * The PCI Proxy service will return a `transactionId` in the response which you use as `PaymentGatewayData` inside the [Credit card data](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#credit-card-data) object. * Once you have the `PaymentGatewayData`, you can create a payment card by providing [Credit card data](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#credit-card-data) in the request body. > **Production environment**: Note PCI Proxy documentation only highlights the sandbox endpoints, used for the staging environment. For the production environment, omit the `sandbox.` part from the address. For example, `https://pay.sandbox.datatrans.com/upp/payment/js/secure-fields-2.0.0.min.js` becomes `https://pay.datatrans.com/upp/payment/js/secure-fields-2.0.0.min.js`. [PreviousPayment card authorization](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/payment-card-authorization) [NextAPI Operations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations) Last updated 2 years ago Was this helpful? --- # Availability blocks | Booking Engine Guide Availability blocks are fixed sets of inventory set aside from public availability for private groups such as wedding parties, travel agencies or corporate clients. If you have access to these private blocks, you can use them in the API. To use an availability block, you will need to obtain its `availabilityBlockId`. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/availability-blocks#how-to-obtain-availability-block-id) How to obtain availability block ID -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can obtain a unique availability block ID from the Availability Blocks screen in **Mews Operations**, under 'Booking engine link'. Multiple IDs can be created, in case you have multiple booking engine instances. > Note: This functionality requires the property to have an _Enterprise subscription_. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/availability-blocks#how-to-work-with-availability-blocks) How to work with availability blocks ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Use [Get availability blocks](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/availability-blocks#get-availability-blocks) to fetch details about your availability block. Check that the current date is between `StartUtc` and `EndUtc` to see if the availability block is valid, or the block has expired. Then you can supply `availabilityBlockId` into all the API operations that accept it (see below). To get the appropriate rate, filter [Rates](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#rate) with the `rateId` from the fetched availability block details. Only this rate should be available and bookable for this booking engine session. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/availability-blocks#endpoints-accepting-availability-block-id) Endpoints accepting availability block ID * [Get availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-availability) * [Get reservations pricing](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#get-reservations-pricing) * [Create reservation group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#create-reservation-group) [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/availability-blocks#further-information) Further information ------------------------------------------------------------------------------------------------------------------------------------------------------ For more information about availability blocks, the following guide may be helpful. You can also use the Search function to find other suitable content in the Mews Help system. * [Creating availability blocks](https://help.mews.com/s/article/Creating-availability-blocks-in-Mews?language=en_US) [PreviousUse cases](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases) [NextOn session payments](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/on-session-payments) Last updated 3 years ago Was this helpful? --- # Changelog 2021 | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-29th-november-2021) 29th November 2021 ------------------------------------------------------------------------------------------------------------------------------ * API: Changed domain from www.mews.li to api.mews.com * Standalone: Changed domain from www.mews.li to api.mews.com * Widget: Changed domain from www.mews.li to api.mews.com [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-19th-november-2021) 19th November 2021 ------------------------------------------------------------------------------------------------------------------------------ * Widget: Removed `distributorBedOccupancyChanged` event trigger. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-9th-november-2021) 9th November 2021 ---------------------------------------------------------------------------------------------------------------------------- * API: Added [CategoryImageAssignment](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#category-image-assignment) docs and [deprecated ImageIds in the RoomCategory](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/deprecations) . [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-3rd-august-2021) 3rd August 2021 ------------------------------------------------------------------------------------------------------------------------ * API: Added `AverageAmountPerTimeUnit` field to [Room price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-price) replacing the `AverageAmountPerNight`. * API: Added `ChargingMode` field to [Product](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product) replacing the `Charging`. * API: Added `PostingMode` field to [Product](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product) replacing the `Posting`. * API: Added `SettlementMaximumTimeUnits` field to [Rate group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#rate-group) replacing the `SettlementMaximumNights`. * Standalone: Stopped supporting `mewsDistributorOpened` deeplink parameter. * Standalone: Moved introduction guide to [Getting started](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-standalone/getting-started) . * Widget: Stopped supporting deeplinks in Distributor widget. Deeplinks are now supported only in Distributor Standalone. For a widget, you can use the Widget API instead. * Widget: Moved introduction guide to Getting started. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-21st-july-2021) 21st July 2021 ---------------------------------------------------------------------------------------------------------------------- * API: Added `Services` parameter at [Get configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#get-configuration) endpoint that uses newly added [Service](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service) object. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-15th-june-2021) 15th June 2021 ---------------------------------------------------------------------------------------------------------------------- * Widget: Rephrased and restructured main, Distributor Widget and Distributor Standalone introduction. * Widget: Added FAQ about Configuration IDs. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-10th-may-2021) 10th May 2021 -------------------------------------------------------------------------------------------------------------------- * API: Fixed inconsistency in naming in the documentation. * API: Fixed DTOs table heading to reflect the columns. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-3rd-may-2021) 3rd May 2021 ------------------------------------------------------------------------------------------------------------------ * API: Added use case on [On session payment card authorization](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/payment-card-authorization) . [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-19th-april-2021) 19th April 2021 ------------------------------------------------------------------------------------------------------------------------ * API: Moved use case on [How to support payment card in booking engine client application](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/supporting-payment-cards) . [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-30th-march-2021) 30th March 2021 ------------------------------------------------------------------------------------------------------------------------ * API: Added use case for [On session payments](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/on-session-payments) . [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-25th-march-2021) 25th March 2021 ------------------------------------------------------------------------------------------------------------------------ * API: Changed naming of URL variables used in the documentation to make clear distinction between application URLs and API URLs. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-19th-march-2021) 19th March 2021 ------------------------------------------------------------------------------------------------------------------------ * API: Changed urls for testing (demo) environments. * Widget: Changed urls for testing (demo) environments. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021#id-16th-february-2021) 16th February 2021 ------------------------------------------------------------------------------------------------------------------------------ * Widget: Removed deprecation notice for no longer supported integrations which can be set up via Google Tag Manager (GTM) integration. Next [Changelog 2020](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020) [PreviousChangelog 2022](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2022) [NextChangelog 2020](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020) Last updated 3 years ago Was this helpful? --- # Supported language codes | Booking Engine Guide List of supported `languageCode` values. LanguageCode CultureCode Name ca-ES ES Catalan cs-CZ CZ Czech da-DK DK Danish de-CH CH German (Swiss) de-DE DE German (German) el-GR GR Greek en-GB GB English (British) en-US US English (United States) es-ES ES Spanish et-EE EE Estonian eu-ES ES Euskara fi-FI FI Finnish fr-FR FR French is-IS IS Icelandic it-IT IT Italian ja-JP JP Japanese ka-GE GE Georgian ko-KR KR Korean ms-MY MY Malay nb-NO NO Norwegian nl-NL NL Dutch pl-PL PL Polish pt-BR BR Portuguese (Brazilian) pt-PT PT Portuguese (European) ru-RU RU Russian sk-SK SK Slovak sv-SE SE Swedish ta-IN IN Tamil tr-TR TR Turkish uk-UA UA Ukrainian zh-CN CN Chinese (Simplified) [PreviousSupported currency codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-currency-codes) [NextUse cases](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases) Last updated 3 years ago Was this helpful? --- # Changelog 2020 | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-26th-november-2020) 26th November 2020 ------------------------------------------------------------------------------------------------------------------------------ * API: Updated [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) page. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-20th-november-2020) 20th November 2020 ------------------------------------------------------------------------------------------------------------------------------ * API: Made `ConfigurationId` parameter in [Create reservation group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#create-reservation-group) endpoint required. * API: Added `ConfigurationId` parameter to [Get availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-availability) endpoint. * API: Previous variant of sending `HotelId` without `ConfigurationId` to these endpoints was deprecated. * General: Stopped support for hotel/enterprise ids in URL and in the configuration of a javascript client. * General: Configuration ids are now the only supported way to setup Distributor. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-28th-august-2020) 28th August 2020 -------------------------------------------------------------------------------------------------------------------------- * API: Added `CurrencyCode` parameter to [Get availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-availability) endpoint. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-22nd-june-2020) 22nd June 2020 ---------------------------------------------------------------------------------------------------------------------- * API: Added section describing payment card support. * API: Improved `PaymentGatewayData` description. * API: Removed deprecated payment gateways. * API: Improved `CreditCardData` description. * API: [PR 36](https://github.com/MewsSystems/gitbook-distributor-guide/pull/36/files) * Widget: Updated info about payment gateways and payment card storages. * Widget: [PR 36](https://github.com/MewsSystems/gitbook-distributor-guide/pull/36/files) [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-18th-june-2020) 18th June 2020 ---------------------------------------------------------------------------------------------------------------------- * API: Removed `AlwaysIncluded` field from [Product](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product) ([PR37](https://github.com/MewsSystems/gitbook-distributor-guide/pull/37/files) ). In order to pre-select a product during a booking, you can use `IncludedByDefault` field. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-22nd-april-2020) 22nd April 2020 ------------------------------------------------------------------------------------------------------------------------ * API: Added following sections: Configuration, Theme, City, PaymentCardInput, RequiredField, Enterprise and Address. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-23rd-march-2020) 23rd March 2020 ------------------------------------------------------------------------------------------------------------------------ * Widget: Added guide for conditionally firing tags based on tracking consents. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-20th-march-2020) 20th March 2020 ------------------------------------------------------------------------------------------------------------------------ * Widget: Added tracking consents integration. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-18th-march-2020) 18th March 2020 ------------------------------------------------------------------------------------------------------------------------ * API: Added `close()` FE api description. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-4th-march-2020) 4th March 2020 ---------------------------------------------------------------------------------------------------------------------- * API: Added SendMarketingEmail field to Booker. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-3rd-march-2020) 3rd March 2020 ---------------------------------------------------------------------------------------------------------------------- * API: Added enums for RateGroups section and some minor improvements. [](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2020#id-26th-february-2020) 26th February 2020 ------------------------------------------------------------------------------------------------------------------------------ * API: Added documentation for `hotels/getPaymentConfiguration`. * API: Deleted old/legacy `payments/getPaymentGateway`. [PreviousChangelog 2021](https://mews-systems.gitbook.io/booking-engine-guide/changelog/changelog2021) Last updated 9 months ago Was this helpful? --- # Payment card authorization | Booking Engine Guide Whenever a user creates a reservation, there is an option to let them add a payment card, which will then be stored in Mews. You can read more about how to support payment cards in your booking engine application in the [Supporting payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/supporting-payment-cards) use case. With the PSD2 directive (Revised Payment Services Directive - a European Union Directive), it might be convenient for the enterprise to authorize the card for smooth payments in the future. This can minimize the risk of a future payment being rejected. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/payment-card-authorization#creating-a-reservation-group-with-verified-card) Creating a reservation group with verified card --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The first step of the workflow is to create a reservation group via the API, using [Create reservation group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#create-reservation-group) and supplying payment card data with the request - see [Supporting payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/supporting-payment-cards) . The next step is to check whether the card needs authorization by getting the card details using [Get payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#get-payment-cards) and checking if the card [Authorization state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorization-state) is `Authorizable`. If it is, then you can try to authorize the card immediately, using [Authorize payment card](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorize-payment-card) . Check the card [Authorization request state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorization-request-state) in the response to [Authorize payment card](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorize-payment-card) . If the state is a finite state, such as `Authorized` or `Declined`, then no further action is needed. If the state is a non-finite state, such as `Pending` or `Requested`, then you can redirect the user to the Mews application, which will take care of the whole authorization process. Simply navigate the user to URL: `https://[MewsApplicationsBaseUrl]/navigator/card-authorization/detail/[PaymentCardId]?returnUrl=[ReturnUrl]`. A `returnUrl` query parameter is optional and is used by the application to return the user into your booking engine after successful payment card authorization, or in case the user decides to abandon the process. The `returnUrl` value should be a `Base64` encoded absolute URL e.g. in JavaScript via the `btoa` function. After the user returns to your booking engine, you can verify the card authorization state again using [Get payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#get-payment-cards) and checking that the [Authorization state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorization-state) of the card is `Authorized`. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/payment-card-authorization#step-by-step-workflow) Step by step workflow ----------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. Call [Create reservation group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#create-reservation-group) with [Credit card data](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#credit-card-data) , and get `PaymentCardId` from the response. 2. Validate that the card [Authorization state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorization-state) is `Authorizable` via the [Get payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#get-payment-cards) operation. **If not, the workflow ends here.** 3. Try to authorize the card via [Authorize payment card](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorize-payment-card) and check that the [Authorization request state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorization-request-state) in the response is either `Pending` or `Requested`. **If not, the workflow ends here.** 4. Create a `ReturnUrl` by encoding your URL using `Base64`, e.g. the JavaScript example would be `btoa(urlWhereUserShouldReturn)`. 5. Re-direct the user to the gateway at URL `https://[MewsApplicationsBaseUrl]/navigator/card-authorization/detail/[PaymentCardId]?returnUrl=[ReturnUrl]` (you can find the value of `MewsApplicationBaseUrl` in the [Environments](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/environments) section). 6. After the user returns to the `ReturnUrl` in your booking engine, you can verify the authorization state by again using [Get payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#get-payment-cards) and checking that the [Authorization state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#authorization-state) is `Authorized`. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/payment-card-authorization#workflow-diagram) Workflow diagram ------------------------------------------------------------------------------------------------------------------------------------------------------- ![](https://mews-systems.gitbook.io/booking-engine-guide/~gitbook/image?url=https%3A%2F%2F3292240558-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FtIc30XOAP46ahd8X73va%252Fuploads%252Fgit-blob-0391971ea787a26e231662042c06664c2828dc4e%252Fon-session-payment-card-authorization-flow.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=8a588f0&sv=2) [PreviousOn session payments](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/on-session-payments) [NextSupporting payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/supporting-payment-cards) Last updated 3 years ago Was this helpful? --- # Vouchers | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/vouchers#validate-voucher) Validate voucher -------------------------------------------------------------------------------------------------------------------------------------- Determine if the specified voucher code is valid or not. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/vouchers#request) Request `[ApiBaseUrl]/api/distributor/v1/vouchers/validate` Copy { "Client": "My Client 1.0.0", "HotelId": "3edbe1b4-6739-40b7-81b3-d369d9469c48", "VoucherCode": "Discount2042" } Property Type Contract Description `Client` string required Identification of the client as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `HotelId` string required Unique identifier of hotel. `VoucherCode` string required Voucher code enabling special rate offerings (case sensitive). ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/vouchers#response) Response Copy { "IsValid": false } Property Type Contract Description `IsValid` boolean required Indicates whether the voucher code is valid. [PreviousServices](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services) [NextDeprecations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/deprecations) Last updated 9 months ago Was this helpful? --- # Supported currency codes | Booking Engine Guide List of supported `currencyCode` values. CurrencyCode Symbol Precision AED AED 2 ANG ƒ 2 ARS $ 2 AUD A$ 2 BOB Bs 2 BRL R$ 2 BSD $ 2 CAD C$ 2 CDF FC 2 CHF CHF 2 CLP CLP$ 0 CNY CN¥ 2 COP COL$ 0 CRC ₡ 0 CZK Kč 0 DKK DKK 2 DOP RD$ 0 EGP E£ 2 EUR € 2 FJD FJ$ 2 GBP £ 2 GEL GEL 2 GHS GH₵ 2 GTQ Q 2 HKD HK$ 2 HNL L 2 HRK kn 2 HUF Ft 0 IDR Rp 0 ILS ₪ 2 ISK ISK 2 JPY JP¥ 0 KES KSh 2 KHR ៛ 0 KRW ₩ 0 MAD DH 2 MGA AR 1 MUR Rs 2 MXN Mex$ 2 MYR RM 2 NAD N$ 2 NGN ₦ 2 NOK NOK 2 NZD NZ$ 2 PAB B/. 2 PEN S/. 2 PHP ₱ 2 PLN zł 2 PYG ₲ 2 RUB ₽ 2 SAR ﷼ 2 SCR SR 2 SEK SEK 2 SGD S$ 2 THB ฿ 2 TOP T$ 2 TRY ₺ 2 TWD NT$ 2 UAH ₴ 2 USD $ 2 UYU $U 2 VUV VT 0 WST $ 2 XCD $ 2 XOF CFA 0 XPF ₣ 2 ZAR R 2 [PreviousImages](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/images) [NextSupported language codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-language-codes) Last updated 3 years ago Was this helpful? --- # Google Triggers Reference | Booking Engine Guide > **Notice of usage:** Google Tag Manager (GTM) and Google Analytics 4 (GA4) are third party services and we provide this integration as is. We support a set of custom events and Data Layer variables for use with GTM and GA4, however we have no control over what happens to them and how they are used. The basic setup examples we provide have been tested and verified to work with the Mews Booking Engine, however if you need a more complex setup then we cannot provide the support to do so and we recommend to ask a specialist to set it up and test it for you. This reference provides details of **custom events** and **Data Layer variables** generated within the Booking Engine, which can be used to trigger analytics tags to fire, i.e. to send data to Google Analytics. You will need to reference these events and variables when setting up tag _triggers_ in Google Tag Manager. [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#contents) Contents ---------------------------------------------------------------------------------------------------------------------- * [Data Layer variables](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#data-layer-variables) * [Custom events](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#custom-events) * [GA4 pageview events](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4-pageview-events) * [GA4 eCommerce events](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4-ecommerce-events) * [Illustration of GA4 events in the Booking Engine](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#illustration-of-ga4-events-in-the-booking-engine) [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#data-layer-variables) Data Layer variables ---------------------------------------------------------------------------------------------------------------------------------------------- All event data is passed to Google Tag Manager through a _Data Layer_. > #### > > [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#what-is-a-data-layer) > > What is a Data Layer? > > A Data Layer is a Javascript object in a website or app that collects analytics data in a standardized way. It acts as a layer between the site and the tag management system. The layer stores values, such as page name and URL, that are populated automatically when a visitor uses the site. The data is transferred into tag management variables and can be used to activate triggers in your tag configurations. [Google Help — The data layer](https://support.google.com/tagmanager/answer/6164391?hl=en) To use data from the Data Layer in your tags, in the GTM configuration set up a _Variable_ with a suitable name as a Data Layer Variable (DLV), like this: ![](https://mews-systems.gitbook.io/booking-engine-guide/~gitbook/image?url=https%3A%2F%2F3292240558-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FtIc30XOAP46ahd8X73va%252Fuploads%252Fgit-blob-1305537ebb267850263327c3f4e3e8b51dcbf258%252Fvariable.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=6407c7c8&sv=2) variable The [Custom events](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#custom-events) reference below describes which Data Layer Variables are relevant to which custom events. > **Prices:** Note all prices currently presented via the Data Layer are gross prices, i.e. including taxes and fees. [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#custom-events) Custom events -------------------------------------------------------------------------------------------------------------------------------- **GA4 pageview events** * [ga4\_ApplicationLoaded](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_applicationloaded) * [ga4\_VoucherAdded](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_voucheradded) * [ga4\_PropertiesLoaded](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_propertiesloaded) * [ga4\_CalendarLoaded](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_calendarloaded) * [ga4\_CategoriesLoaded](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_categoriesloaded) * [ga4\_RatesLoaded](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_ratesloaded) * [ga4\_ProductsLoaded](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_productsloaded) * [ga4\_PromotedServicesLoaded](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_promotedservicesloaded) * [ga4\_SummaryLoaded](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_summaryloaded) * [ga4\_DetailsLoaded](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_detailsloaded) * [ga4\_BookingCreated](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_bookingcreated) * [ga4\_ConfirmationLoaded](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_confirmationloaded) **GA4 eCommerce events** * [select\_promotion](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#select_promotion) * [view\_item\_list](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#view_item_list) * [add\_to\_cart](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#add_to_cart) * [remove\_from\_cart](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#remove_from_cart) * [begin\_checkout](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#begin_checkout) * [add\_payment\_info](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#add_payment_info) * [purchase](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#purchase) ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#data-layer-variables-in-events) Data Layer Variables in events Each event is fired with a standard set of data: Data Layer Variable Name Description eventName Name of the event, in readable form without prefix, e.g. `Voucher Added`. trackingConsents [Tracking consents](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#tracking-consents) applied at the time the event was created. If a user selects a hotel or property in the Booking Engine, information about it is also added to the event. In _Singlehotel_ mode, the property is always selected. Data Layer Variable Name Description hotelName Name of the hotel or property hotelId Unique identifier of the hotel or property enterpriseName Array with name of the enterprise (hotel / property) in each supported language Pageload events with the 'ga4\_' prefix also have the following attributes available in the Data Layer: Data Layer Variable Name Description page\_location URL style location, to be used for tracking URL page\_title Human readable name of page or screen Some events expose additional DLVs. These are described separately for each event. ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#tracking-consents) Tracking consents Name Type Contract Purpose advertising boolean required Advertising, e.g. used to help advertisers deliver more relevant advertising, or to limit how many times you see an advertisment. functional boolean required Functional, non-essential functionality, e.g. remembering user choices made in the past. necessary boolean required Necessary functionality. performance boolean required Performance, e.g. collecting information about how users use a website; data are anonymized. [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4-pageview-events) GA4 pageview events -------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_applicationloaded) ga4\_ApplicationLoaded * Event which fires when the application is loaded for the user ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_voucheradded) ga4\_VoucherAdded * A voucher has been added into the booking Data Layer Variable Name Description voucherCode Code of voucher added by user ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_propertiesloaded) ga4\_PropertiesLoaded * The properties selection step was loaded for the user ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_calendarloaded) ga4\_CalendarLoaded * The calendar step has been loaded for the user ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_categoriesloaded) ga4\_CategoriesLoaded * Categories / room selection has been shown to the user Data Layer Variable Name Description startDate Start of stay date selected by user endDate End of stay date selected by user available Array of room categories which have been shown to user as available unavailable Array of room categories which have been shown to user as not available * Each of the items in arrays follows the google [Item specification for ecommerce](https://developers.google.com/analytics/devguides/collection/ga4/ecommerce?client_type=gtag) , for example: Copy { item_id: "0d9120fc-72cb-4d23-afe2-ad9000dcb803", item_name: "Room 1", item_category2: "Jan's Hotel", item_category3: "Jan's Hotel City", item_brand: "Jan's Hotel Chain", affiliation: "Jan's Hotel", enterpriseId: "6aaf20ac-a651-4826-b8c0-ad9000dcac3d", currency: "EUR", price: 10 }, ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_ratesloaded) ga4\_RatesLoaded * Rates selection has been shown to the user Data Layer Variable Name Description rates Array of rates shown to user, together with their currency and gross price ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_productsloaded) ga4\_ProductsLoaded * Products selection has been shown to the user Data Layer Variable Name Description products Array of products shown to user ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_promotedservicesloaded) ga4\_PromotedServicesLoaded * Promoted Services has been shown to the user ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_summaryloaded) ga4\_SummaryLoaded * Summary step has been shown to the user ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_detailsloaded) ga4\_DetailsLoaded * The final screen with form to fill in has been shown to the user ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_bookingcreated) ga4\_BookingCreated * Mews created a booking within the PMS. Additional information is available in the `purchase` event. ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4_confirmationloaded) ga4\_ConfirmationLoaded * The confirmation screen has been shown to the user. This step is shown after returning from the payment gateway as the final step of the process. [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#ga4-ecommerce-events) GA4 eCommerce events ---------------------------------------------------------------------------------------------------------------------------------------------- Please follow the [Google guide for tracking eCommerce in GA4](https://developers.google.com/analytics/devguides/collection/ga4/ecommerce) . You need to set up events with all mandatory parameters so they are tracked correctly. We are pushing all available variables into the eCommerce tracking for more advanced setups as well. ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#select_promotion) select\_promotion * Voucher has been added to the booking Data Layer Variable Name Description promotion\_id Array of rates shown to user ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#view_item_list) view\_item\_list * List of available rooms shown to user for eCommerce purposes Data Layer Variable Name Description items Array of items (rooms / categories) shown to user ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#add_to_cart) add\_to\_cart * User added room and products to cart Data Layer Variable Name Description items Array of items (rooms / categories / products) added by user in reservation * Example: Copy { event: "add_to_cart", items: [\ {\ item_id: "0d9120fc-72cb-4d23-afe2-ad9000dcb803",\ quantity: 1,\ item_name: "Room 1",\ item_variant: "Best Price",\ item_category: "Reservation",\ item_category2: "Jan's Hotel",\ item_category3: "Jan's Hotel City",\ item_brand: "Jan's Hotel Chain",\ affiliation: "Jan's Hotel",\ currency: "EUR",\ price: 42\ },\ {\ item_id: "26c2ec6e-2890-4677-b994-ad9000dce77f",\ quantity: 1,\ item_name: "Dog",\ item_category: "Product",\ item_category2: "Jan's Hotel",\ item_category3: "Jan's Hotel City",\ item_brand: "Jan's Hotel Chain",\ affiliation: "Jan's Hotel"\ }\ ], trackingConsents: { necessary: true, performance: true, functional: true, advertising: true }, gtm: {uniqueEventId: 54} } ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#remove_from_cart) remove\_from\_cart * User removed an item from the cart. See `add_to_cart` for event parameters. Data Layer Variable Name Description items Array of items (rooms / categories / products) remover by user in reservation ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#begin_checkout) begin\_checkout * User started the process of check-out. See `add_to_cart` for event parameters. Data Layer Variable Name Description items Array of items (rooms / categories / products) added by user in reservation ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#add_payment_info) add\_payment\_info * User added payment information. Data Layer Variable Name Description payment\_type Payment type, usually `PaymentCard` currency Currency in which the payment will be done value Amount of the reservation items Array of items (rooms / categories / products) added by user in reservation ### [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#purchase) purchase * Purchase made. This is the most important eCommerce event. We expose many variables in the event which can be used for advanced tracking. See the example for full description. The Purchase event is triggered on the booking confirmation screen under the following conditions: 1. Payment Success: When the user returns from the payment gateway, and the payment is successfully completed. 2. Flexible Rates: If the booking selected flexible rates and no payment is required, the Purchase event is triggered immediately upon booking confirmation. > **Reservation Owner Email Configuration** > > The `reservationOwnerEmail` field is now available in the `ecommerce` section of the purchase event. To enable this feature, it must be configured in Commander: > > **Settings** → **Services** → **{service}** → **Booking engine** → **{booking engine}** → Check **"Collect emails for bookings in Google Tag Manager purchase event"** > > **Reminder:** Only use guest email addresses as permitted by your privacy policy and T&Cs. * The most important variables are: Data Layer Variable Name Description startDate Start of stay date selected by user endDate End of stay date selected by user currency Currency in which the payment will be done value Amount of the reservation tax Amount of tax for the reservation reservationGroupName ID / Name of the reservation group created in Mews netValue Value of reservation without taxes grossValue Value of reservation with all taxes pricingMode either `gross` for US style of pricing, `net` for EU style of pricing roomCount Count of rooms in reservation adults Count of Adults in reservations children Count of children in reservations ecommerce.reservationOwnerEmail Email address of the reservation owner (requires booking engine configuration) items Array of items (rooms / categories / products) added by user in reservation. See example for different types of items * Example: Copy { event: "purchase", eventName: "Purchase", ecommerce: { transaction_id: "d4166ad6d39856ae206cf0f48738d63fbe864fb3", value: 160, // Total price of reservation group tax: 17.14, // Total tax of reservation group currency: "EUR", items: [\ /*\ * Rooms and products added to reservation group. There can be multiple rooms with different dates and confirmation numbers. Similarly, the number of different products can range from none to many.\ *\ * Please note that room prices do not include product costs. Each product's price is specified separately.\ */\ {\ item_id: "d089a328-2876-47a8-9dca-b38700d3193a", // Room category id\ item_name: "Room 1", // Room category name\ item_category: "Reservation",\ item_category2: "Kaer Trolde", // Property name\ item_category3: "Prague", // Property city\ item_brand: "Witcher", // Property chain\ affiliation: "Kaer Trolde",\ currency: "EUR",\ price: 160, // Price of reservation\ netPrice: 142.86, // Price of reservation without taxes\ grossPrice: 160, // Price of reservation with taxes\ pricingMode: "Gross", // Pricing mode (Gross mainly Europe = tax is included in price, Net mainly US = tax non included in price)\ quantity: 1, // Count of rooms of room category\ reservationGroupId: "f94a4f53-ab9c-4847-8e4e-b38700d31923",\ reservationGroupName: "ff-31-10-C35D", // Reservation Group name – can be mapped to export from mews Operations for each reservation\ tax: 17.14, // Tax of reservation\ item_variant: "Non refundable", // Selected rate\ confirmationNumber: "87", // Confirmation number of each reservation to be mapped with Mews operations\ reservationRateName: "Non refundable",\ checkInDate: "2025-10-31", // Check-in day of reservation\ checkOutDate: "2025-11-02", // Check-out day of reservation\ stayDuration: 2, // Count of days in reservation\ adults: 2, // Count of adults in reservation\ children: 0 // Count of children in reservation\ }\ ], reservationOwnerEmail: "guest@example.com" // Email address of the reservation owner (when enabled in booking engine configuration) }, affiliation: "Kaer Trolde", transaction_id: "d4166ad6d39856ae206cf0f48738d63fbe864fb3", currency: "EUR", value: 160, // Total price of reservation group tax: 17.14, // Total tax of reservation group reservationGroupId: "f94a4f53-ab9c-4847-8e4e-b38700d31923", // Reservation Group ID – will be added to export in Mews Operation to identify each reservation group reservationGroupName: "ff-31-10-C35D", // Reservation Group name – can be mapped to export from mews Operations for each reservation reservationIds: "d089a328-2876-47a8-9dca-b38700d3193a", // Comma separated list of all reservation (item) IDs chainName: "Witcher", // Chain name netValue: 142.86, // Price without taxes grossValue: 160, // Price with taxes pricingMode: "Gross", // Pricing mode (Gross mainly Europe = tax is included in price, Net mainly US = tax non included in price) roomCount: 1, // Count of rooms adults: 2, // Count of adults children: 0, // Count of children mewsSource: "Mews Booking Engine", // Source identifier mewsAppVersion: "5238.0.0", // Booking Engine version trackingConsents: { necessary: true, performance: true, functional: true, advertising: true }, // Tracking consent status "gtm.uniqueEventId": 56, // GTM unique event identifier items: [\ // Duplicate of ecommerce.items for compatibility\ {\ item_id: "d089a328-2876-47a8-9dca-b38700d3193a",\ item_name: "Room 1",\ item_category: "Reservation",\ item_category2: "Kaer Trolde",\ item_category3: "Prague",\ item_brand: "Witcher",\ affiliation: "Kaer Trolde",\ currency: "EUR",\ price: 160,\ netPrice: 142.86,\ grossPrice: 160,\ pricingMode: "Gross",\ quantity: 1,\ reservationGroupId: "f94a4f53-ab9c-4847-8e4e-b38700d31923",\ reservationGroupName: "ff-31-10-C35D",\ tax: 17.14,\ item_variant: "Non refundable",\ confirmationNumber: "87",\ reservationRateName: "Non refundable",\ checkInDate: "2025-10-31",\ checkOutDate: "2025-11-02",\ stayDuration: 2,\ adults: 2,\ children: 0\ }\ ] } [](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-triggers-reference#illustration-of-ga4-events-in-the-booking-engine) Illustration of GA4 events in the Booking Engine ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ The following annotated screenshots provide a visual illustration of GA4 related events and their respective trigger points within the Booking Engine. ![](https://mews-systems.gitbook.io/booking-engine-guide/~gitbook/image?url=https%3A%2F%2F3292240558-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FtIc30XOAP46ahd8X73va%252Fuploads%252Fgit-blob-de17afdecf7725da3ad6a99174b0a2fed09079bc%252Fga4_event_reference_updated.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=cc4d2bf3&sv=2) variable [PreviousGoogle Tag Manager](https://mews-systems.gitbook.io/booking-engine-guide/integrations/google-tag-manager) [NextGoogle Tag Manager Configuration](https://mews-systems.gitbook.io/booking-engine-guide/integrations/gtm-skeleton) Last updated 19 days ago Was this helpful? --- # Reference | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#options-reference) Options reference --------------------------------------------------------------------------------------------------------------------------------- > **Note:** Direct configuration of the booking engine through the options has been deprecated and will be disabled in future. Instead use Booking Engine Configuration in **Mews Operations**. The only supported options now are `configurationIds` and `openElements`. Option Type Contract Description configurationIds array of`string` required Set of booking engine unique identifiers. You can get the unique identifier of a configuration from its details page in **Mews Operations** - see [Where can I get Configuration ID?](https://mews-systems.gitbook.io/booking-engine-guide/faq#where-can-i-get-configuration-id) . openElements `string` optional A list of comma-separated CSS selectors of elements, which will automatically get attached to click event listeners for opening the Booking Engine Widget. The string is given as an argument to the `document.querySelectorAll` function, you can get more information about it [here](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll) . The click event is being delegated, meaning that each element is being looked up on a website dynamically after the click happens. This way you can pass a selector to the elements that don’t exist yet during the initialization. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#javascript-api-reference) Javascript API reference ----------------------------------------------------------------------------------------------------------------------------------------------- Javascript API calls are defined on the booking engine instance, which is created with the initialization call. This instance is returned to you as an argument of a callback function that you can pass as the second parameter to the initialization call. The following simple example shows how to use the calls to set up start and end dates, and then open the booking engine: Copy The API functions supported are listed below. Some functions are common to both Single Mode and Chain Mode, while some are specific to one mode or the other. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#common-api-functions) Common API functions #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#open) open() * Opens the booking engine in its overlay #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#close) close() * Closes the booking engine and its overlay (note: even though the booking engine is closed, it still responds to API calls) #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#setlanguagecode-languagecode) setLanguageCode(languageCode) * `languageCode` Type: `string` Description: The language code to be set, in format `en-US`. [Supported language codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-language-codes) * Sets the language of the booking engine’s localization. The language code should be in the format _language_\-_countryCode_, e.g. `en-US`, as a variant of [IETF tag](https://en.wikipedia.org/wiki/IETF_language_tag) . If `languageCode` is not in the valid format, nothing happens. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#setcurrencycode-currencycode) setCurrencyCode(currencyCode) * `currencyCode` Type: `string` Description: The currency code to be set, in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format, e.g. `EUR`. [Supported currency codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-currency-codes) * Sets the currency of the booking engine’s localization. The currency code should be in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. If `currencyCode` is not in the valid format, nothing happens. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#setstartdate-date) setStartDate(date) * `date` Type: `Date` Description: The start date to set * Sets the start date for a new availability query, the currently loaded availability list is not affected. If `date` is not a valid `Date` object or its value isn’t allowed as a start date, nothing happens. Note: `monthIndex` starts runs from `0` for January to `11` for December ([click here for more details](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#Individual_date_and_time_component_values) ). > **Correct** - for 18 January 2019: > > Copy > > distributor.setStartDate(new Date(2019, 0, 18)) > > **Incorrect** - DO NOT DO THIS: > > Copy > > distributor.setStartDate("2019-01-18") #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#setenddate-date) setEndDate(date) * `date` Type: `Date` Description: The end date to set * Sets the end date for a new availability query, the currently loaded availability list is not affected. If `date` is not a valid `Date` object, nothing happens. Note: `monthIndex` starts runs from `0` for January to `11` for December ([click here for more details](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#Individual_date_and_time_component_values) ). > **Correct** - for 18 December 2019: > > Copy > > distributor.setEndDate(new Date(2019, 11, 18)) > > **Incorrect** - DO NOT DO THIS: > > Copy > > distributor.setEndDate("2019-12-18") #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#setvouchercode-code) setVoucherCode(code) * `code` Type: `string` Description: The voucher code to set * Sets a new voucher code value. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#setadultcount-adultcount) setAdultCount(adultCount) * `adultCount` Type: `number` Description: The number of adults to set * Sets the number of adults that should be selected by default. Space occupancy for adults on the rate screen will be pre-filled according to this value. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#setchildcount-childcount) setChildCount(childCount) * `childCount` Type: `number` Description: The number of children to set * Sets the number of children that should be selected by default. Space occupancy for children on the rate screen will be pre-filled according to this value. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#disabletracking) disableTracking() * Sets all tracking consents to false (see [Integrations](https://mews-systems.gitbook.io/booking-engine-guide/integrations) ). #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#enabletracking) enableTracking() * Sets all tracking consents to true (see [Integrations](https://mews-systems.gitbook.io/booking-engine-guide/integrations) ). ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#single-mode-api-functions) Single Mode API functions #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#showrooms) showRooms() * Sets the booking engine to the `Rooms` step. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#showrates-roomid) showRates(roomId) * `roomId` Type: `string` Description: ID of a room or space to be selected * Sets the booking engine to the third step (`Rates`) as if you had selected a room on the second screen. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#chain-mode-api-functions) Chain Mode API functions #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#showhotels) showHotels() * Sets the booking engine to the `Hotels` step. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#showrooms-hotelid) showRooms(hotelId) * `hotelId` Type: `string` Description: ID of a hotel or other property whose rooms you want to display * Sets the booking engine to the `Rooms` step. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#setcity-cityid) setCity(cityId) * `cityId` Type: `string` Description: ID of a city whose hotels you want to display ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#advanced-configuration-optional) Advanced configuration (optional) As the third parameter, `Mews.Distributor` accepts optional configuration. Copy Mews.Distributor( { configurationIds: ['aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'] }, function (api) { api.open(); }, { dataBaseUrl: 'https://api.mews-demo.com' } ); #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/reference#string-databaseurl) string dataBaseUrl * Allows you to define a custom URL which is used for booking engine API calls and static assets. In the example above, the booking engine will be run against our Demo environment. [PreviousAdvanced guide](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/advanced-guide) [NextTroubleshooting](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/troubleshooting) Last updated 1 year ago Was this helpful? --- # Use cases | Booking Engine Guide This section provides guidance on using the Booking Engine Widget in various common scenarios. > **Important:** Before diving into the use cases, ensure that you meet all the necessary [Prerequisites](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/use-cases/prerequisites) > . Failing to do so may result in code that is difficult to comprehend, or in behavior that deviates from your expectations. * [Testing in the Demo environment](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/use-cases/testing-in-demo-environment) * [Using your own Date inputs](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/use-cases/using-your-own-date-inputs) * [Multiple enterprises and pre-selected locations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/use-cases/multi-enterprises) * [Disabling widget caching](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/use-cases/disable-widget-caching) [PreviousGetting started](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/getting-started) [NextPrerequisites](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-widget/use-cases/prerequisites) Last updated 1 year ago Was this helpful? --- # Reservations | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#get-reservations-pricing) Get reservations pricing ---------------------------------------------------------------------------------------------------------------------------------------------------------- Get a price quotation for a specific hotel, date interval, room category and person count. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#request) Request `[ApiBaseUrl]/api/distributor/v1/reservations/getPricing` Copy { "Client": "My Client 1.0.0", "HotelId": "3edbe1b4-6739-40b7-81b3-d369d9469c48", "StartUtc": "2015-01-01T00:00:00Z", "EndUtc": "2015-01-03T00:00:00Z", "VoucherCode": "Discount2042", "RoomCategoryId": "3540c7d4-e128-41e2-81d8-ff4d196c595a", "Occupancies": [\ {\ "OccupancyData": [\ {\ "AgeCategoryId": "16e8a466-729e-4d32-a221-ade300e410a8",\ "PersonCount": 1\ }\ ]\ }\ ], "ProductIds": [\ "d0e88da5-ae64-411c-b773-60ed68954f64"\ ], "AvailabilityBlockId": "5mgbe1b4-6739-40b7-81b3-d369d9469c48" } Property Type Contract Description `Client` string required Identification of the client as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `HotelId` string required Unique identifier of the hotel. `StartUtc` string required Start date of the reservation, i.e. arrival date. `EndUtc` string required End date of the reservation, i.e. departure date. `VoucherCode` string optional Voucher code enabling special rate offerings. `RoomCategoryId` string required Identifier of the requested room category. `Occupancies` array of [Occupancy](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#occupancy) required Occupancy numbers for the reservations. `ProductIds` array of string optional Unique identifiers of the requested products. `AvailabilityBlockId` string optional Unique identifier of availability block if present. Provide always when you have it. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#occupancy) Occupancy Property Type Contract Description `OccupancyData` array of [OccupancyData](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#occupancy-data) required List of occupancy data. `~AdultCount~` ~number~ ~required~ ~Number of adults.~ **Deprecated!** `~ChildCount~` ~number~ ~required~ ~Number of children.~ **Deprecated!** ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#response) Response Copy { "OccupancyPrices": [\ {\ "AdultCount": 1,\ "ChildCount": 0,\ "OccupancyData": [\ {\ "AgeCategoryId": "16e8a466-729e-4d32-a221-ade300e410a8",\ "PersonCount": 1\ }\ ],\ "Pricing": [\ {\ "MaxPrice": {\ "TotalAmount": { },\ "AverageAmountPerTimeUnit": { }\ },\ "Price": {\ "TotalAmount": { },\ "AverageAmountPerTimeUnit": { }\ },\ "RateId": "b34330be-7e19-453e-8959-592c4e820f85"\ }\ ]\ }\ ] } Property Type Contract Description `OccupancyPrices` array of [Room occupancy availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-occupancy-availability) required Pricing information. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#get-reservation-price) Get reservation price ---------------------------------------------------------------------------------------------------------------------------------------------------- Get a total price for the requested reservations. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#request-1) Request `[ApiBaseUrl]/api/distributor/v1/reservations/price` Copy { "Client": "My Client 1.0.0", "ConfigurationId": "e4da5c87-1b4b-4e68-841e-abc800c82505", "CurrencyCode": "EUR", "Reservations": [\ {\ "Identifier": "uniqueClientGeneratedIdentifier1",\ "StartUtc": "2030-01-01T00:00:00Z",\ "EndUtc": "2030-01-03T00:00:00Z",\ "ProductIds": [\ "13800226-e46d-429d-b31f-ae590104b256"\ ],\ "VoucherCode": null,\ "RateId": "7888ba86-7ad2-4d50-abd3-acf700f0d20a",\ "RoomCategoryId": "a0c790b7-51c4-4702-a351-abc800c8118b",\ "OccupancyData": [\ {\ "AgeCategoryId": "16e8a466-729e-4d32-a221-ade300e410a8",\ "PersonCount": 1\ }\ ]\ }\ ] } Property Type Contract Description `Client` string required Identification of the client as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `ConfigurationId` string required Unique identifier of the Booking Engine configuration used. `CurrencyCode` string optional ISO 4217 code of the currency in which price will be calculated. Enterprise default currency code is used as default. [Supported currency codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-currency-codes) `Reservations` array of [Reservation](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#reservation) required List of reservations. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#reservation) Reservation Property Type Contract Description `~AdultCount~` ~number~ ~required~ ~Number of adults.~ **Deprecated!** `~ChildCount~` ~number~ ~required~ ~Number of children.~ **Deprecated!** `Identifier` string required Unique identifier for reservation generated on client. `StartUtc` string required Start date of the reservation, i.e. arrival date. `EndUtc` string required End date of the reservation, i.e. departure date. `ProductIds` array of string optional Unique identifiers of products which should be included into reservation price calculations. `VoucherCode` string optional Voucher code applied to reservation `RateId` string required Identifier of the chosen rate. `RoomCategoryId` string required Unique identifier of the room category. `OccupancyData` array of [OccupancyData](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#occupancy-data) required List of occupancy data. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#occupancy-data) Occupancy Data Property Type Contract Description `AgeCategoryId` string required Age category identifier. `PersonCount` number required Person count. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#response-1) Response Copy { "ReservationPrice": [\ {\ "Identifier": "uniqueClientGeneratedIdentifier1",\ "TotalAmount": {\ "Currency": "EUR",\ "GrossValue": 310.00,\ "NetValue": 282.72,\ "TaxValues": [\ {\ "TaxRateCode": "ES-2016-R",\ "Value": 27.28\ }\ ],\ "Breakdown": {\ "Items": [\ {\ "TaxRateCode": "ES-2016-R",\ "NetValue": 272.72,\ "TaxValue": 27.28\ },\ {\ "TaxRateCode": null,\ "NetValue": 10.0,\ "TaxValue": 0.0\ }\ ]\ }\ },\ "AmountToChargeOnConfirmation": null,\ "ProductOrderPrices": [\ {\ "ProductId": "13800226-e46d-429d-b31f-ae590104b256",\ "AgeCategoryId": null,\ "ProductName": {\ "es-ES": "Before check in"\ },\ "ProductOptions": {\ "SelectedByDefault": false,\ "BillAsPackage": false,\ "OfferToCustomer": true,\ "ExcludePriceFromOffer": false,\ "OfferToEmployee": true\ },\ "ChargingMode": "Once",\ "TotalAmount": {\ "Currency": "EUR",\ "GrossValue": 10.0,\ "NetValue": 10.0,\ "TaxValues": [],\ "Breakdown": {\ "Items": [\ {\ "TaxRateCode": null,\ "NetValue": 10.0,\ "TaxValue": 0.0\ }\ ]\ }\ }\ }\ ]\ }\ ] } #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#reservationprice) ReservationPrice Property Type Contract Description `Identifier` string optional Unique identifier for reservation provided in the request data. `AmountToChargeOnConfirmation` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#amount) optional Amount that needs to be charged on payment gateway on reservationGroup confirmation. `TotalAmount` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#amount) required Total amount of the reservation. `ProductOrderPrices` array of [ProductOrderPricingInfo](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#productorderpricinginfo) required List of product order prices assigned to the reservation. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#productorderpricinginfo) ProductOrderPricingInfo Property Type Contract Description `ProductId` string required Unique identifier of product. `AgeCategoryId` string optional Identifier of age category. `~ProductName~` [~Localized text~](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) ~required~ ~Name of the hotel.~ **Deprecated!** `ProductOptions` [ProductOptions](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#productoptions) optional Product options. `~ChargingMode~` ~string~ [~Product charging mode~](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product-charging-mode) ~required~ ~Charging mode of the product.~ **Deprecated!** `TotalAmount` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#amount) required Total amount of product. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#productoptions) ProductOptions Property Type Contract Description `SelectedByDefault` boolean optional If product was selected by default for reservation. `BillAsPackage` boolean optional Product is part of a package. `OfferToCustomer` boolean optional Product is available in booking engine. `ExcludePriceFromOffer` boolean optional Product was not available in booking engine, but it is counted in reservation total price ( eg. CityTax ). `OfferToEmployee` boolean optional Product available in Mews Operations. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#amount) Amount Property Type Contract Description `Currency` string required ISO 4217 code of the currency. `GrossValue` number required Gross value of the amount. (Net + sum of `TaxValues`). `NetValue` number required Net value of the amount. `~TaxValues~` ~array of~ [~Tax values~](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#tax-value) ~required~ ~Tax values of the amount~ **Deprecated!**. `Breakdown.Items` array of [Complete tax](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#complete-tax) required List of complete taxes related to this amount. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations#complete-tax) Complete tax Property Type Contract Description `TaxRateCode` string required Unique identifier of Tax Rate Code. `NetValue` number required Net amount of product. `TaxValue` number required Tax amount of product ( Calculated from NetValue based on TaxRateCode ). [PreviousPayment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards) [NextReservation groups](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups) Last updated 9 months ago Was this helpful? --- # Configuration | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#get-configuration) Get configuration --------------------------------------------------------------------------------------------------------------------------------------------- Get configuration data for the specified booking engine instances, including location, supported room and space categories, products, tax environment, and so on. This operation can be called initially to fetch data which may be important during the booking workflow. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#request) Request `[ApiBaseUrl]/api/distributor/v1/configuration/get` Copy { "Client": "My Client 1.0.0", "Ids": [\ "3edbe1b4-6739-40b7-81b3-d369d9469c48",\ ...\ ], "PrimaryId": "3edbe1b4-6739-40b7-81b3-d369d9469c48" } Property Type Contract Description `Client` string required Identification of the API client, as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `PrimaryId` string required Unique identifier of the primary [Configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#configuration-1) . `Ids` array of string required Set of unique identifiers of [Configurations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#configuration-1) . ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#response) Response Copy { "Cities": [\ {\ "Id": "9044b0bf-cbe0-4df5-beeb-b32e19bcd073",\ "ImageId": "e956201e-ba2f-470f-8070-b43f9cd72194",\ "Name": {\ "en-US": "Amsterdam"\ }\ }\ ], "CityId": "9044b0bf-cbe0-4df5-beeb-b32e19bcd073", "Configurations": [\ {\ "Id": "3edbe1b4-6739-40b7-81b3-d369d9469c48",\ "AdultCount": null,\ "ChildCount": null,\ "ChildSelectionEnabled": null,\ "CompetitorRateDescription": {\ "en-US": "Competitor Rate Description"\ },\ "CompetitorPriceRelativeAdjustment": 1.1,\ "DisplayAvailability": null,\ "DisplayPromoCode": null,\ "DisplayRateComparision": null,\ "DisplaySpecialRequests": null,\ "Enterprise": {\ "AcceptedCurrencyCodes": ["EUR"],\ "AdditionalLegalStatements": {\ "en-US": "Lorem ipsum."\ },\ "Address": {\ "City": "Zeist",\ "CountryCode": "NL",\ "Latitude": 52.0749748,\ "Line1": "Arnhemse Bovenweg 31",\ "Line2": "",\ "Longitude": 5.2590181,\ "PostalCode": "3708 AA"\ },\ "Categories": [\ {\ "Description": {\ "en-US": "Our Single Castleroom is a cozy and comfortable room with a single bed (80x200), spacious bathroom with guest supplies, working desk and a flat screen TV. This quiet non-smoking room of 15m2 has a nice view of the Castle and of course there is free high speed Wi-Fi.\r\n"\ },\ "ExtraBedCount": 0,\ "Id": "295d96e7-8501-4cbd-b78d-8bf590bf6db9",\ "Name": { "en-US": "Single Castleroom" },\ "NormalBedCount": 1,\ "Ordering": 0,\ "SpaceType": "Room"\ }\ ],\ "CategoryImageAssignments": [\ {\ "Id": "69832f4b-4b47-4d32-9b89-ac0600de0cd6",\ "CategoryId": "295d96e7-8501-4cbd-b78d-8bf590bf6db9",\ "ImageId": "f987a97c-5049-44ca-9933-5b657e5263e2",\ "Ordering": 2\ }\ ],\ "CityId": "39db0c2f-6929-47ec-9386-0abdaaef4c9c",\ "DefaultCurrencyCode": "EUR",\ "DefaultLanguageCode": "nl-NL",\ "DefaultRateCurrencyCode": "EUR",\ "Description": { "nl-NL": "" },\ "Email": "info@kasteelkerckebosch.com",\ "IanaTimeZoneIdentifier": "Europe/Berlin",\ "Id": "7a13590c-6538-461e-b02f-6357400de493",\ "ImageId": "263c3e5f-e11d-41d8-9746-4bdd0852f04f",\ "IntroImageId": "f24469f8-c23b-4450-a1f8-3ecd39904e99",\ "Name": {\ "en-US": "Sample Hotel Description"\ },\ "Pricing": "Gross",\ "PrivacyPolicyUrl": {\ "en-US": "https://localhost/en"\ },\ "Products": [\ {\ "Id": "4fd0e6e0-101c-410d-8c12-ad6000b7e390",\ "Name": {\ "en-US": "Breakfast"\ },\ "Description": {},\ "CategoryId": "77e0a18c-f2a5-418f-b578-16d3599c059d",\ "ImageId": null,\ "IncludedByDefault": false,\ "Pricing": {\ "Discriminator": "Absolute",\ "Value": {\ "CHF": {\ "Currency": "CHF",\ "GrossValue": 108.31,\ "NetValue": 98.46,\ "TaxValues": [\ {\ "TaxRateCode": "CZ-L",\ "Value": 9.85\ }\ ]\ },\ "EUR": {\ "Currency": "EUR",\ "GrossValue": 100,\ "NetValue": 90.91,\ "TaxValues": [\ {\ "TaxRateCode": "CZ-L",\ "Value": 9.09\ }\ ]\ }\ }\ },\ "ChargingMode": "PerTimeUnit",\ "PostingMode": "PerTimeUnit",\ "Ordering": 1\ },\ {\ "Id": "5d6de830-8ada-4b65-b72c-60fc1e719f1b",\ "Name": {\ "nl-NL": "Extra bedlinnen",\ "en-US": "Extra bedlinnen (Once Off)"\ },\ "Description": {},\ "CategoryId": "77e0a18c-f2a5-418f-b578-16d3599c059d",\ "ImageId": "ec643f33-cd6c-4250-accd-518182165ffe",\ "IncludedByDefault": false,\ "Pricing": {\ "Discriminator": "Relative",\ "Value": {\ "ProductIds": [],\ "TaxRateCodes": [\ "CZ-L"\ ],\ "Multiplier": 0.05,\ "Target": "GrossValue"\ }\ },\ "ChargingMode": "Once",\ "PostingMode": "Once",\ "Ordering": 0\ }\ ],\ "TaxEnvironmentCode": "NL",\ "Telephone": "030 6926666",\ "TermsAndConditionsUrl": {\ "en-US": "https://website.com/terms-and-conditions.html"\ }\ },\ "OnlineTravelAgencies": [],\ "PaymentCardRequirement": "NotRequired",\ "RequiredFields": [],\ "ServiceId": "c1eec12a-1101-4bg6-ad24-e48f8dlpb9ee"\ }\ ], "Services": [\ {\ "Id": "c1eec12a-1101-4bg6-ad24-e48f8dlpb9ee",\ "EnterpriseId": "7a13590c-6538-461e-b02f-6357400de493",\ "Ordering": 1,\ "CreatedUtc": "2021-03-30T11:17:03Z",\ "IsActive": true,\ "Names": {\ "en-US": "Accommodation"\ },\ "ShortNames": {\ "en-US": "Accommodation"\ },\ "Data": {\ "Discriminator": "Bookable",\ "Value": {\ "StartOffset": "P0M0DT15H0M0S",\ "EndOffset": "P0M0DT12H0M0S",\ "TimeUnit": "Day"\ }\ }\ }\ ], "CurrencyCode": null, "CurrencyCodes": [], "DisplayVoucherCode": false, "EndDateOffset": null, "GtmContainerId": "", "IntroVideoUrl": "", "LanguageCode": null, "NowUtc": "2020-04-09T07:18:48Z", "PrimaryColor": "", "StartDateOffset": null, "Theme": null, "VoucherCode": "" } Property Type Contract Description `Cities` array of [City](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#city) required Cities supported by the enterprise. `CityId` string required Unique identifier of the default city. `Configurations` array of [Configurations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#configuration-1) required Configurations of the booking engine instances. `Services` array of [Services](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service) required Services that the configurations are set up for. `CurrencyCode` string optional ISO 4217 code of the currency which Mews Booking Engine should use when displaying prices. [Supported currency codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-currency-codes) `DisplayVoucherCode` boolean required Determines whether enterprise's voucher codes should be listed in Mews Booking Engine (voucher codes are listed by default). `StartDateOffset` number optional Number of days after the day that the customer is booking that will be selected as the default start date in the date picker (for example, if `3` is set and a customer uses the booking engine on the 1st day of the month, the default start date will be the 4th). If left blank, the default will be 0. `EndDateOffset` number optional Number of days after the day that the customer is booking that will be selected as the default end date in the date picker (for example, if `3` is set and a customer uses the booking engine on the 1st day of the month, the default end date will be the 3rd). If left blank, the default will be `4`. `GtmContainerId` string optional Google Tag Manager identifier. `IntroVideoUrl` string optional Booking engine's intro video URL. `LanguageCode` string optional Language code which Mews Booking Engine should use. [Supported language codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-language-codes) `NowUtc` string required Current server date and time in UTC timezone in ISO 8601 format. `PrimaryColor` string optional Booking engine's primary color in Hex format. `Theme` [Theme](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#theme) optional Booking engine's theme variant. `VoucherCode` string optional Voucher code which enables special rate offerings. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#theme) Theme * `Light` * `Dark` #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#city) City Property Type Contract Description `Id` string required Unique identifier of the city. `ImageId` string optional Unique identifier of the city image. `Name` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required City name. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#configuration) Configuration Property Type Contract Description `Id` string required Unique identifier of the configuration. `AdultCount` number optional Default number of adults. `ChildCount` number optional Default number of children. `ChildSelectionEnabled` boolean optional Determines whether to allow adding children to reservations (true by default). `CompetitorPriceRelativeAdjustment` number optional Percentage markup with which competitor's prices (listed in the rate comparison banner if `DisplayRateComparison` is set to `true`) will be shown, compared to enterprise's Best Available Rate (BAR). For example, if enterprise's BAR costs 50, and entered here is `1`, their rate will be shown as 50. If here is entered `1.1`, their rate will be shown as 55 (as here is added a 10% markup). `CompetitorRateDescription` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Description differentiating enterprise's online booking from competitors booking. (for example, `20% online booking discount` or `Breakfast included`). `DisplayAvailability` boolean optional Determines whether to display property's availability next to maximum occupancy in space categories (availability will be shown by default). `DisplayRateComparison` boolean optional Determines whether to display rate comparison. `DisplaySpecialRequests` boolean optional Determines whether to display special requests field during checkout. `Enterprise` [Enterprise](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#enterprise) required Enterprise to which the `Configuration` belongs. `OnlineTravelAgencies` array of string required Array of travel agencies to include in comparison banner. `PaymentCardRequirement` string [Payment card requirement](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#payment-card-requirement) required Determines how to handle payment cards. `RequiredFields` array of [Required fields](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#required-field) required Form fields which are required and need to be filled in. `ServiceId` string required Unique identifier of the service to which the configuration is bound. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service) Service Property Type Contract Description `Id` string required Unique identifier of the service. `EnterpriseId` string required Identifier of the enterprise the service belongs to. `Ordering` number required Number defining the ordering of the services. `CreatedUtc` string required Date and time of the service creation in UTC timezone in ISO 8601 format. `IsActive` boolean required Whether the service is still active. `Names` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Service name. `ShortNames` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Service short name. `Data` [Service data](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service-data) required Additional information about the specific service. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service-data) Service data Property Type Contract Description `Discriminator` string [Service data discriminator](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service-data-discriminator) required Determines type of value. `Value` object required Structure of object depends on [Service data discriminator](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service-data-discriminator) . #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service-data-discriminator) Service data discriminator * `Bookable` - Data specific to a bookable service. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#bookable-service-data) Bookable service data Property Type Contract Description `StartOffset` string required Offset from the start of the time unit defining the default start of the reservations in ISO 8601 duration format. `EndOffset` string required Offset from the end of the time unit defining the default end of the reservations in ISO 8601 duration format. `TimeUnit` [Time unit](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#time-unit) required Time unit of the service. Time units represent a fixed, finite time interval: a minute, a day, a month, etc. A Time unit defines the operable periods for a bookable service. We currently only support the Day unit. We think of the daily time unit as the physical time unit that starts at midnight and ends at midnight the following day. Start offsets are anchored to the start of the time unit and end offsets are anchored to the end of the time unit. `StartOffset` and `EndOffset` define the default start and end of the service (so, the service orders). Positive end offsets of the daily time unit define the nightly service as depicted in the diagram below. ![](https://mews-systems.gitbook.io/booking-engine-guide/~gitbook/image?url=https%3A%2F%2F3292240558-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FtIc30XOAP46ahd8X73va%252Fuploads%252Fgit-blob-4a607e5b429147631f96651d7eb859fd45ef3af0%252Ftimeunits-distributor-night.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=9ad86912&sv=2) Negative or zero end offsets of the daily time unit define the daily service as depicted in the diagram below. ![](https://mews-systems.gitbook.io/booking-engine-guide/~gitbook/image?url=https%3A%2F%2F3292240558-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FtIc30XOAP46ahd8X73va%252Fuploads%252Fgit-blob-7f1cb2523cdde8af8d4ebf2a226bcf9e07e93860%252Ftimeunits-distributor-day.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=2d381f45&sv=2) #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#time-unit) Time unit * `Day` * ... #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#payment-card-requirement) Payment card requirement * `NotRequired` - Payment card info is never required. * `AlwaysRequired` - Payment card info is always required and validated. * `NotRequiredForFullyPaidBookings` - Payment card info is not required for fully paid bookings. Otherwise required. * `NotRequiredForFullyOrPartiallyPaidBookings` - Payment card info is not required for fully or partially paid bookings. Otherwise required. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#required-field) Required field * `Telephone` #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#enterprise) Enterprise Property Type Contract Description `Id` string required Unique identifier of the enterprise. `AcceptedCurrencyCodes` array of string required Array of currency codes in ISO 4217 format accepted by the enterprise. `AdditionalLegalStatements` array of [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Additional legal statements. `Address` [Address](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#address) required Address of the enterprise. `Categories` array of [Room category](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-category) required Array of active room categories of the enterprise. `CategoryImageAssignments` array of [Category image assignment](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#category-image-assignment) required Array of images representing the category image. `CityId` string required Unique identifier of the [City](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#city) . `DefaultCurrencyCode` string required Default enterprise currency code in ISO 4217 format. `DefaultLanguageCode` string required Default enterprise language in ISO format. `DefaultRateCurrencyCode` string required Default enterprise rate currency code in ISO 4217 format. `Description` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Enterprise description. `Email` string required Email of the enterprise. `IanaTimeZoneIdentifier` string required IANA time zone identifer. `ImageId` string optional Unique identifier of the enterprise logo. `IntroImageId` string optional Unique identifier of the enterprise intro image. `Name` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Enterprise name. `Pricing` string [Pricing method](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#pricing-method) required Pricing method used by the enterprise. `PrivacyPolicyUrl` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Enterprise privacy policy URL. `Products` array of [Product](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product) required Array of active products which can be offered to the customer. `TaxEnvironmentCode` string required Tax environment code. `Telephone` string required Telephone of the enterprise. `TermsAndConditionsUrl` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Enterprise terms and conditions URL. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#address) Address Property Type Description `City` string optional City. `CountryCode` string optional ISO 3166-1 code of the [Country](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#country) . `Latitude` number optional The latitude. `Longitude` number optional The longitude. `Line1` string optional First address line. `Line2` string optional Second address line. `PostalCode` string optional Postal code. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#category-image-assignment) Category image assignment Property Type Contract Description `Id` string required Unique identifier of the room category. `CategoryId` string required Unique identifier of the [Room category](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-category) for which the image is attached. `ImageId` string required Unique identifier of the image that can be used in the [URL to get the image file](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/images) . `Ordering` number required Ordinal number of the image that can be used to display the images in order defined in the administration. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#pricing-method) Pricing method * `Gross` - The enterprise shows amount with gross prices. * `Net` - The enterprise shows amount with net prices. [PreviousAvailability blocks](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/availability-blocks) [NextHotels](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels) Last updated 9 months ago Was this helpful? --- # Reservation groups | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#create-reservation-group) Create reservation group ---------------------------------------------------------------------------------------------------------------------------------------------------------------- Create a group of one or more reservations, i.e. make a reservation. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#request) Request `[ApiBaseUrl]/api/distributor/v1/reservationGroups/create` Copy { "Client": "My Client 1.0.0", "ConfigurationId": "5dfgaeb5-5848-81b3-40b7-d102e96kcf52", "HotelId": "3edbe1b4-6739-40b7-81b3-d369d9469c48", "Customer": { "Email": "hiro@snow.com", "FirstName": "Hiro", "LastName": "Protagonist", "Telephone": "", "NationalityCode": "", "SendMarketingEmails": false }, "Booker": { "Email": "john.doe@snow.com", "FirstName": "John", "LastName": "Doe", "Telephone": "654257001458", "SendMarketingEmails": true }, "Reservations": [\ {\ "RoomCategoryId": "4037c0ec-a59d-43f1-9d97-d6c984764e8c",\ "StartUtc": "2015-01-01T00:00:00Z",\ "EndUtc": "2015-01-03T00:00:00Z",\ "VoucherCode": "Discount2042",\ "RateId": "c1d48c54-9382-4ceb-a820-772bf370573d",\ "AdultCount": 3,\ "ChildCount": 0,\ "ProductIds": [\ "d0e88da5-ae64-411c-b773-60ed68954f64"\ ],\ "Notes": "Quiet room please."\ }\ ], "CreditCardData": { "PaymentGatewayData": "...", "Expiration": "2030-10", "HolderName": "John Smith" }, "AvailabilityBlockId": "5mgbe1b4-6739-40b7-81b3-d369d9469c48" } Property Type Contract Description `Client` string required Client application name, as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `ConfigurationId` string required Unique identifier of the Booking Engine configuration used. `HotelId` string required Unique identifier of the hotel. `Customer` [Customer](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#customer) required Information about the customer or guest. `Booker` [Customer](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#customer) optional Information about the person making the booking. `Reservations` array of [Reservation data](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#reservation-data) required Reservation parameters, such as dates and quantities of persons. `CreditCardData` [Credit card data](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#credit-card-data) optional Credit card data, required if hotel has payment gateway. `AvailabilityBlockId` string optional Unique identifier of availability block if present. Provide always when you have it. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#customer) Customer Property Type Contract Description `Email` string required Email of the customer. `FirstName` string required First name of the customer. `LastName` string required Last name of the customer. `Telephone` string optional Telephone number of the customer. `NationalityCode` string optional ISO 3166-1 Aplha-2 code of the customer’s nation country, e.g.`US`. `SendMarketingEmails` boolean optional Subscribe to marketing emails. When `Booker` is present, this should be `false` or `null` because the customer is not subscribing, the booker is. See [Send marketing emails](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#send-marketing-emails) . #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#send-marketing-emails) Send marketing emails The boolean flag `SendMarketingEmails` indicates if the user has opted in to receive marketing communication or not. The API accepts the following values: * `true` - subscription is created * `false` - subscription is disabled * `null` - subscription remains untouched When `Booker` is present in the request, we assume that the booker is booking on behalf of the customer, but their opt-in to marketing communication is for them as user and not for the customer. Therefore, the `SendMarketingEmails` property for the booker should be set according to the user's choice, while the `SendMarketingEmails` property for the customer should be set to `false` or `null`. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#reservation-data) Reservation data Property Type Contract Description `RoomCategoryId` string required Identifier of the requested room or space category. `StartUtc` string required Start date of the reservation, i.e. arrival date. `EndUtc` string required End date of the reservation, i.e. departure date. `VoucherCode` string optional A voucher code, to be paired with reservation for later retrieval only. The actual voucher rate used is determined by setting a proper `RateId`. `RateId` string required Identifier of the chosen rate. `AdultCount` number required Number of adults. `ChildCount` number required Number of children. `ProductIds` array of string optional Unique identifiers of the requested products. `Notes` string optional Additional notes. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#credit-card-data) Credit card data Property Type Contract Description `PaymentGatewayData` string required Encoded payment card data obtained from the payment gateway specific library. For more details, see our [Supporting payment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/supporting-payment-cards) use case. `Expiration` string required Expiration date of payment card, in format `YYYY-MM`. `HolderName` string required Name of the card holder. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#response) Response Copy { "Id": "f6fa7e62-eb22-4176-bc49-e521d0524dee", "CustomerId": "7ac6ca0d-7c08-4ab1-8da8-9b44979d8855", "Reservations": [\ {\ "Id": "123456ec-a59d-43f1-9d97-d6c984764e8c",\ "RoomCategoryId": "4037c0ec-a59d-43f1-9d97-d6c984764e8c",\ "StartUtc": "2015-01-01T00:00:00Z",\ "EndUtc": "2015-01-03T00:00:00Z",\ "RateId": "c1d48c54-9382-4ceb-a820-772bf370573d",\ "Rate": {\ "Id": "c1d48c54-9382-4ceb-a820-772bf370573d",\ "Name": {\ "en-US": "Rate"\ },\ "Description": {\ "en-US": "Best rate available."\ }\ },\ "AdultCount": 3,\ "ChildCount": 0,\ "ProductIds": [\ "d0e88da5-ae64-411c-b773-60ed68954f64"\ ],\ "Notes": "Quiet room please.",\ "Amount": { },\ "Number": "1234"\ }\ ], "PaymentRequestId": "2e3a700a-7b10-4e61-8e9f-acfa00ee00df", "PaymentCardId": "dc2f8608-9d71-47fd-9d41-ad1a009913c6", "TotalAmount": { } } Property Type Contract Description `Id` string required Unique identifier of the created reservation group. `CustomerId` string required Unique identifier of the reservation group customer. `Reservations` array of [Reservation](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#reservation) required Details of the reservations in the group. `PaymentRequestId` string optional Unique identifier of the [Payment request](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-request) that can be used to complete [on session payment](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/on-session-payments) . `PaymentCardId` string optional Unique identifier of the [Payment card](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards#payment-card) that can be used to complete [on session payment card authorization](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/payment-card-authorization) . `TotalAmount` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#multi-currency-amount) required Total amount of the whole group. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#reservation) Reservation Property Type Contract Description `Id` string required Identifier of the reservation. `Number` string required Confirmation number of the reservation. `RoomCategoryId` string required Identifier of the requested room or space category. `StartUtc` string required Start date of the reservation, i.e. arrival date. `EndUtc` string required End date of the reservation, i.e. departure date. `AdultCount` number required Number of adults. `ChildCount` number required Number of children. `ProductIds` array of string optional Unique identifiers of the requested products. `RateId` string required Identifier of the chosen rate. `Notes` string optional Additional notes. `Amount` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#multi-currency-amount) required Total amount of the reservation. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#documentation-update-reservation-status-based-on-feature-setting) Documentation Update: Reservation Status Based on Feature Setting #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#enable-automatic-cancellation-for-optional-reservations) Enable Automatic Cancellation for Optional Reservations **When the feature** [**Enable automatic cancellation for optional reservations**](https://help.mews.com/s/article/confirm-or-cancel-optional-reservations?language=en_US) **is activated on your bookable service under** _**Visit Options**_**:** * Reservations with a balance due upon confirmation will initially be set to an **Optional** state. * These reservations will only transition to a **Confirmed** status upon successful payment of the due amount. **If the feature is not activated:** * Reservations will be created directly in the **Confirmed** state. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#error-response) Error response In case of an error caused by insufficient availability (which might have decreased since the time it was provided to the client), the error response may contain the following fields on top of the standard ones: Property Type Contract Description `ExceedingReservationIndexes` array of number optional Indexes of reservations from the request that are not available anymore. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#get-reservation-group) Get reservation group ---------------------------------------------------------------------------------------------------------------------------------------------------------- Fetch details of the specified reservation group. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#request-1) Request `[ApiBaseUrl]/api/distributor/v1/reservationGroups/get` Copy { "Client": "My Client 1.0.0", "HotelId": "3edbe1b4-6739-40b7-81b3-d369d9469c48", "ReservationGroupId": "f6fa7e62-eb22-4176-bc49-e521d0524dee", "Extent": { "PaymentRequests": false, "Payments": false } } Property Type Contract Description `Client` string required Client application name, as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `HotelId` string required Unique identifier of the hotel. `ReservationGroupId` string required Unique identifier of the reservation group. `Extent` [Reservation group extent](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#reservation-group-extent) optional Extent of data to be returned. e.g. it is possible to specify that together with the reservation group, payment requests and payments will be returned. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#reservation-group-extent) Reservation group extent Property Type Contract Description `PaymentRequests` boolean optional Whether the response should contain [Payment requests](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-request) related to the reservation group. `Payments` boolean optional Whether the response should contain [Payment](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment) attempts related to the [Payment requests](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-request) for reservation group. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#response-1) Response Copy { "Id": "f6fa7e62-eb22-4176-bc49-e521d0524dee", "CustomerId": "7ac6ca0d-7c08-4ab1-8da8-9b44979d8855", "Reservations": [\ {\ "Id": "123456ec-a59d-43f1-9d97-d6c984764e8c",\ "RoomCategoryId": "4037c0ec-a59d-43f1-9d97-d6c984764e8c",\ "StartUtc": "2015-01-01T00:00:00Z",\ "EndUtc": "2015-01-03T00:00:00Z",\ "RateId": "c1d48c54-9382-4ceb-a820-772bf370573d",\ "Rate": {\ "Id": "c1d48c54-9382-4ceb-a820-772bf370573d",\ "Name": {\ "en-US": "Rate"\ },\ "Description": {\ "en-US": "Best rate available."\ }\ },\ "AdultCount": 3,\ "ChildCount": 0, \ "ProductIds": [\ "d0e88da5-ae64-411c-b773-60ed68954f64"\ ],\ "Notes": "Quiet room please.",\ "Amount": { },\ "Number": "1234"\ }\ ], "PaymentRequestId": "2e3a700a-7b10-4e61-8e9f-acfa00ee00df", "TotalAmount": { }, "PaymentRequests": [\ {\ "Id": "ace78dac-a0f3-420e-8a42-acfb00b9e1e5",\ "ReservationGroupId": "f6fa7e62-eb22-4176-bc49-e521d0524dee",\ "State": "Completed"\ }\ ], "Payments": [\ {\ "Id": "21639c17-edad-47f9-8348-acfb00b9f569",\ "EnterpriseId": "8a51f050-8467-4e92-84d5-abc800c810b8",\ "PaymentRequestId": "ace78dac-a0f3-420e-8a42-acfb00b9e1e5",\ "CreatedUtc": "2021-03-30T11:17:03Z",\ "State": "Charged",\ "Amount": {\ "Currency": "EUR",\ "GrossValue": 929.70,\ "NetValue": 929.70,\ "TaxValues": []\ },\ "ChargeAmount": {\ "Currency": "EUR",\ "GrossValue": 929.70,\ "NetValue": 929.70,\ "TaxValues": []\ }\ }\ ] } Property Type Contract Description `Id` string required Unique identifier of the created reservation group. `CustomerId` string required Unique identifier of customer who created reservation group. `Reservations` array of [Reservation](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#reservation) required Details of the created reservations in the group. `PaymentRequestId` string optional Unique identifier of payment request that can be used to complete [on session payment](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/use-cases/on-session-payments) . `TotalAmount` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#multi-currency-amount) required Total amount of the whole group. `PaymentRequests` array of [Payment request](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-request) optional Contains payment requests related to the reservation group. `Payments` array of [Payment](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment) optional Contains Payments related to the payment requests. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-request) Payment request Property Type Contract Description `Id` string required Unique identifier of the payment request. `ReservationGroupId` string required Identifier of the related reservation group. `State` string [Payment request state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-request-state) required State of the payment request. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-request-state) Payment request state * `Pending` - Non-finite state. Awaiting a next action. * `Completed` - Finite state. Payment request that has been covered by payment. * `Canceled` - Finite state. Payment request has been manually canceled by the creator (enterprise). * `Expired` - Finite state. Payment request has not been completed within its expiration time. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment) Payment Property Type Contract Description `Id` string required Unique identifier of the payment. `Amount` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#amount) required Amount in a currency which was used to create the [Payment request](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-request) - usually the default currency of the enterprise. `ChargeAmount` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#amount) required Amount in currency which was used for the payment during the charge. i.e. currency that will be visible on the user bank statement for the payment. `CreatedUtc` string required Date and time of the payment creation in UTC timezone in ISO 8601 format. `EnterpriseId` string required Identifier of the enterprise receiving the payment. `PaymentRequestId` string required Identifier of the payment request. `State` string [Payment state](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-state) required State of the payment attempt. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#amount) Amount Property Type Contract Description `Currency` string required ISO 4217 code of the currency. `GrossValue` number required Gross value of the amount. (Net + sum of `TaxValues`) `NetValue` number required Net value of the amount. `TaxValues` array of [Tax values](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#tax-value) required Tax values of the amount. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups#payment-state) Payment state * `Pending` - Non-finite state. Payment has been created, but the state is not known yet. * `Verifying` - Non-finite state. Payment is awaiting a 3DS verification. * `Charged` - Finite state. Payment has been successfully charged. * `Canceled` - Finite state. Payment has been canceled, and it has not been charged. * `Failed` - Finite state. Payment has not been charged. [PreviousReservations](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservations) [NextServices](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services) Last updated 9 months ago Was this helpful? --- # Door | Open API This category covers door locks and other access control solutions. The most common integration is an on-premise key encoder or key cutter, which is considered as a type of [Device integration](https://mews-systems.gitbook.io/open-api/use-cases/devices) . These resources may also be helpful: * [How do key cutter integrations work](https://help.mews.com/s/article/how-do-key-cutter-integrations-work?language=en_US&Language=en_US) * [How does a key cutter integration work with a Mews Kiosk](https://help.mews.com/s/article/how-does-a-key-cutter-integration-work-with-a-mews-kiosk?language=en_US) [PreviousDistribution](https://mews-systems.gitbook.io/open-api/use-cases/distribution) [NextEvents](https://mews-systems.gitbook.io/open-api/use-cases/events) Last updated 3 years ago Was this helpful? --- # Distribution | Open API Distribution refers to the Channel Manager integrations through which availability, rates and inventory are distributed, and from which reservations are made. See the [Mews Channel Manager API](https://mews-systems.gitbook.io/channel-manager-api/) . [PreviousCustomer Relationship](https://mews-systems.gitbook.io/open-api/use-cases/crm) [NextDoor](https://mews-systems.gitbook.io/open-api/use-cases/door) Last updated 3 years ago Was this helpful? --- # Hotels | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-hotels) Get hotels ------------------------------------------------------------------------------------------------------------------------ Get hotels data for a single specified hotel. This operation can be called initially to fetch data which may be important during the booking workflow. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#request) Request `[ApiBaseUrl]/api/distributor/v1/hotels/get` Copy { "Client": "My Client 1.0.0", "HotelId": "3edbe1b4-6739-40b7-81b3-d369d9469c48" } Property Type Contract Description `Client` string required Identification of the client, as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `HotelId` string required Unique identifier of the hotel. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#response) Response Copy { "Languages": [\ {\ "Code": "en-US",\ "Name": "English (United States)",\ "DefaultCulture": {\ "CurrencyDecimalSeparator": ",",\ "CurrencyGroupSeparator": "."\ }\ }\ ], "Currencies": [\ {\ "Code": "CZK",\ "Symbol": "Kč",\ "ValueFormat": "#,##0 \"Kč\";−#,##0 \"Kč\"",\ "DecimalPlaces": 0,\ "SymbolIsBehindValue": true\ }\ ], "Countries": [\ {\ "Code": "CZ",\ "Name": "Czech Republic"\ }\ ], "ImageBaseUrl": "https://cdn.mews-demo.com/Media/Image", "Id": "3edbe1b4-6739-40b7-81b3-d369d9469c48", "Name": { "en-US": "Distributor api hotel" }, "Description": { "en-US": "" }, "CityId": "e5fd108e-1e0a-4cc4-9d3a-34d7e0e57527", "ImageId": "87ead9b6-8c96-4b3c-a90d-fb8a02a005ad", "IntroImageId": "c0dcec83-96a4-44b5-a898-de2becbbdb5e", "DefaultLanguageCode": "en-US", "DefaultCurrencyCode": "EUR", "DefaultRateCurrencyCode": "EUR", "SupportedLanguageCodes": [\ "cs-CZ",\ "da-DK",\ "de-CH",\ "de-DE",\ "el-GR",\ "en-GB",\ "ta-IN",\ "tr-TR",\ "uk-UA",\ "en-US"\ ], "AcceptedCurrencyCodes": [\ "CZK",\ "EUR",\ "USD"\ ], "RoomCategories": [\ {\ "Id": "d79fa529-d95e-485e-b81b-e8a669a1062a",\ "Name": {\ "en-US": "King Double Room"\ },\ "Description": {\ "en-US": "The double rooms have two separate beds, 2 x 105 wide."\ },\ "Ordering": 4,\ "NormalBedCount": 2,\ "ExtraBedCount": 0,\ "SpaceType": "Room"\ }\ ], "Products": [\ {\ "Id": "4fd0e6e0-101c-410d-8c12-ad6000b7e390",\ "Name": {\ "en-US": "Breakfast"\ },\ "Description": {},\ "CategoryId": "77e0a18c-f2a5-418f-b578-16d3599c059d",\ "ImageId": null,\ "IncludedByDefault": false,\ "Pricing": {\ "Discriminator": "Absolute",\ "Value": {\ "CHF": {\ "Currency": "CHF",\ "GrossValue": 108.31,\ "NetValue": 98.46,\ "TaxValues": [\ {\ "TaxRateCode": "CZ-L",\ "Value": 9.85\ }\ ]\ },\ "EUR": {\ "Currency": "EUR",\ "GrossValue": 100,\ "NetValue": 90.91,\ "TaxValues": [\ {\ "TaxRateCode": "CZ-L",\ "Value": 9.09\ }\ ]\ }\ }\ },\ "ChargingMode": "PerTimeUnit",\ "PostingMode": "PerTimeUnit",\ "Ordering": 1\ },\ {\ "Id": "5d6de830-8ada-4b65-b72c-60fc1e719f1b",\ "Name": {\ "nl-NL": "Extra bedlinnen",\ "en-US": "Extra bedlinnen (Once Off)"\ },\ "Description": {},\ "CategoryId": "77e0a18c-f2a5-418f-b578-16d3599c059d",\ "ImageId": "ec643f33-cd6c-4250-accd-518182165ffe",\ "IncludedByDefault": false,\ "Pricing": {\ "Discriminator": "Relative",\ "Value": {\ "ProductIds": [],\ "TaxRateCodes": [\ "CZ-L"\ ],\ "Multiplier": 0.05,\ "Target": "GrossValue"\ }\ },\ "ChargingMode": "Once",\ "PostingMode": "Once",\ "Ordering": 0\ }\ ], "PaymentGateway": { "PaymentGatewayType": "PciProxy", "IsMerchant": true, "SupportedCreditCardTypes": [\ "MasterCard",\ "Visa",\ "Amex"\ ], "PublicKey": "1100016827" }, "TermsAndConditionsUrl": "https://app.mews-demo.com/Platform/Document/TermsAndConditions/3edbe1b4-6739-40b7-81b3-d369d9469c48", "IanaTimeZoneIdentifier": "Europe/Budapest", "Email": "distributor-api@mews.li", "Telephone": "+", "AdditionalLegalStatements": [], "Address": { "Line1": "Staromestske namesti 16", "Line2": "", "City": "Prague", "PostalCode": "11000", "CountryCode": "US", "Latitude": null, "Longitude": null } } Property Type Contract Description `Countries` array of [Country](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#country) required Countries supported by the hotel. `Currencies` array of [Currency](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#currency) required Currencies accepted by the hotel. `DefaultCurrencyCode` string required Code of hotel’s default currency. `DefaultLanguageCode` string required Code of hotel’s default language. `DefaultRateCurrencyCode` string required Code of currency of hotel’s default rate. `IanaTimezoneIdentifier` string required Iana identifier of hotel’s time zone `ImageId` string optional Unique identifier of hotel’s logo image. `IntroImageId` string optional Unique identifier of hotel’s intro image (usable as background image). `Languages` array of [Language](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#language) required Languages supported by the hotel. `Name` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Name of the hotel. `Description` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Description of the hotel. `PaymentGateway` one of [Payment gateway](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#payment-gateway) types optional Info about payment gateway used by the hotel. `Products` array of [Product](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product) required All products orderable with rooms associated with the first bookable service in the list of services of this enterprise. `RoomCategories` array of [Room category](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-category) required All room categories offered by hotel. `TermsAndConditionsUrl` string optional URL of hotel’s terms and conditions. `ImageBaseUrl` string required Base URL of images. > The returned list of products contains only the products associated with the first bookable service in the list of services of this enterprise. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#country) Country Property Type Contract Description `Code` string required ISO 3166-1 Aplha-2 code of the country. `Name` string required Name of the country. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#currency) Currency Property Type Contract Description `Code` string required Code of the currency in ISO 4217 format. `Symbol` string required Symbol of the currency. `ValueFormat` string required Format of a currency value (for both positive and negative values, including symbol). `DecimalPlaces` number required Number of decimal places used with the currency value. `SymbolIsBehindValue` boolean required Indicates whether the symbol stands behind a value in standard formatting. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#language) Language Property Type Contract Description `Code` string required Language code. `Name` string required Name of the language. `DefaultCulture` [Culture](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#culture) required Specifics of a default culture for the language. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#culture) Culture Property Type Contract Description `CurrencyDecimalSeparator` string required Symbol used to separate decimal places in the currency value format. `CurrencyGroupSeparator` string required Symbol used to separate thousands in the currency value format. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) Localized text A localized text is an object of the property values localized into languages supported by hotel, indexed by language codes. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#payment-gateway) Payment gateway If the hotel does not use any payment gateway, the value is null. If it does, then you should use a specific API call and the gateway’s library to encode credit card data. The main purpose of a payment gateway is to securely obtain the credit card of the customer before a reservation is created. You can decide not to support any of them and just ignore it, in which case reservations are created with a note about missing credit card. Property Type Contract Description `PaymentCardStorageType` string [Payment card storage type](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#payment-card-storage-type) required Type of the payment card storage used by enterprise. `IsMerchant` boolean required Whether the gateway is processed through **Mews Payments** or not (formerly called Mews Merchant). `SupportedCreditCardTypes` array of [Credit card type](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#credit-card-type) required Supported payment cards, should be used to enhance UX. `PublicKey` string required Merchant identifier for which PCI Proxy iframe is connected. `DefaultCurrencyCode` string required Currency code of default payment gateway in ISO 4217 format. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#payment-card-storage-type) Payment card storage type * `PciProxy` #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#credit-card-type) Credit card type * `MasterCard` * `Visa` * `Amex` * `Discover` * `DinersClub` * `Jcb` * `Maestro` * ... #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product) Product Property Type Contract Description `Id` string required Unique identifier of the product. `CategoryId` string optional Unique identifier of the product category. `Name` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Name of the product localized into all supported languages. `Description` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Description of the product localized into all supported languages. `ImageId` string optional Unique identifier of the product’s image. `IncludedByDefault` boolean required Indicates whether the product should be added to order by default. `Pricing` [Pricing coproduct](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#pricing-coproduct) required Object defining the pricing method and price values. `ChargingMode` string [Product charging mode](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product-charging-mode) required Charging mode of the product. `PostingMode` string [Product posting mode](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product-posting-mode) required Posting mode of the product. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#pricing-coproduct) Pricing coproduct Property Type Contract Description `Discriminator` string [Pricing data discriminator](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#pricing-data-discriminator) required Determines type of value. `Value` [Multi-currency amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#multi-currency-amount) / [Relative price data value](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#relative-price-data-value) required Structure of object depends on the [Pricing data discriminator](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#pricing-data-discriminator) #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#pricing-data-discriminator) Pricing data discriminator * `Absolute` - Data specific to absolutely priced product are represented by [Multi-currency amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#multi-currency-amount) . * `Relative` - Data specific to relatively priced product are represented by [Relative price data value](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#relative-price-data-value) . #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#relative-price-data-value) Relative price data value Property Type Contract Description `ProductIds` array of string required Unique identifiers of [Products](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product) used to calculate the price of the relatively priced product. `Multiplier` number required Percentage of the relative price. `Target` [Relative price target](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#relative-price-target) required Target defining whether the price of a product should be calculated by multiplying gross value, tax value or net value of dependant products. `TaxRateCodes` array of string required Tax rate codes that should be applied to the price in order to calculate the taxes of the product. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#relative-price-target) Relative price target * `GrossValue` - The price of the product should be calculated from gross value of dependant products * `TaxValue` - The price of the product should be calculated from tax value of dependant products * `NetValue` - The price of the product should be calculated from net value of dependant products #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product-charging-mode) Product charging mode * `Once` * `PerTimeUnit` * `PerPersonPerTimeUnit` * `PerPerson` #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#product-posting-mode) Product posting mode * `Once` * `PerTimeUnit` #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#multi-currency-amount) Multi-currency amount An object where name corresponds to ISO code and value represents a structure that holds gross price, net price and tax values. Copy { "USD": { "GrossValue": 100.00, "NetValue": 93.46, "TaxValues": [\ {\ "TaxRateCode": "DE-R",\ "Value": 6.54\ }\ ] } } Property Type Description `GrossValue` Number Net price + taxes `NetValue` Number Amount without taxes `TaxValues` Collection of [Tax values](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#tax-value) Tax values for the net value amount #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#tax-value) Tax value Property Type Description `TaxRateCode` string Unique identifier of the rate. `Value` Number Amount of tax #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-category) Room category Property Type Contract Description `Id` string required Unique identifier of the room category. `Name` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Name of the room category localized into all supported languages. `Description` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Description of the room category localized into all supported languages. `NormalBedCount` number required Number of normal beds in the room category. `ExtraBedCount` number required Number of extra beds possible in the room category. `SpaceType` [Space type](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#space-type) required Type of the room category. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#space-type) Space type * `Room` * `Dorm` * `Bed` * ... [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-availability) Get availability ------------------------------------------------------------------------------------------------------------------------------------ Get availability and pricing options for the specified hotel for the specified date interval. Further optional parameters can be supplied, such as room categories and voucher codes. The availability and pricing is returned for each applicable combination of occupancy and rate, for each available room category. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#request-1) Request `[ApiBaseUrl]/api/distributor/v1/hotels/getAvailability` Copy { "Client": "My Client 1.0.0", "ConfigurationId": "5dfgaeb5-5848-81b3-40b7-d102e96kcf52", "HotelId": "3edbe1b4-6739-40b7-81b3-d369d9469c48", "StartUtc": "2015-01-01T00:00:00Z", "EndUtc": "2015-01-03T00:00:00Z", "ProductIds": [\ "d0e88da5-ae64-411c-b773-60ed68954f64"\ ], "CurrencyCode": "EUR", "VoucherCode": "Discount2042", "OccupancyData": [\ {\ "AgeCategoryId": "47ae3dbb-0de6-4afd-845b-af4900c21e2c",\ "PersonCount": 2\ }\ ], "CategoryIds": [\ "295d96e7-8501-4cbd-b78d-8bf590bf6db9"\ ], "AvailabilityBlockId": "5mgbe1b4-6739-40b7-81b3-d369d9469c48" } Property Type Contract Description `Client` string required Identification of the client as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `ConfigurationId` string required Unique identifier of the used Distributor configuration. `HotelId` string required Unique identifier of hotel. `StartUtc` string required Reservation start date (arrival date) in ISO 8601 format. `EndUtc` string required Reservation end date (departure date) in ISO 8601 format. `ProductIds` array of string optional Unique identifiers of products which should be included into pricing calculations. `CurrencyCode` string optional ISO 4217 code of the currency. If specified the prices in response will contain only single currency based on the code provided. [Supported currency codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-currency-codes) `VoucherCode` string optional Voucher code enabling special rate offerings. `OccupancyData` array of [Occupancy Data](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#occupancy-data) required Occupancy numbers for the reservations. `~AdultCount~` ~number~ ~optional~ ~Requested number of adults. If provided together with~ `~ChildCount~`~, then~ `~RoomOccupancyAvailabilities~` ~will be computed only for that combination instead of all possible. If~ `~RoomCategory~` ~doesn’t support the given values, then the nearest applicable values are found.~ **Deprecated!** `~ChildCount~` ~number~ ~optional~ ~Requested number of children.~ **Deprecated!** `CategoryIds` array of string optional Unique identifiers of categories for which should be the availability computed only. If omitted, availability of all categories is returned instead. `AvailabilityBlockId` string optional Unique identifier of availability block, if present. When provided, only availability for this block is returned. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#occupancy-data) Occupancy Data Property Type Contract Description `AgeCategoryId` string required Age category identifier - see [Where can I get Age Category ID?](https://mews-systems.gitbook.io/booking-engine-guide/faq#where-can-i-get-age-category-id) . `PersonCount` number required Number of people in the given age category. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#response-1) Response Copy { "RateGroups": [\ {\ "Id": "634d4625-e127-4282-a17d-ab51010e4deb",\ "SettlementType": "Manual",\ "SettlementAction": "ChargeCreditCard",\ "SettlementTrigger": "Start",\ "SettlementOffset": "P0M0DT0H0M0S",\ "SettlementValue": 1.00000000,\ "SettlementFlatValue": null,\ "SettlementMaximumTimeUnits": null\ }\ ], "Rates": [\ {\ "Id": "c1d48c54-9382-4ceb-a820-772bf370573d",\ "Name": {\ "en-US": "Rate"\ },\ "Description": {\ "en-US": "Best rate available."\ },\ "IsPrivate": false\ }\ ], "RoomCategoryAvailabilities": [\ {\ "RoomCategoryId": "4037c0ec-a59d-43f1-9d97-d6c984764e8c",\ "AvailableRoomCount": 5,\ "RoomOccupancyAvailabilities": [\ {\ "AdultCount": 1,\ "ChildCount": 0,\ "OccupancyData": [\ {\ "AgeCategoryId": "47ae3dbb-0de6-4afd-845b-af4900c21e2c",\ "PersonCount": 1\ }\ ],\ "Pricing": [\ {\ "RateId": "c1d48c54-9382-4ceb-a820-772bf370573d",\ "Price": { },\ "MaxPrice": { }\ }\ ]\ },\ {\ "AdultCount": 2,\ "ChildCount": 0,\ "OccupancyData": [\ {\ "AgeCategoryId": "47ae3dbb-0de6-4afd-845b-af4900c21e2c",\ "PersonCount": 2\ },\ ],\ "Pricing": [\ {\ "RateId": "c1d48c54-9382-4ceb-a820-772bf370573d",\ "Price": {\ "TotalAmount": { },\ "AverageAmountPerTimeUnit": { }\ },\ "MaxPrice": {\ "TotalAmount": { },\ "AverageAmountPerTimeUnit": { }\ }\ }\ ]\ }\ ]\ }\ ] } Property Type Contract Description `RateGroups` array of [Rate group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#rate-group) required Information about all available rate groups. `Rates` array of [Rate](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#rate) required Information about all available rates. `RoomCategoryAvailabilites` array of [Room category availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-category-availability) required Availabilities of room categories. If a room category is not available, it is not included. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#rate-group) Rate group Property Type Contract Description `Id` string required Unique identifier of the rate. `SettlementType` string [Settlement type](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#settlement-type) required Determines if system will charge reservation cost automatically or if you'd like employees to manually process payments. `SettlementAction` string [Settlement action](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#settlement-action) required Determines how payment will be taken at time of automatic trigger. Valid if settlement is automatic only. `SettlementTrigger` string [Settlement trigger](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#settlement-trigger) required Moment when amount is automatically charged, with offset applying to this time (for example, a 'Creation' trigger with no offset will charge the amount when items are created). If settlement is manual, a task will be created at this moment. `SettlementOffset` string required Start of the interval in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601#Durations) which gets added before or after selected settlement trigger (for example, '-1 day' will charge the amount 1 day before). `SettlementValue` number optional Percentage of the total extent cost which is charged automatically (for example, a `1.0` settlement value will charge the full cost of extent included below). Value is charged at the time of settlement trigger plus time difference from offset. When null, `FlatValue` is provided with absolute decimal value. `SettlementFlatValue` number optional Absolute value of settlement cost in settlement currency code. When provided `SettlementValue` is `null` `SettlementCurrencyCode` number required Settlement currency code `SettlementMaximumTimeUnits` number optional Maximum number of time units that will be charged automatically (only applies to automatic settlements). The rest will be charged manually. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#settlement-type) Settlement type * `Automatic` * `Manual` #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#settlement-action) Settlement action * `ChargeCreditCard` * `CreatePreauthorization` #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#settlement-trigger) Settlement trigger * `Confirmation` * `Start` * `End` * `StartDate` * `EndDate` #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#rate) Rate Property Type Contract Description `Id` string required Unique identifier of the rate. `Name` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Name of the rate localized into all supported languages. `Description` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Description of the rate localized into all supported languages. `IsPrivate` boolean required Set to `true` for promotion rate enabled by provided `VoucherCode` #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-category-availability) Room category availability Property Type Contract Description `RoomCategoryId` string required Unique identifier of the room category. `RoomOccupancyAvailabilities` array of [Room occupancy availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-occupancy-availability) required Availabilities of rooms in the category by the room occupancy. `AvailableRoomCount` number required Number of available rooms from the room category. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-occupancy-availability) Room occupancy availability Property Type Contract Description `~AdultCount~` ~number~ ~required~ ~Number of adults for the associated pricing.~ **Deprecated!** `~ChildCount~` ~number~ ~required~ ~Number of childs for the associated pricing.~ **Deprecated!** `OccupancyData` array of [OccupancyData](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#occupancy-data) required List of occupancy data. `Pricing` array of [Pricing](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#pricing) required Pricing information. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#pricing) Pricing Property Type Contract Description `RateId` string required Unique identifier of a rate. `Price` [Room price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-price) required Price of the room. `MaxPrice` [Room price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-price) required Max price of the room with the same parameters and conditions among other rates. Can be understood (and possibly displayed) as the value before discount. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-price) Room price Property Type Contract Description `TotalAmount` [Multi-currency amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#multi-currency-amount) required Total amount of the room for whole reservation. `AverageAmountPerTimeUnit` [Multi-currency amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#multi-currency-amount) required Average amount per time unit. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#get-payment-configuration) Get payment configuration ------------------------------------------------------------------------------------------------------------------------------------------------------ Fetch payment configuration parameters for the specified hotel. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#request-2) Request `[ApiBaseUrl]/api/distributor/v1/hotels/getPaymentConfiguration` Copy { "Client": "My Client 1.0.0", "HotelId": "3edbe1b4-6739-40b7-81b3-d369d9469c48" } Property Type Contract Description `Client` string required Identification of the client as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `HotelId` string required Unique identifier of hotel. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#response-2) Response Copy { "PaymentGateway": { "PaymentGatewayType": "PciProxy", "PaymentCardStorageType": "PciProxy", "IsMerchant": true, "SupportedCreditCardTypes": [\ "MasterCard",\ "Visa"\ ], "PublicKey": "1100116614", "DefaultCurrencyCode": "EUR" }, "SurchargeConfiguration": { "SurchargeServiceId": "74d5eb0a-784a-4870-b34a-ab6500a1136e", "SurchargeFees": { "MasterCard": 0.02, "Visa": 0.01, "Amex": 0.0125 } } } Property Type Contract Description `PaymentGateway` [Payment gateway](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#payment-gateway) required Object that describes payment gateway of the enterprise. `SurchargeConfiguration` [Surcharge configuration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#surcharge-configuration) required Object describing surcharge configuration used by the enterprise. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#surcharge-configuration) Surcharge configuration Property Type Contract Description `SurchargeServiceId` string optional Unique identifier of surcharge service. `SurchargeFees` [Surcharge fees](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#surcharge-fees) required Surcharge fees are additional fees charged by payment card company. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#surcharge-fees) Surcharge fees Property Type Contract Description `Key` string [Credit card type](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#credit-card-type) required Credit card type. `Value` number required Amount of the surcharge fee itself. [PreviousConfiguration](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration) [NextPayment cards](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/payment-cards) Last updated 9 months ago Was this helpful? --- # Revenue Management | Open API For Revenue Management Systems (RMS) integrations, take a look at the [Revenue management use case](https://mews-systems.gitbook.io/connector-api/use-cases/revenue-management) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api) . [PreviousReputation & Loyalty](https://mews-systems.gitbook.io/open-api/use-cases/reputation-loyalty) [NextService Optimization](https://mews-systems.gitbook.io/open-api/use-cases/service-optimization) Last updated 3 years ago Was this helpful? --- # Guest Technology | Open API Guest Technology integrations covers a range of use cases related to guest-facing technologies, whether in-room, mobile or in shared spaces. These include telephones, TVs and other entertainment systems, and may include in-room controls. Take a look at the [Guest technology use case](https://mews-systems.gitbook.io/connector-api/use-cases/guest-technology) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api) . [PreviousGuest Services](https://mews-systems.gitbook.io/open-api/use-cases/guest-services) [NextKiosk](https://mews-systems.gitbook.io/open-api/use-cases/kiosk) Last updated 3 years ago Was this helpful? --- # Services | Booking Engine Guide [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#get-services-availability) Get services availability -------------------------------------------------------------------------------------------------------------------------------------------------------- Get availability for the specified service for each time unit in the specified date interval. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#request) Request `[ApiBaseUrl]/api/distributor/v1/services/getAvailability` Copy { "Client": "My Client 1.0.0", "EnterpriseId": "3edbe1b4-6739-40b7-81b3-d369d9469c48", "ServiceId": "40665467-5862-4932-a861-aa6b00e2b660", "StartUtc": "202-01-01T00:00:00Z", "EndUtc": "2022-01-31T00:00:00Z", "CategoryIds": ["4037c0ec-a59d-43f1-9d97-d6c984764e8c"], "LanguageCode": "en-GB" } Property Type Contract Description `Client` string required Identification of the client as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `EnterpriseId` string required Unique identifier of the enterprise. `ServiceId` string required Unique identifier of the [Service](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service) for which availability should be returned. `StartUtc` string required Start date of the requested interval. `EndUtc` string required End date of the requested interval. `CategoryIds` array of string optional Unique identifiers of specific categories for which availability should be returned. If omitted, availability will be returned for all categories. `LanguageCode` string optional Code of the language. [Supported language codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-language-codes) ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#response) Response Copy { "TimeUnitStartsUtc": [\ "2022-10-04T22:00:00Z",\ "2022-10-05T22:00:00Z",\ "2022-10-06T22:00:00Z"\ ], "CategoryAvailabilities": [\ {\ "CategoryId": "ddc48d9f-f21d-422a-b24a-aa6b00e2b77e",\ "Availabilities": [\ 56,\ 40,\ 26\ ]\ },\ {\ "CategoryId": "abcdefg-08ad-4d19-98cc-aa6b00e2999e",\ "Availabilities": [\ 0,\ 10,\ 0\ ]\ }\ ] } Property Type Contract Description `TimeUnitStartsUtc` array of string required Each time unit specified in request interval. Values are in UTC timezone in ISO 8601 format. `CategoryAvailabilities` array of [Category Availability](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#category-availability) required List of availability counts for each category. Each availability number belongs to TimeUnitStartsUtc linked by same index. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#category-availability) Category Availability Property Type Contract Description `CategoryId` string required Identifier of the room category. `Availabilities` array of number required List of availability counts for each TimeUnitStartsUtc linked by same index. [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#get-services-pricing) Get services pricing ---------------------------------------------------------------------------------------------------------------------------------------------- Get pricing for the specified service for each time unit in the specified date interval. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#request-1) Request `[ApiBaseUrl]/api/distributor/v1/services/getPricing` Copy { "Client": "My Client 1.0.0", "EnterpriseId": "3edbe1b4-6739-40b7-81b3-d369d9469c48", "ServiceId": "40665467-5862-4932-a861-aa6b00e2b660", "StartUtc": "202-01-01T00:00:00Z", "EndUtc": "2022-01-31T00:00:00Z", "CategoryIds": ["4037c0ec-a59d-43f1-9d97-d6c984764e8c"], "RateIds": ["4037c0ec-a59d-43f1-9d97-d6c984764e8c"], "LanguageCode": "en-GB", "CurrencyCode": "EUR", "OccupancyData": [\ {\ "AgeCategoryId": "16e8a466-729e-4d32-a221-ade300e410a8",\ "PersonCount": 1\ },\ {\ "AgeCategoryId": "790c82c1-cbe6-4b8d-a45f-ade300e410a8",\ "PersonCount": 1\ }\ ] } Property Type Contract Description `Client` string required Identification of the client as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `EnterpriseId` string required Unique identifier of the enterprise. `ServiceId` string required Unique identifier of the [Service](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service) for which availability should be returned. `StartUtc` string required Start date of the requested interval. `EndUtc` string required End date of the requested interval. `CategoryIds` array of string optional Unique identifiers of specific room categories for which pricing should be computed. If omitted, pricing will be computed and returned for all room categories. `RateIds` array of string optional Unique identifiers of specific rates for which pricing should be computed. If omitted, pricing will be computed and returned for all rates. `LanguageCode` string optional Code of the language. [Supported language codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-language-codes) `CurrencyCode` string optional Currency code which should be used for prices in the response. [Supported currency codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-currency-codes) `OccupancyData` array of [Occupancy Data](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#occupancy-data) optional List of occupancy data. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#response-1) Response Copy { "RateGroups":[\ {\ "Id": "3ede420b-9e9e-4008-abef-abc800c82505",\ "Ordering": 0,\ "SettlementType": "Manual",\ "SettlementAction": "ChargeCreditCard",\ "SettlementTrigger": "Start",\ "SettlementValue": 1.00,\ "SettlementOffset": "P0M0DT0H0M0S",\ "SettlementMaximumNights": null,\ "SettlementMaximumTimeUnits": null,\ "SettlementCurrencyCode": null\ }\ ], "Rates":[\ {\ "Id": "f02923a9-ffa3-4d83-a9d7-abc800c81111",\ "ServiceId": "33c75941-c2ec-467e-9797-abc800c8110d",\ "RateGroupId": "3ede420b-9e9e-4008-abef-abc800c82505",\ "Ordering": 0,\ "Name": {\ "es-ES": "Fully Flexible",\ "en-US": "Fully Flexible"\ },\ "Description": {},\ "IsPrivate": false,\ "CurrencyCode": "EUR"\ }\ ], "CategoryPrices": [\ {\ "CategoryId": "4037c0ec-a59d-43f1-9d97-d6c984764e8c",\ "OccupancyPrices": [\ {\ "Occupancies": [\ {\ "AgeCategoryId": "16e8a466-729e-4d32-a221-ade300e410a8",\ "PersonCount": 1\ },\ {\ "AgeCategoryId": "790c82c1-cbe6-4b8d-a45f-ade300e410a8",\ "PersonCount": 1\ }\ ]\ }\ ],\ "RateGroupPrices":[\ {\ "MinRateId": "abd865c2-8cc3-4ebc-acad-aca100b125b9",\ "MinPrice": {\ "TotalAmount": {\ "Currency": "EUR",\ "GrossValue": 83.41,\ "NetValue": 77.65,\ "Breakdown": {\ "Items": [\ {\ "TaxRateCode": null,\ "NetValue": 18.11,\ "TaxValue": 0.0\ },\ {\ "TaxRateCode": "CZ-L",\ "NetValue": 57.50,\ "TaxValue": 5.76\ },\ {\ "TaxRateCode": "CZ-Z",\ "NetValue": 2.04,\ "TaxValue": 0.00\ }\ ]\ }\ },\ "AverageAmountPerTimeUnit": {\ "Currency": "EUR",\ "GrossValue": 41.71,\ "NetValue": 38.83,\ "Breakdown": {\ "Items": [\ {\ "TaxRateCode": null,\ "NetValue": 9.06,\ "TaxValue": 0.0\ },\ {\ "TaxRateCode": "CZ-L",\ "NetValue": 28.75,\ "TaxValue": 2.88\ },\ {\ "TaxRateCode": "CZ-Z",\ "NetValue": 1.02,\ "TaxValue": 0.00\ }\ ]\ }\ }\ },\ "MaxPrice": {\ "TotalAmount": {\ "Currency": "EUR",\ "GrossValue": 20020.15,\ "NetValue": 18201.97,\ "Breakdown": {\ "Items": [\ {\ "TaxRateCode": null,\ "NetValue": 18.11,\ "TaxValue": 0.0\ },\ {\ "TaxRateCode": "CZ-L",\ "NetValue": 18181.82,\ "TaxValue": 1818.18\ },\ {\ "TaxRateCode": "CZ-Z",\ "NetValue": 2.04,\ "TaxValue": 0.00\ }\ ]\ }\ },\ "AverageAmountPerTimeUnit": {\ "Currency": "EUR",\ "GrossValue": 10010.08,\ "NetValue": 9100.99,\ "Breakdown": {\ "Items": [\ {\ "TaxRateCode": null,\ "NetValue": 9.06,\ "TaxValue": 0.0\ },\ {\ "TaxRateCode": "CZ-L",\ "NetValue": 9090.91,\ "TaxValue": 909.09\ },\ {\ "TaxRateCode": "CZ-Z",\ "NetValue": 1.02,\ "TaxValue": 0.00\ }\ ]\ }\ }\ }\ }\ ]\ }\ ] } Property Type Contract Description `RateGroups` array of [Rate group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#rate-group) required Information about all available rate groups. `Rates` array of [Rate](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#rate) required Information about all available rates. `CategoryPrices` array of [Category price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#category-price) required Prices for all specified categories. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#category-price) Category price Property Type Contract Description `CategoryId` string required Unique identifier of category. `OccupancyPrices` array of objects with arrays of [Occupancy](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#occupancy) required List of occupancies for age categories against which rate group prices are supplied. When `OccupancyData` request parameter is not provided, the prices for the combination of the default adult and a single child category is generated for up to 3 person counts. `RateGroupPrices` array of [Rate group price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#rate-group-price) required Prices for the given category for each of the occupancy bands specified in OccupancyPrices. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#occupancy) Occupancy Property Type Contract Description `AgeCategoryId` string required Identifier of age category. `PersonCount` number required Number of persons of this Age category type. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#rate-group-price) Rate group price Property Type Contract Description `MinRateId` string required Unique identifier of rate. `MinPrice` [Min price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#min-price) objects required Minimal price for the specified interval for rate. `MaxPrice` [Max price](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#max-price) objects required Maximal price for the specified interval for rate. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#min-price) Min price Property Type Contract Description `TotalAmount` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#amount) objects required Total price for specified interval. `AverageAmountPerTimeUnit` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#amount) objects required Price for one timeUnit. (Day/Night) #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#max-price) Max price Property Type Contract Description `TotalAmount` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#amount) objects required Total price for specified interval. `AverageAmountPerTimeUnit` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#amount) objects required Price for one timeUnit. (Day/Night) #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#rate) Rate Property Type Contract Description `Id` string required Unique identifier of the rate. `Name` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Name of the rate localized into all supported languages. `Description` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Description of the rate localized into all supported languages. `IsPrivate` boolean required Set to `true` for promotion rate enabled by provided `VoucherCode`. `ServiceId` string required Unique identifier of the [Service](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service) to which the rate is bound. `RateGroupId` string required [Rate group](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#rate-group) Identifier of the rate. `Ordering` number required Number defining the ordering of the rate. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#amount) Amount Property Type Contract Description `Currency` string required ISO 4217 code of the currency. `GrossValue` number required Gross value of the amount. (Net + sum of `TaxValues`) `NetValue` number required Net value of the amount. `Breakdown.Items` array of [Complete tax](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#complete-tax) required List of taxes related to this amount. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#rate-1) Rate Property Type Contract Description `Currency` string required Amount currency. `GrossValue` number required Gross value of the amount. (Net + sum of `Breakdown > Items`) `NetValue` number required Net value of the amount. `Breakdown.Items` array of [Complete tax](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#complete-tax) required List of taxes related to this amount. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#complete-tax) Complete tax Property Type Contract Description `TaxRateCode` string Unique identifier of the tax rate. `NetValue` number required Net value taxValue is calculated from. `TaxValue` number required Tax value calculated from `NetValue` based on Tax configuration. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#response-diagram) Response diagram ![](https://mews-systems.gitbook.io/booking-engine-guide/~gitbook/image?url=https%3A%2F%2F3292240558-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FtIc30XOAP46ahd8X73va%252Fuploads%252Fgit-blob-874d88b30cc82450399172217fdbf11011174fb3%252Fget_services_pricing_v2_v2.png%3Falt%3Dmedia&width=768&dpr=4&quality=100&sign=16a8947e&sv=2) Get services pricing response [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#get-promoted-services) Get promoted services ------------------------------------------------------------------------------------------------------------------------------------------------ > #### > > [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#restricted) > > Restricted! > > This functionality is currently in beta-test and as such it is subject to change. Get promoted (upsell) services for a given service and interval with prices in given currency. Returns available promoted services, their pricing, and related resource categories. ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#request-2) Request `[ApiBaseUrl]/api/distributor/v1/services/getPromotions` Copy { "Client": "My Client 1.0.0", "EnterpriseId": "3edbe1b4-6739-40b7-81b3-d369d9469c48", "ServiceId": "40665467-5862-4932-a861-aa6b00e2b660", "StartUtc": "2022-01-01T00:00:00Z", "EndUtc": "2022-01-31T00:00:00Z", "CurrencyCode": "EUR" } Property Type Contract Description `Client` string required Identification of the client as described in [Authentication](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authentication) . `EnterpriseId` string required Unique identifier of the enterprise. `ServiceId` string required Unique identifier of the [Service](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/configuration#service) for which promoted services should be returned. `StartUtc` string required Start date of the requested interval. `EndUtc` string required End date of the requested interval. `CurrencyCode` string required Currency code for prices in the response. [Supported currency codes](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/supported-currency-codes) ### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#response-2) Response Copy { "PromotedServices": [\ {\ "PromotedServiceAssignmentId": "b1e2c3d4-5678-1234-9abc-1234567890ab",\ "PromotedServiceId": "a1b2c3d4-5678-1234-9abc-1234567890ab",\ "PromotedRateId": "c1d2e3f4-5678-1234-9abc-1234567890ab",\ "PromotedServiceTimeUnitPeriod": "Day",\ "PromotedServiceStartOffset": "P0D",\ "PromotedServiceEndOffset": "P0D",\ "PromotedServiceUnitCountLimit": "Unlimited",\ "PromotedServiceReservationIntervalLimit": "InsideParent",\ "PromotedServiceDefaultOccupancyData": [\ { "AgeCategoryId": "16e8a466-729e-4d32-a221-ade300e410a8", "PersonCount": 2 }\ ],\ "PromotedServiceOptions": { "ProRataCharging": false },\ "PromotedRateName": { "en-US": "Flexible Rate" },\ "PromotedResourceCategoryId": "ddc48d9f-f21d-422a-b24a-aa6b00e2b77e",\ "PromotedResourceCategoryName": { "en-US": "Room" },\ "PromotedResourceCategoryDescription": { "en-US": "A nice room" },\ "ImageId": "e1f2a3b4-5678-1234-9abc-1234567890ab",\ "TotalAmount": { "Currency": "EUR", "GrossValue": 100.0, "NetValue": 90.0, "Breakdown": { "Items": [] } },\ "UnitAmount": { "Currency": "EUR", "GrossValue": 50.0, "NetValue": 45.0, "Breakdown": { "Items": [] } },\ "AvailableCount": 5,\ "Ordering": 1,\ "MinPricePerTimeUnit": { "Currency": "EUR", "GrossValue": 50.0, "NetValue": 45.0, "Breakdown": { "Items": [] } }\ }\ ], "ResourceCategories": [\ {\ "CategoryId": "ddc48d9f-f21d-422a-b24a-aa6b00e2b77e",\ "Name": { "en-US": "Room" },\ "Description": { "en-US": "A nice room" }\ }\ ] } Property Type Contract Description `PromotedServices` array of [Promoted service](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#promoted-service) required List of available promoted services for the given interval. `ResourceCategories` array of [Room categories](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#room-category) required List of resource categories related to promoted services. #### [](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#promoted-service) Promoted service Property Type Contract Description `PromotedServiceAssignmentId` string required Unique identifier of the promoted service assignment. `PromotedServiceId` string required Unique identifier of the promoted service. `PromotedRateId` string required Unique identifier of the promoted rate. `PromotedServiceTimeUnitPeriod` string required Time unit period (e.g. Day, Hour) for the promoted service. `PromotedServiceStartOffset` string required Start offset for the promoted service (ISO 8601 duration). `PromotedServiceEndOffset` string required End offset for the promoted service (ISO 8601 duration). `PromotedServiceUnitCountLimit` string required Unit count limit for the promoted service. `PromotedServiceReservationIntervalLimit` string required Reservation interval limit for the promoted service. `PromotedServiceDefaultOccupancyData` array of [Occupancy data](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#occupancy-data) required Default occupancy data for the promoted service. `PromotedServiceOptions` object required Options for the promoted service (e.g. ProRataCharging). `PromotedRateName` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Name of the promoted rate. `PromotedResourceCategoryId` string required Resource category id for the promoted service. `PromotedResourceCategoryName` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Name of the resource category. `PromotedResourceCategoryDescription` [Localized text](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/hotels#localized-text) required Description of the resource category. `ImageId` string optional Image id for the resource category. `TotalAmount` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#amount) optional Total price for the promoted service. `UnitAmount` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#amount) optional Price per time unit for the promoted service. `AvailableCount` number optional Number of available promoted services. `Ordering` number required Ordering of the promoted service. `MinPricePerTimeUnit` [Amount](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/services#amount) required Minimal price per time unit for the promoted service. [PreviousReservation groups](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/reservation-groups) [NextVouchers](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/operations/vouchers) Last updated 2 months ago Was this helpful? --- # Accounting | Open API For financial accounting, take a look at the [Accounting use case](https://mews-systems.gitbook.io/connector-api/use-cases/accounting) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api) . [PreviousUse Cases](https://mews-systems.gitbook.io/open-api/use-cases) [NextBooking](https://mews-systems.gitbook.io/open-api/use-cases/booking) Last updated 3 years ago Was this helpful? --- # Customer Relationship | Open API For customer management, take a look at the [Customer management use case](https://mews-systems.gitbook.io/connector-api/use-cases/customer-management) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api) . [PreviousBooking](https://mews-systems.gitbook.io/open-api/use-cases/booking) [NextDistribution](https://mews-systems.gitbook.io/open-api/use-cases/distribution) Last updated 3 years ago Was this helpful? --- # Service Optimization | Open API Service Optimization is a general term that covers housekeeping, maintenance, work order management, HR (Human Resources) and related service optimization functions. The most common requirement is around Housekeeping, for which see the [Housekeeping use case](https://mews-systems.gitbook.io/connector-api/use-cases/housekeeping) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api) . [PreviousRevenue Management](https://mews-systems.gitbook.io/open-api/use-cases/revenue-mgmt) [NextUpsell](https://mews-systems.gitbook.io/open-api/use-cases/upsell) Last updated 3 years ago Was this helpful? ---