# Mews Open API Welcome to the **Mews Open API** developer documentation. Here you will find all the information you need to get started working with the **Mews Open API** as quickly as possible, as well as support in case you get stuck, and of course a full reference for each individual API. Let's jump in! {% hint style="success" %} #### 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). {% endhint %} ## Our APIs Not sure which option is right for you? See [The Mews APIs](/getting-started/the-mews-apis). If you need further assistance, or have any questions or special requests, please contact .

:plug:

Connector APIA general-purpose API that gives access to data and services in Mews, and supports multiple use cases./spaces/8QGgEdFlLPx3GworPLr8

:cash-register:

POS APIAn API for Point-of-Sale systems to integrate with Mews for seamless order management and data exchange./spaces/fOtD4bwkCg5dMG01D7h0

:bed-empty:

Booking EngineAn API for Booking Engines to enable your customers to create reservations directly in Mews./spaces/NQLFOBK71zKQNjl5UEnW

:chart-line:

Channel Manager APIAn API for Channel Managers and other distribution channels to fetch availability, rates and inventory data, and make reservations./spaces/BRKhVN3KmDvpkFzJQmT5
:gem:Loyalty Partner APIA reverse API for loyalty program providers to integrate their membership systems with Mews./spaces/NXX5WlJYsdpRtizxNDPz
*** {% hint style="info" %} **Changes to the documentation** To track changes and updates to this documentation, you can follow the [GitHub repository](https://github.com/MewsSystems/open-api-docs). For the individual APIs, we maintain Changelog and Deprecations pages. {% endhint %} # Getting started The **Mews Open API** is a powerful tool that enables you to easily connect your hospitality software into Mews and become part of our ecosystem of integrated solutions. Use the **Mews Open API** to fetch data, make bookings, adjust rates, post charges, upsell products, and do a myriad of other things. We take the 'open' part very seriously, which is why we make it as easy as possible to connect and why we are always trying to remove barriers to successful adoption. All the documentation is publicly hosted on [GitHub](https://github.com/MewsSystems/open-api-docs), and we provide a Demo environment for developers so you can start coding and testing straight away. ## A family of APIs The **Mews Open API** is in fact a family of APIs. Each API operates independently, serving a different function, and each has its own documentation. * See [The Mews APIs](/getting-started/the-mews-apis) ## What do you want to achieve? Take a look at [The Mews APIs](/getting-started/the-mews-apis) to see which is the API for you. The documentation for each API includes examples of common use cases for that API, or you can find an overview of all of them in [Use Cases](/use-cases/business-use-cases). ## Getting stuck in Each API includes a Guidelines section explaining how to use the API, including quick-start information for connecting to a Demo environment and getting results right away. * [Go straight to the Mews Connector API](https://mews-systems.gitbook.io/connector-api/) * [Go straight to the Mews POS API](https://docs.mews.com/pos-api/) * [Go straight to the Mews Channel Manager API](https://mews-systems.gitbook.io/channel-manager-api/) * [Go straight to the Mews Booking Engine API](https://mews-systems.gitbook.io/booking-engine-guide/) ## Help with terminology Throughout your Mews journey, you may find terms that are unfamiliar or unclear. That's why we created the [Mews Glossary for Open API users](/getting-started/glossary). The Glossary provides a full description of all the terms used across the individual Mews APIs. # The Mews APIs Mews supports the following APIs, each serving a different purpose. The documentation for each API is self-contained and consists of two parts: * A set of guidelines on how to use the API * A detailed reference for all the API operations And each API is hosted as a public GitHub repository. ## Mews Connector API This API is a general-purpose API that gives access to data and services in Mews Operations. The API supports many use cases, including Kiosk, Point Of Sale, Reservations Data, Upselling and Events Management, to name just a few. We encourage you to explore the API and innovate new solutions for our customers! {% content-ref url="/spaces/8QGgEdFlLPx3GworPLr8" %} [Connector API](https://docs.mews.com/connector-api/) {% endcontent-ref %} ## Mews POS API A general-purpose API that gives real-time access to data and services in Mews POS (Point-of-sale). Supports use cases such as business intelligence, inventory management, table bookings, etc. {% content-ref url="/spaces/fOtD4bwkCg5dMG01D7h0" %} [POS API](https://docs.mews.com/pos-api/) {% endcontent-ref %} ## Mews Channel Manager API This API is for Channel Managers and other distribution channels to fetch availability, rates and inventory data, and make reservations. {% content-ref url="/spaces/BRKhVN3KmDvpkFzJQmT5" %} [Channel Manager API](https://docs.mews.com/channel-manager-api/) {% endcontent-ref %} ## Mews Booking Engine API This API is for booking engines to enable guests to create reservations directly in Mews. Please note that for custom booking engine solutions, connected properties will need a Mews Enterprise subscription. {% content-ref url="/spaces/NQLFOBK71zKQNjl5UEnW" %} [Booking Engine](https://docs.mews.com/booking-engine-guide/) {% endcontent-ref %} {% hint style="warning" %} **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://docs.mews.com/connector-api/). {% endhint %} ## Which API to use? If you are a Channel Manager, or a bulk sales or distribution channel such as an Online Travel Agent, then you will want the [Mews Channel Manager API](https://mews-systems.gitbook.io/channel-manager-api/). If you are implementing a Booking Engine for your customers to book with you directly, you will want the [Mews Booking Engine API](https://mews-systems.gitbook.io/booking-engine-guide/). If you are integrating a Point-of-Sale system with Mews, you will want the [Mews POS API](https://docs.mews.com/pos-api/). For all other use cases, use the [Mews Connector API](https://mews-systems.gitbook.io/connector-api/). Please also take a look at [Use Cases](/use-cases/business-use-cases), where you can find more information on individual use cases and links to more details in the documentation for the appropriate API. # Mews Marketplace The [Mews Marketplace](https://www.mews.com/en/products/marketplace) is where customers of Mews can find certified integration partners to help them improve operations, generate more revenue and enhance the guest experience. If you are a Mews partner, the Marketplace is the place to be! > **Private integrations** > > Private integrations are where you make a private connection to a single enterprise or single property; in this case you would not be listed in the Marketplace. # Your journey with Mews {% hint style="success" %} #### 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). {% endhint %} 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](#step-1-exploration) * [Step 2: Let us know what you plan to do](#step-2-qualification) * [Step 3: Develop and test your solution](#step-3-development) * [Step 4: Get certified](#step-4-certification) * [Step 5: Go live with a pilot](#step-5-pilot) * [Step 6: Join the Marketplace!](#step-6-publication) If you have questions about the process, drop us a line to . {% hint style="info" %} #### 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](/getting-started/your-journey/booking-engine-integrations). {% endhint %} {% stepper %} {% step %} #### Exploration First find out [which of our APIs you should be using](/getting-started/the-mews-apis). If you're not sure, take a look at the [use cases](/use-cases/business-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. {% endstep %} {% step %} #### 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? {% endstep %} {% step %} #### 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). {% endstep %} {% step %} #### 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) {% endstep %} {% step %} #### 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. {% hint style="warning" %} #### Tokens are sensitive 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. {% endhint %} * **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](#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. {% endstep %} {% step %} #### Publication If your integration is intended to be listed publicly in the Mews Marketplace, then after an agreed period (see below) 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). {% hint style="info" %} 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. {% endhint %} {% endstep %} {% endstepper %} # Booking Engine integrations The steps for a Booking Engine API integration are as follows: {% stepper %} {% step %} ### Exploration Explore the [Booking Engine Guide](https://mews-systems.gitbook.io/booking-engine-guide/) and familiarize yourself with the API guidelines and operations. Not sure if the API is the right option? See [Booking Engine Guide ways to integrate](https://mews-systems.gitbook.io/booking-engine-guide/faq/ways-to-integrate). {% hint style="info" %} Please note that connection to the Booking Engine API is only available to Mews customers with Enterprise packages. {% endhint %} {% endstep %} {% step %} ### Registration Once you're sure you want to develop against the API, please register your client name and other details with Mews, as described in [Booking Engine API authorization](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authorization). To do so, send an email to like the following example. In the meantime, you can start working with the API straight away using the sample client name, as described in [Booking Engine API authorization](https://mews-systems.gitbook.io/booking-engine-guide/booking-engine-api/guidelines/authorization). > **Registration email** > > *Dear Mews support,* > > *We would like to register the following client for Booking Engine access:* > > * *Client name:* \ > * *Contact email:* \ > * *Environments:* \ > {% endstep %} {% step %} ### Development You can connect to our Demo environment to try out API operations, using your registered client name. Until your client name is registered, you can use the sample client name. All of the information you need to start developing and testing is in the [Booking Engine Guide](https://mews-systems.gitbook.io/booking-engine-guide/). {% endstep %} {% step %} ### Production Finally, when your development & testing is complete, you can switch over to the Production environment and you're all done, no certification needed! Note we support separate client name lists for the two environments, so make sure you are registered for the Production environment. {% endstep %} {% endstepper %} If you have questions about the process, drop us a line to . # Mews Glossary for Open API users This glossary lists the terms used within the **Mews Open API** and explains their meaning. The terms are presented in alphabetical order. ## Access Token An Access Token is a unique security token for a given [Property](#Property) integration, which you need in order to access that property's data through the [Mews Connector API](#ConnectorAPI). The token encodes the permissions granted to that [Integration](#Integration). Integration partners are sent the Access Token by Mews when authorized by the property, alternatively the property can obtain the Access Token directly through Mews Operations, see [Find an integration access token](https://help.mews.com/s/article/find-an-integration-s-access-token?language=en_US). Note that in cases where there is more than one instance of the same [Integration](#Integration) in one [Property](#Property), each instance has a separate Access Token. In the Connector API, most API endpoints require Access Token, [Client Token](#ClientToken) and [Client](#Client) fields to be included in the request data in order to authenticate the [Client](#Client) and to authorize access to the requested data and services. In the Channel Manager API, on the Mews side, most API endpoints instead require [Connection Token](#ConnectionToken) and [Client Token](#ClientToken) to perform a similar role. Access Tokens normally allow access to a single [Property](#Property) or [Enterprise](#Enterprise), however some tokens may be [Portfolio Access Tokens](#PortfolioAccessToken), which allow access to all the properties within a [Portfolio](#Portfolio). ## Accommodation Accommodation is synonymous with '[Stay](#Stay)' and refers to room-stay based services offered by a Property. These are the main services that properties offer to their customers, in fact a default [Stay](#Stay) service is created automatically by Mews and cannot be deleted. Accommodation services are [Bookable Services](#BookableService), i.e. they can be reserved or booked prior to a [Customer](#Customer)'s arrival. ## Account Depending on context, Account could refer to a property account, user account or a financial account. However, the most common meaning of Account is a [Customer](#Customer) or [Company](#Company). * The normal meaning of Account is a [Customer](#Customer) or [Company](#Company), i.e. it is a general term that covers both, and for which there is a single unique identifier or GUID. * A property account is a record containing the details of a [Property](#Property), e.g. its name and address, see [Set up your property account](https://help.mews.com/s/article/set-up-your-property-account?language=en_US). * A user account is a record containing the details of a [Property](#Property) [Employee](#Employee) and their access permissions, see [Setting up your account](https://help.mews.com/s/article/setting-up-your-account?language=en_US). * A financial account is a record of financial transactions, e.g. a [Paymaster](#Paymaster) account or guest [Bill](#Bill). ## Accounting Category Accounting Categories are used to categorize [Accounting Items](#AccountingItem) (both [Orders](#Order) and [Payments](#Payment)) and they are configured differently for each [Property](#Property). All [Accounting Items](#AccountingItem) belong to an Accounting Category. Each Accounting Category has a name, a classification, and associated codes used for accounting purposes. Accounting Category is specified for a [Service](#Service) in the service settings, so when an [Order](#Order) is made against a [Service](#Service) then it uses that Accounting Category. ## Additional Services Additional Services are [Services](#Service) that cannot be purchased when a [Reservation](#Reservation) is made, unlike [Bookable Services](#BookableService). They are additional or extra to the main service, and can be purchased on-site and added to a guest's [Bill](#Bill). Examples include room service, airport transfer and spa services. ## Accounting Item All [Order](#Order) items and [Payment](#Payment) items are types of Accounting Item. [Order](#Order) items are consumed items, [Payment](#Payment) items are payments or invoices. ## ADR ADR stands for Average Daily Rate, a standard hospitality industry metric expressing the average revenue earned per occupied [Space](#Space) per day. Hotels use ADR as a measure of pricing performance — for example, when offering an [Allowance](#Allowance) instead of discounting the room [Rate](#Rate), the hotel can protect its ADR while still providing added value to the guest. ## Allowance An Allowance is a packaged spending benefit that a [Property](#Property) attaches to a [Rate](#Rate), giving guests a pre-defined amount they can redeem against specified on-property services — for example, food & beverage, spa, or minibar charges. Rather than discounting the room [Rate](#Rate), the [Property](#Property) adds value while protecting its [ADR](#ADR). ## ARI ARI is a general hospitality industry term and stands for [Availability](#Availability), [Rates](#Rate) and [Inventory](#Inventory). ## Availability Availability is the quantity of [Spaces](#Space) of specified [Space Categories](#SpaceCategory) (or quantity of [Resources](#Resource) of specified [Resource Categories](#ResourceCategory) ) that are open for sale during a specified time period. ## Availability Block Availability Block is synonymous with Group Block, it implies a block of [Inventory](#Inventory) set aside for group sales, e.g. a block of guest rooms set aside for a wedding, or a block of rooms set aside for a tour operator. Normally these are a group of similar [Spaces](#Space) belonging to the same [Space Category](#SpaceCategory) and subject to the same [Rate](#Rate). Availability Blocks are different than [Resource Blocks](#ResourceBlock), which are groups of [Spaces](#Space) taken out of Inventory because they are out-of-service or being used for other purposes. ## Bill A Bill is a financial account for a [Customer](#Customer) or [Company](#Company), synonymous with 'folio'. It can contain a mix of [Order](#Order) items and [Payment](#Payment) items. A Bill can be 'open', i.e. you can modify it, or 'closed', i.e. closed to further changes. A closed Bill is assumed to be balanced, i.e. sums to zero, and 'settled' by the [Customer](#Customer) or [Company](#Company). Note that a [Customer](#Customer) Bill is linked to the [Customer](#Customer) [Profile](#Profile), not to the [Reservation](#Reservation). However, using the API you can still identify the [Reservations](#Reservation), Bills and [Services](#Service) that an [Accounting Item](#AccountingItem) is linked to. For more information, search "Bill" in [Mews Help](https://help.mews.com/s/?language=en_US). ## Bookable Service Bookable Services are the main [Services](#Service) in a [Property](#Property) that your guests can book or reserve, such as the default [Stay](#Stay) [Service](#Service). They are displayed on the system timeline and don't depend on any other [Service](#Service) for their purchase, as opposed to [Additional Services](#AdditionalServices). See [Set up a bookable service](https://help.mews.com/s/article/set-up-a-bookable-service?language=en_US). ## Booker A Booker is a [Customer](#Customer) who makes a [Reservation](#Reservation) for another Customer. They are not the main Customer linked to the Reservation, who is referred to as the Reservation [Owner](#Owner). ## Booking This term is synonymous with [Reservation](#Reservation). ## Booking Engine Booking Engine implies the part of a booking website or app through which users can make bookings in customer properties. The **Mews Booking Engine** is part of the Mews product portfolio. ## Booking Engine API The **Mews Booking Engine API** is one of the main APIs within the [Mews Open API](#OpenAPI-MewsOpenAPI). It can be used by custom Booking Engines to enable users to check availability and make reservations directly in Mews. ## Breakage Breakage is the unspent [Allowance](#Allowance) that is retained by the [Property](#Property) as revenue when the allowance expires or the guest checks out. It represents the portion of the allowance that the guest did not consume during their stay. ## Business Segment Business Segments, Channel Manager Segments, or just Segments, are used to classify [Reservations](#Reservation) by attributes relevant to a [Property](#Property)'s operations, such as traveler type or whether the [Reservation](#Reservation) is group or individual. They allow the [Property](#Property) to gather information from reports to identify trends and to target customers more effectively. See [Create, modify or delete a segment](https://help.mews.com/s/article/create-modify-or-delete-a-segment?language=en_US\&Language=en_US). ## Cashier A Cashier is a role for handling payments. Multiple cashiers can be configured for a [Property](#Property), and [Employees](#Employee) allocated against them. Each cashier has a specified currency that they work in. See [Create or delete a cashier](https://help.mews.com/s/article/create-or-delete-a-cashier?language=en_US). ## Chain A Chain is a group of multiple [Properties](#Property) or [Enterprises](#Enterprise) under the same management. In the context of the Mews system, Chains are used to define legal relationships between [Enterprises](#Enterprise), and for sharing certain data which is common across the Chain. Note that Chains are separate to [Portfolios](#Portfolio) used for [Multi-property](#Multi-property) working as part of **Mews Multi-Property**. ## Channel Channel is shorthand for the sales channel through which [Bookings](#Booking) are made, e.g. direct from the [Property](#Property) website, from a Central Reservation System (CRS), from a Global Distribution System (GDS) or from an Online Travel Agent (OTA). ## Channel Manager A Channel Manager is a hub for managing the various sales [Channels](#Channel) that a [Property](#Property) may be connected to. Typically a [Property](#Property) would connect its Mews Property Management System (Mews Operations) to a Channel Manager and the Channel Manager would in turn connect to the various Channels. SiteMinder is a well-known example of a Channel Manager. Mews Operations passes ARI data ([Availability](#Availability), [Rates](#Rate) and [Inventory](#Inventory)) to the Channel Manager, which distributes them to the connected [Channels](#Channel), and Mews Operations receives [Reservations](#Reservation) from the Channel Manager. The part of the [Mews Open API](#OpenAPI-MewsOpenAPI) that supports this two-way functionality is called the [Channel Manager API](#ChannelManagerAPI). Typically, this is connected via an [Integration](#Integration) to a Channel Manager, however the same API may also be used to connect other sales channels. From the API's point of view, they all have the same functionality, sending outgoing updates of ARI data ([Availability](#Availability), [Rates](#Rate) and [Inventory](#Inventory)) and receiving incoming [Reservations](#Reservation). ## Channel Manager API The **Mews Channel Manager API** is one of the main APIs within the [Mews Open API](#OpenAPI-MewsOpenAPI). It is used by Channel Managers and other distribution channels to fetch availability, rates and inventory, and make reservations. ## Channel Manager ID This is another name for the [Connection Token](#ConnectionToken) used in the Channel Manager API, because each [Connection Token](#ConnectionToken) identifies a unique [Channel Manager](#ChannelManager) [Connection](#Connection) (or any other client application connection). ## Channel Manager Segment See [Business Segment](#BusinessSegment). ## Charge Rule Charge Rule is the particular method of calculation that the system uses for deriving a [Product](#Product) charge or price, e.g. 'per person per night' implies that the charge is the individual nightly rate multiplied by the number of people and the the number of nights. ## Check-in Check-in is the process of registering a [Customer](#Customer)'s arrival at a [Property](#Property) at the beginning of their stay, although this may be performed in advance of their physical arrival on site, using an online check-in process. The [Mews Open API](#OpenAPI-MewsOpenAPI) may describe this process as 'start reservation', implying the start of the reserved period of stay. ## Check-out Check-out is the process of registering a [Customer](#Customer)'s departure from a [Property](#Property) at the end of their [Stay](#Stay). The [Mews Open API](#OpenAPI-MewsOpenAPI) may describe this process as 'process reservation', implying that the the [Bill](#Bill) has been settled and therefore it can be processed and closed. ## Client The meaning of Client depends on context, but it generally refers to the client application or partner application which is accessing the API and consuming API data and services - thus it is a client of the API. For example, the [Client Token](#ClientToken) is the security token used to uniquely identify the client application. ## Client Token A Client Token is a security token you use to authenticate your application when accessing the API. As such, you should keep this token secure and never share it. You will be provided with the Client Token by Mews during the partner on-boarding process. Client Tokens are used across the Mews APIs, however there may be differences in detail between individual APIs so please consult the API documentation for the particular API you are using. In the Connector API, most API endpoints require [Access Token](#AccessToken), Client Token and [Client](#Client) fields in the request data in order to authenticate the [Client](#Client) and to authorize access to the requested data and services. In the Channel Manager API, on the Mews side, most API endpoints similarly require [Connection Token](#ConnectionToken) and Client Token. In the Channel Manager API, on the Channel Manager side, a Client Token is still required, but in this case the client application is the Mews application. Note that you need a different Client Token to connect to different Mews environments, i.e. one token for the Production environment and a separate token for the Demo environment. ## Command A Command is a command or instruction that the system sends to a physical [Device](#Device) such as an on-premise printer or on-premise key cutter. ## Companion A Companion is a [Customer](#Customer) or [Guest](#Guest) linked to a [Reservation](#Reservation) who is not the primary Customer or [Owner](#Owner), but an additional Guest. ## Company Company is a corporate entity linked to a booking or [Reservation](#Reservation), for example in the case of a corporate travel booking. Company records which store details about each company are called Company [Profiles](#Profile). Companies can be automatically to incoming [Reservations](#Reservation) using [Channel Manager](#ChannelManager) [Mapping Tables](#MappingTable). [Travel Agencies](#TravelAgency) are a special type of Company and within the API they may be considered as separate entities. ## Complimentary Product Item A Complimentary Product Item is a zero cost [Product Item.](#ProductItem) The system considers these as 'inactive' and therefore they do not appear in the Accounting Report nor on the [Customer](#Customer) Account under **Customer profile > Billing**. If it is a [Stay Product](#StayProduct), then it appears against **Reservation module > Items**. If it is a [Service Product](#ServiceProduct), it appears against **Customer profile > Dashboard > Orders**. ## Connection A Connection represents a single interface instance between a given [Channel Manager](#ChannelManager) or other client application and the Channel Manager API (Mews side). The concept of a Connection is unique to the Channel Manager API. Each Connection has an associated [Connection Token](#ConnectionToken), which you need to access API data and services via that connection. ## Connection Token A Connection Token is a unique security token for a given [Connection](#Connection) that a [Channel Manager](#ChannelManager) or other client application makes to the Mews side of the Channel Manager API. You need this in order to access a [Property](#Property)'s data through the API. A single client application can make one or more [Connections](#Connection), with each one having a unique Connection Token. As an integration partner, you are sent the Connection Token by Mews when authorized by the [Property](#Property), alternatively the [Property](#Property) can obtain the Connection Token through Mews Operations, see for example the [Channel manager onboarding guide](https://help.mews.com/s/article/channel-manager-onboarding-guide?language=en_US) and [How to switch from one channel manager to another](https://help.mews.com/s/article/how-to-switch-from-one-channel-manager-to-another?language=en_US). You only use the Connection Token when working with the Mews Channel Manager API, the [Access Token](#AccessToken) serves a similar function when working with the Connector API. If your application supports the [getProperties](https://mews-systems.gitbook.io/channel-manager-api/mews-api#get-properties) API operation, this can be used to recover the Connection Tokens for all [Connections](#Connection) the [Property](#Property) supports for this [Client](#Client) application. In this case, an [Employee](#Employee) email address is used as an authorization token. ## Connector API The **Mews Connector API** is one of the main APIs within the [Mews Open API](#OpenAPI-MewsOpenAPI). This should not be confused with Mews Connector, which is a separate system with a similar name. The Connector API is a general-purpose API that gives access to data and services in **Mews Operations** and supports numerous use cases. ## Counter A Counter is a literal numerical count of something useful such as the number of [Bills](#Bill) closed, maintained in real time. ## Customer The normal meaning of Customer within the [Mews Open API](#OpenAPI-MewsOpenAPI) is the end-customer or consumer of the services that the hospitality [Enterprise](#Enterprise) provides, typically a hotel [Guest](#Guest). If you substitute the word 'guest', you won't go far wrong. The details about a Customer are stored in their [Profile](#Profile). Note that Customer Profiles can exist independently of a [Reservation](#Reservation). ## Department Department is an administrative or functional division of a [Property](#Property), e.g. Housekeeping or Front of House. An [Employee](#Employee) may be assigned to a Department, and [Tasks](#Task) may be assigned to [Employees](#Employee) or Departments. ## Deposit A Deposit is a sum payed as a first instalment, e.g. against a [Reservation](#Reservation), with the intention to pay the balance at a later date, e.g. on [Check-out](#CheckOut). ## Device The term Device refers to a physical hardware device or system that Mews connects to, such as an on-premise printer or an on-premise key cutter / key encoder. ## Distributor Distributor is the old name for the Mews Booking Engine. As such, there may be references to Distributor in the Booking Engine Guide, especially in URLs, function names and the like. For Distributor, read Mews Booking Engine. ## Editable History Interval Editable History Interval (EHI) is the shorter of the two Editable History Windows (EHW) used in Mews Operations. For a full explanation of these terms and how to interpret them, see [Editable History Window](#EditableHistoryWindow). ## Editable History Window Editable History Window (EHW) refers to the historical time window within which amendments are permitted to certain data before they are considered fully closed to editing. It is expressed as a period of time, e.g. 2 days, this means that once the data is 2 days old it can no longer be changed and is considered a frozen historical record. There are in fact two EHWs and they are separate configuration parameters in Mews Operations: one is the **Operational EHW** (concerned with [Reservations](#Reservation)) and the other is the **Accounting EHW** (concerned with accounting data). For example, changes are permitted to [Bills](#Bill) and invoices after they are closed, for a period of time equal to the Accounting Editable History Window. After that time has elapsed, [Bills](#Bill) and invoices can no longer be edited. The same applies to historical [Reservations](#Reservation) data, these cannot be edited after the Operational Editable History Window time period has elapsed. If you try to post an [Accounting Item](#AccountingItem) or [Outlet](#Outlet) item with a 'consumption time' that falls outside of the permitted editable time period, you will not be permitted to do so and will receive an appropriate error response. In the Mews Connector API, the *Get Configuration* operation returns **Editable History Interval**, which is the shorter of the two Editable History Windows. Any operation that you perform through the API on historical data will therefore be valid if it lies within this interval period, regardless of whether it is related to accounting data or reservation data. For more information: * [Set up your Editable History Windows](https://help.mews.com/s/article/set-up-your-editable-history-windows?language=en_US) * [How to extend the Operational & Accounting editable history window](https://help.mews.com/s/article/how-to-extend-the-operational-accounting-editable-history-window?language=en_US) * [The accounting configuration in Mews - an overview of the settings](https://help.mews.com/s/article/what-is-the-accounting-configuration?language=en_US) ## Employee A member of staff at a [Property](#Property) or [Enterprise](#Enterprise). They may also be referred to as a [User](#User) of the Mews system, depending on context. ## Enterprise The term Enterprise implies a single Mews customer, either an individual [Property](#Property) such as a hotel or hostel, or some other type of Mews customer which consists of multiple physical properties, such as a campus. ## Extra Additional [Products](#Product) bundled with a [Reservation](#Reservation) may be described as Extras. ## Group The term Group will rarely be used on its own except in a specific context, since the term Group could refer to a group of [Properties](#Property) (normally a [Chain](#Chain) or [Enterprise](#Enterprise)), a [Reservation Group](#ReservationGroup), a [Group Block](#GroupBlock), or a [Rate Group](#RateGroup). ## Group Block See [Availability Blocks](#AvailabilityBlock). ## Guest See [Customer](#Customer). The term Guest is used in some parts of the [Mews Open API](#OpenAPI-MewsOpenAPI), but it should be read as the more general term [Customer](#Customer). ## Hotel See [Property](#Property). The term Hotel is used in some parts of the [Mews Open API](#OpenAPI-MewsOpenAPI), but it should be read as the more general term [Property](#Property). ## Integration When a [Property](#Property) or [Enterprise](#Enterprise) in Mews makes a connection with a partner system, this connection is called an Integration. A [Property](#Property) or [Enterprise](#Enterprise) can have more than one instance of an Integration with a given partner system, but normally it would only have one. ## Inventory The number of [Spaces](#Space) (e.g. guest rooms) available for sale, distributed across sales [Channels](#Channel). ## Item Item could be a [Product Item](#ProductItem), [Order](#Order) Item, [Payment](#Payment) Item or [Accounting Item](#AccountingItem). ## Length of Stay The period of a [Customer](#Customer)'s stay-over, expressed usually in number of nights. ## Mapping Table Mapping Tables are used to map relationships between [Space Categories](#SpaceCategory), [Rates](#Rate), [Products](#Product) and [Companies](#Company), using abbreviated codes for the respective entities. For example, in the Channel Manager API, 'product mappings' map [Rate Plan](#RatePlan) codes such as "NR" to [Product](#Product) codes such as "AUR". ## Marketplace Marketplace is the app store for Mews integration partners that Mews customers are able to see within their Mews account and from where they can purchase compatible products and services. Learn [how to connect and disconnect integrations available in the Mews Marketplace](https://help.mews.com/s/article/connect-and-disconnect-integrations?language=en_US\&Language=en_US). ## Message The meaning of the term Message may depend on context, but generally it refers to customer messages (i.e. guest messages) within **Mews Operations**. The Mews [Connector API](#ConnectorAPI) permits API clients to integrate with the Mews customer messaging system and thus send and receive such messages. ## Message Thread Message threads are conversations initiated by a customer (i.e. a guest), within the customer messaging system of **Mews Operations**. A message thread consists of one or more [Messages](#Message). ## Multi-property **Mews Multi-Property** is an optional module of **Mews Operations** that supports above-property level functionality, such as central management of users, rates and vouchers, across a [Portfolio](#Portfolio) of multiple [Properties](#Property). This functionality is reflected in the [Mews Connector API](#ConnectorAPI) through the use of [Portfolio Access Tokens](#PortfolioAccessToken). ## Open API The **Mews Open API** refers to the family of APIs provided by Mews to partners and customers for them to connect and access data and services in Mews. Currently it consists of three separate APIs: Mews Connector API, Mews Channel Manager API, and Mews Booking Engine API. The Mews Open API should not be confused with the term OpenAPI (without the space). ## OpenAPI OpenAPI is a public standard for defining Web APIs. OpenAPI definitions may be available for some or all of the Mews Open API - see the current API documentation for details. The OpenAPI specification was formerly known as Swagger and may still be referred to by that name. ## Order [Accounting Items](#AccountingItem) are split into [Order](#Order) items (consumed items, such as night stays or products) and [Payment](#Payment) items (such as cash, credit card payments or invoices). Thus an Order is a consumed [Service](#Service) or [Product](#Product) item. ## Outlet An Outlet is a retail outlet or retail location in a [Property](#Property), such as a bar, restaurant or spa centre. Outlets are used to record revenue and payments that occur external to the Mews system. While consumed items that are to be settled later by a guest or corporate account are posted to their respective [Customer](#Customer) [Profiles](#Profile) in Mews, items that have been consumed AND paid for should be posted to Outlets. You can read more about [how properties use Outlets](https://help.mews.com/s/article/set-up-outlets?language=en_US) and how the figures appear on the [Mews Accounting Report](https://help.mews.com/s/article/accounting-report?language=en_US). ## Owner The Owner of a [Reservation](#Reservation) is the primary [Customer](#Customer) linked to the Reservation, i.e. the primary [Guest](#Guest). Additional Guests are known as [Companions](#Companion). ## Package Package implies a bundle of [Services](#Service) and service-related [Products](#Product), e.g. if a room-stay is booked together with a spa treatment, or a room-stay with breakfast. Product rules can be used to create packages where [Products](#Product) are automatically added to a [Reservation](#Reservation) when it is made. See [Package products with accommodation](https://help.mews.com/s/article/package-products-with-accommodation?language=en_US). ## Paymaster A Paymaster account is a type of financial account used to compile charges into a single [Bill](#Bill) and issue a single invoice. This could be used for issuing a [Bill](#Bill) to a non-resident customer who doesn't have a [Profile](#Profile) on the system (also known as a **Lobby Bar Paymaster**), or to a [Travel Agent](#TravelAgency) or other [Company](#Company) which wants to receive a regular invoice for all their bookings with multiple [Customers](#Customer) (also known as a **City Ledger Paymaster**). ## Payment [Accounting Items](#AccountingItem) are split into [Order](#Order) items (consumed items, such as night stays or products) and Payment items (such as cash, credit card payments or invoices). Thus a Payment is a financial payment on an account. ## Payment Card A Payment Card is a payment device in the form of a physical card or its electronic equivalent issued by a financial institution and which enables its owner to authorize payments from the owner's financial account. A Payment Card is associated with a [Customer](#Customer) or [Company](#Company). Multiple Payment Cards can be linked to a [Profile](#Profile), see [Adding a new payment card](https://help.mews.com/s/article/add-a-new-payment-card?language=en_US). ## Portfolio A Portfolio is a collection of [Properties](#Property) or [Enterprises](#Enterprise) that form part of a single group, for the purposes of centralised management of that group when using **Mews Multi-Property**. See also [Multi-property](#Multi-property). ## Portfolio Access Token Portfolio Access Tokens are special types of [Access Token](#AccessToken) that grant access to all [Properties](#Property) or [Enterprises](#Enterprise) within a [Portfolio](#Portfolio), rather than just a single [Property](#Property) or [Enterprise](#Enterprise). These are used to facilitate [Multi-property](#Multi-property) functionality through the **Mews Open API**. API operations that support Portfolio Access Tokens may work across all [Enterprises](#Enterprise) within scope of the token, or you may specify which individual [Enterprise](#Enterprise) from within the [Portfolio](#Portfolio) you wish the operation to work with. ## Preauthorization Preauthorization or pre-authorization (often abbreviated 'pre-auth') is a [Payment Card](#PaymentCard) provider service which puts a time-limited hold on an amount authorized by the card owner, reducing the available funds, until the transaction is 'cleared' or 'settled' or cancelled. You might use this for instance when a [Reservation](#Reservation) is made to ensure that the account holder has sufficient funds to settle the [Bill](#Bill), as the service fails if insufficient funds are available. A Preauthorization does not take the funds immediately but puts a temporary hold on them. The length of time for the hold can vary. ## Price Price is the amount of money expected in exchange for goods and services, its use depends on context but usually in the [Mews Open API](#OpenAPI-MewsOpenAPI) it refers to the price of a [Reservation](#Reservation). The system calculates this from the nightly rate and the number of nights of the [Stay](#Stay). ## Product A Product is a purchasable item linked to a [Service](#Service). Although all Products are associated with [Services](#Service), those linked to [Stay](#Stay) [Services](#Service) are sometimes called [Stay Products](#StayProduct) (or Reservation Products) and those linked to other [Services](#Service) are sometimes called [Service Products](#ServiceProduct). Products can be items that can be purchased in their own right, or they can be 'relative products', meaning that they are defined relative to another product, e.g. a discounted version of the original product is a relative product which can have a price expressed as a percentage. Additional Products bundled with a [Reservation](#Reservation) may also be described as [Extras](#Extra). ## Product Item Product Item is an instance of a [Product](#Product) added to a [Customer](#Customer)'s [Bill](#Bill). ## Product Rule Product Rules are the rules that Mews uses for automatically creating [Packages](#Package), i.e. they are a set of rules that automatically add or remove [Products](#Product) from a [Reservation](#Reservation) when it is made. See [Packages](#Package). You configure Product Rules as part of setting up [Rates](#Rate). ## Product Service Order Product Service Order is the name given to an [Order](#Order) made against an [Additional Service](#AdditionalServices) (e.g. breakfast or minibar), as opposed to a [Reservation](#Reservation). Some care is needed here, as this is strictly an Additional Service Order and not to be confused with [Products](#Product). ## Profile In its general sense, a Profile is a 'record of details' about some entity, such as a [Customer](#Customer), stored on the system as a data record. Typically, the term Profile implies the encapsulated details about a [Customer](#Customer) (a Customer Profile or Guest Profile) or a [Company](#Customer) (a Company Profile). In some cases, the term may refer to the encapsulated details about a [User](#User) on the Mews system (a User Profile). Sometimes the term is used explicitly, but sometimes the term [Customer](#Customer), [Company](#Customer) or [User](#User), when used on their own, implies a Profile. ## Property Property is a general hospitality industry term to refer to a single hotel, hostel, resort, apartment building, cruise ship or other similar entity providing lodgings and hospitality. Thus a Property is an individual hospitality business that is a user and customer of Mews. ## Rate Rate is the term used to describe the price per night for a [Stay](#Stay) . It depends on a number of factors, including the type of [Space](#Space) and the date. Sometimes a Rate is a relative rate based on a 'base rate'. ## Rate Group A Rate Group is a grouping of [Rates](#Rate) that all share the same cancellation policies. For example, all 'flexible rates' would be one Rate Group, all 'non-refundable rates' would be another Rate Group, and all 'corporate rates' would be another Rate Group. ## Rate Plan Rate Plan is synonymous with [Rate](#Rate). ## Reservation Reservation has the normal hospitality meaning, i.e. a contract between a [Property](#Property) and a named [Customer](#Customer) or agent to set aside a category of [Space](#Space) and/or provide some hospitality [Service](#Service) for a specified period of time, such as a guest bedroom for a specific date and duration (in this case a [Stay](#Stay) Reservation). The contract would also contain a [Price](#Price) and terms and conditions such as a cancellation policy. ## Reservation Group A Reservation Group is a collection of associated [Reservations](#Reservation). They are collected together and given a group name for easy reference. A group would include all [Reservations](#Reservation) for a wedding party or corporate event, for example. ## Resource A Resource is something that can be sold, reserved or used. This could be an object or even the services of a person, but normally in our context it refers to a physical accommodation-based resource such as a hotel room, for which we use the general term [Space](#Space). In simple terms, a hotel room is a type of [Space](#Space), and a [Space](#Space) is a type of Resource. The [Mews SpaceTime project](https://developers.mews.com/project-spacetime/) has broadened the scope of reservable entities from [Rooms](#Room) to [Spaces](#Space) to Resources, and this remains an on-going project. As a result, within the [Mews Open API](#OpenAPI-MewsOpenAPI) you may see references to Resources and corresponding [Resource Categories](#ResourceCategory), but you may also see references to [Spaces](#Space) and corresponding [Space Categories](#SpaceCategory). In most cases you will probably find that they correspond to the same thing, i.e. hotel rooms. ## Resource Access Token A Resource Access Token is a general term for a time-limited security token granting access to a specified resource. In practise within Mews this means a PIN code (Personal Identification Number) or RFID tag (Radio Frequency ID) which may be in the form of a physical card, tag, wristband or digital equivalent used to access services, doors or similar within a [Property](#Property). Note a Resource Access Token is completely separate from and unrelated to the [Access Token](#AccessToken) used by [Client](#Client) applications to access the [Mews Open API](#OpenAPI-MewsOpenAPI); and the word 'resource' is used in the broadest sense and does not necessarily imply a [Space](#Space). ## Resource Block Resource Blocks are groups of [Resources](#Resource) or [Spaces](#Space) that you take out of [Inventory](#Inventory) because they are temporarily out-of-service or being used for other purposes. Do not confuse Resource Blocks with [Availability Blocks](#AvailabilityBlock), which are groups of [Spaces](#Space) taken out of [Inventory](#Inventory) because they are set aside for group sales. ## Resource Category This is the category to which a [Resource](#Resource) belongs, analogous to [Space Category](#SpaceCategory) but at a higher level of abstraction. For the difference between these concepts, see [Resource](#Resource) and [Space](#Space). ## Restriction Restrictions are specified limitations on [Space](#Space) [Availability](#Availability), for example the restriction that a [Space Category](#SpaceCategory) is only available if booked for a minimum [Length of Stay](#LengthOfStay) (LOS) or the restriction that a [Space Category](#SpaceCategory) is 'closed to arrival'. ## Room The term Room implies a hotel room or a function room, however the term is rarely used within the [Mews Open API](#OpenAPI-MewsOpenAPI), instead the more general term [Space](#Space) is used, or in some cases the even more general term [Resource](#Resource). A room such as a guest bedroom or suite is a type of [Space](#Space), but a [Space](#Space) may also be a car parking bay or a function room. ## Rule The meaning of Rule depends on context, but may be a [Product Rule](#ProductRule) or a [Charge Rule](#ChargeRule). ## Segment See [Business Segment](#BusinessSegment). ## Service A Service is any type of saleable hospitality service provided by a [Property](#Property), including an accommodation service or room-stay. The definition is quite broad, and could include a taxi service, room service or minibar service. All items that can be consumed by a [Customer](#Customer) are made against a Service. These can be [Bookable Services](#BookableService) or [Additional Services](#AdditionalServices). [Bookable Services](#BookableService) are ones that can be purchased when a [Reservation](#Reservation) is made. [Additional Services](#AdditionalServices) cannot be purchased when a [Reservation](#Reservation) is made, but can be purchased on-site and manually added to a [Customer](#Customer) [Bill](#Bill). The default [Bookable Service](#BookableService) is the [Stay](#Stay) Service, which Mews creates automatically and which cannot be deleted, so every [Property](#Property) has a [Stay](#Stay) Service. Services can have a service fee, and can also have associated [Products](#Product). All [Products](#Product) are linked to Services. Some [Products](#Product) are bundled with a Service when the [Reservation](#Reservation) is made, according to configured [Product Rules](#ProductRule), this is called a [Package](#Package). You can read more about the relationship between services and products in [Understanding services](https://help.mews.com/s/article/understanding-services?language=en_US). ## Service Order A Service Order is an [Order](#Order) made against a [Service](#Service). An [Order](#Order) made against a [Bookable Service](#BookableService) is known as a [Reservation](#Reservation). Thus a [Reservation](#Reservation) is a type of Service Order. When we think of [Reservation](#Reservation), we normally think of a [Stay](#Stay) [Reservation](#Reservation) (i.e. booking one's stay at a property). This is simply an [Order](#Order) made against the default [Stay](#Stay) [Service](#Service) . But a [Reservation](#Reservation) in the broadest sense could be an [Order](#Order) made against any [Bookable Service](#BookableService), e.g. car parking or a tennis court. An [Order](#Order) made against an [Additional Service](#AdditionalServices) (e.g. breakfast or minibar) is known as a [Product Service Order](#ProductServiceOrder). Some care is needed here, as this is strictly an Additional Service Order and not to be confused with [Products](#Product). In summary, A Service Order is one of two types, either a [Reservation](#Reservation) (an [Order](#Order) against a [Bookable Service](#BookableService)) or a [Product Service Order](#ProductServiceOrder) (an [Order](#Order) against an [Additional Service](#AdditionalServices)). ## Service Product A [Product](#Product) is a purchasable item linked to a [Service](#Service). Although all [Products](#Product) are associated with [Services](#Service), those linked to [Stay](#Stay) [Services](#Service) are sometimes called [Stay Products](#StayProduct) (or Reservation Products) and those linked to other [Services](#Service) are sometimes called Service Products. Thus Service Products are [Products](#Product) which can be booked against a [Customer](#Customer) [Profile](#Profile) without being linked to a [Reservation](#Reservation). ## Space A Space is a bookable, location-based [Resource](#Resource) such as a bed, guest room, dormitory, apartment, function room, tennis court or car parking bay which can be sold on the basis of a [Reservation](#Reservation) for a specified date/time and duration. It is used in preference to the more restricted definition of 'room'. In practice, most spaces are accommodation-based resources such as beds, guest rooms and dormitories, booked on a nightly stay basis, and some parts of the [Mews Open API](#OpenAPI-MewsOpenAPI) and some partner [Integrations](#Integration) may make that assumption. For more information about the Mews vision for space resources, see the [Mews Devs blog post about Project Spacetime](https://developers.mews.com/project-spacetime/). ## Space Category Space Category is the named category of [Space](#Space) which Mews uses when calculating [Availability](#Availability) and when distributing ARI ([Availability](#Availability), [Rates](#Rate) and [Inventory](#Inventory)) to sales [Channels](#Channel). For example, a hotel might have a Space Category of "double room", "twin room" or "single room". Space Category is different than [Space Type](#SpaceType), which is one of the parameters used within Mews Operations to define a Space Category. [Space Type](#SpaceType) defines what the type of [Space](#Space) is, e.g. room, dorm, car parking bay. Confusion can arise because in traditional systems Space Category is equivalent to 'room type', this has led to it naturally being referred to as 'space type', in fact within the Channel Manager API, **SpaceTypeCode** is used in this way in Inventory mappings. SpaceTypeCode actually refers to a Space Category, despite the name. Furthermore, to avoid confusion between the terms 'category' and 'type' within the Channel Manager API, actual [Space Types](#SpaceType) (as defined in this Glossary) are referred to instead as 'space classifications'. In summary: * Within the Channel Manager API, the terms 'space category', 'space type' and 'space type code' all refer to Space Category * Within the Channel Manager API, the term 'space classification' refers to [Space Type](#SpaceType) ## Space Classification Space Classification defines what the type of [Space](#Space) is, e.g. room, dorm, car parking bay. The term is used in the Channel Manager API and is synonymous with [Space Type](#SpaceType) within Mews Operations. The Channel Manager API avoids using the term 'space type' so as not to confuse it with [Space Category](#SpaceCategory). ## Space Type Space Type defines what the type of [Space](#Space) is, e.g. room, dorm, car parking bay. Space Type is one of the parameters used to define a given [Space Category](#SpaceCategory), and the two are different. In order to avoid confusion, within the Channel Manager API Space Type is instead referred to as 'space classification'. ## State State is a general term whose meaning depends on the context. In the [Mews Open API](#OpenAPI-MewsOpenAPI) it could refer to: * [Bill](#Bill) state, e.g. open or closed * [Preauthorization](#Preauthorization) state, e.g. chargeable, expired, cancelled, charged * [Task](#Task) state, e.g. open or closed * [Payment](#Payment) item state, e.g. charged, cancelled, pending, failed, verifying ## Stay Stay is synonymous with [Accommodation](#Accommodation) and refers to room-stay based [Services](#Service) offered by a [Property](#Property). These are the main [Services](#Service) that [Properties](#Property) offer to their [Customers](#Customer), in fact Mews automatically creates a default Stay service and you cannot delete it. Stay services are [Bookable Services](#BookableService), i.e. they can be reserved prior to a [Customer](#Customer)'s arrival. ## Stay Product A [Product](#Product) is a purchasable item linked to a [Service](#Service). Although all [Products](#Product) are associated with [Services](#Service), those linked to [Stay](#Stay) [Services](#Service) are sometimes called Stay Products (or Reservation Products) and those linked to other [Services](#Service) are sometimes called [Service Products](#ServiceProduct). Thus Stay Products are bookable [Stay](#Stay) [Products](#Product) linked to a [Reservation](#Reservation). ## Swagger Swagger is the old name for the [OpenAPI](#OpenAPI-Swagger) specification. ## Task Tasks are pieces of work that need to be done within the [Property](#Property). Tasks can be created within Mews Operations and allocated to [Employees](#Employee) or [Departments](#Department) to complete them. An [Employee](#Employee) logging in to Mews Operations sees their pending tasks on the Dashboard. ## Travel Agency A Travel Agency is a special type of [Company](#Company), representing a booking agent. Like other [Companies](#Company), Mews stores the details of the Travel Agency in a [Profile](#Profile), and like other [Companies](#Company) they can be attached to a booking or [Reservation](#Reservation). This can be set up automatically using [Channel Manager](#ChannelManager) [Mapping Tables](#MappingTable). Since Travel Agencies are a special type of [Company](#Company), within the API they may be considered as separate entities. ## User A User is an [Enterprise](#Enterprise) [Employee](#Employee) who has an account on the Mews system. ## Voucher A Voucher is a coupon or token that gives [Customers](#Customer) or [Companies](#Company) access to special [Rates](#Rate). A Voucher is linked to a private [Rate](#Rate), i.e. a [Rate](#Rate) that is not distributed publicly. The Voucher may be in physical form, but may simply be a unique identifying code. # Business use cases # Accounting 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). # Booking If you are implementing a Booking Engine and want to allow your customers to make bookings directly in Mews, you will want the [Mews Booking Engine API](https://mews-systems.gitbook.io/booking-engine-guide/). This is one of three solutions we offer for Booking Engine integration, from off-the-shelf to custom, depending on the resources you have available. All of this is described in the [Mews Booking Engine Guide](https://mews-systems.gitbook.io/booking-engine-guide/), of which the API is a part. # Customer Relationship 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). # Distribution 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/). # Door 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](/use-cases/data-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) # Events For integrating a meetings and events system into Mews, see the [Event management use case](https://mews-systems.gitbook.io/connector-api/use-cases/event-management) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api). # Guest Services Guest Services covers F\&B ordering or in-room dining, service requests, information directories and other guest-facing services. For guest messaging, see the [Messaging use case](https://mews-systems.gitbook.io/connector-api/use-cases/messaging) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api). You may also be interested in data-based use cases such as [Working with Profiles](/use-cases/data-use-cases/profiles). If the guest service is directly related to guest technology such as telephones or entertainment systems, see [Guest Technology use cases](/use-cases/business-use-cases/guest-tech). # Guest Technology 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). # Kiosk Kiosk covers all customer self-service applications, including physical kiosks and mobile apps. See the [Kiosk use case](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api). # Legal Legal integrations includes Government police reports and mandatory legal & financial reporting, which varies from region to region. These are special cases that lie outside the scope of the **Mews Open API**. Contact for further information. # Payment For automated payment processing, see the [Payment automation use case](https://mews-systems.gitbook.io/connector-api/use-cases/payment-automation) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api). For handling payments for Booking Engine integrations, you can find information on on-session payments, payment card authorization and supporting payment cards in the [Booking Engine API use cases](https://mews-systems.gitbook.io/booking-engine-guide/use-cases). # Point Of Sale A general-purpose API that gives real-time access to data and services in Mews POS (Point-of-sale). Supports use cases such as business intelligence, inventory management, table bookings, etc. * See [Mews POS API](https://docs.mews.com/pos-api/) For retail outlet (POS) integrations using the Connector API, see the [Point of sale use case](https://mews-systems.gitbook.io/connector-api/use-cases/point-of-sale) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api). # Reputation & Loyalty This category of use cases concerns customer reputation management and customer loyalty programs. See the [Reputation management use case](https://mews-systems.gitbook.io/connector-api/use-cases/reputation-management) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api). # Revenue Management 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). # Service Optimization 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). # Upsell For upselling (e.g. selling personalised room upgrades and add-on products and services), see the [Upselling use case](https://mews-systems.gitbook.io/connector-api/use-cases/upsell) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api). # Data use cases # Working with Devices We use the term *Devices* to describe physical on-premise devices which we integrate into our cloud-native system, this includes key cutters or key encoders and also printers for printing hard-copy of guest bills. Integration with such Devices is described in the [Device integrations use case](https://mews-systems.gitbook.io/connector-api/use-cases/device-integrations) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api). # Working with Profiles We don't yet have a dedicated page about working with customer profiles, but you may find something useful here: * [Kiosk use case](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api) * [Reputation management use case](https://mews-systems.gitbook.io/connector-api/use-cases/reputation-management) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api) # Working with Reservations We don't yet have a dedicated page about working with reservations, but you may find something useful here: * [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) * [Kiosk use case](https://mews-systems.gitbook.io/connector-api/use-cases/kiosk) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api) * [Reputation management use case](https://mews-systems.gitbook.io/connector-api/use-cases/reputation-management) in the [Mews Connector API](https://mews-systems.gitbook.io/connector-api) * [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) # Onboarding For on-boarding new properties to your solution, please take a look at the following Help Guides: * [Connector API onboarding guide](https://help.mews.com/s/article/connector-api-integrations-onboarding-mutual-customers?language=en_US) * [Channel Manager API onboarding guide](https://help.mews.com/s/article/channel-manager-onboarding-guide?language=en_US) # Partner Newsletters To subscribe to future Partner Newsletters by email, [sign up here](https://www.mews.com/en/partners-newsletter-subscription). ## Newsletter contents * [(Apr 2023) The Partner Mewsletter April 2023](/staying-up-to-date/partner-newsletters/partner-mewsletter-apr23) * [(Oct 2022) All About Deprecations](/staying-up-to-date/partner-newsletters/partner-mewsletter-oct22) * [(Jul 2022) API Versioning - Share your thoughts](/staying-up-to-date/partner-newsletters/partner-mewsletter-jul22) # Apr 2023 Mewsletter *14 Apr 2023* ## The Partner Mewsletter April 2023 Hello from the **Mews Connectivity Team**! It’s that time again! We have been busy, so here’s what you need to know. ### AVAILABLE RIGHT NOW * **Payment requests** * **Set restrictions** * **Accounting items split** * **Company billing** * **More pagination** * **Time filters** * **Mews Payment Terminals** ### COMING SOON * **Multi-property API** * **Availability blocks** *** ### Payment requests You can now trigger a payment request through the API and make full use of the **Mews payment infrastructure** to offer a seamless and secure guest experience directly in your application – great if you don’t typically deal with payments but want to offer a full end-to-end guest experience. * **API Operations**: [Payment requests](https://mews-systems.gitbook.io/connector-api/operations/paymentrequests) * **Mews Help**: [Send a payment request by email](https://help.mews.com/s/article/send-a-payment-request-by-email?language=en_US) *** ### Set restrictions We’ve added a more efficient way to manage restrictions, with [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). You tell us what the restrictions should look like, and we take care of the underlying calculations – simpler and more efficient for both parties. * **API Operations**: [Restrictions](https://mews-systems.gitbook.io/connector-api/operations/restrictions) *** ### Accounting items split Accounting items have been split into separate operations for **Order items** and **Payment items**. You can fetch the data you want faster and more efficiently, and now using pagination too. * **API Operations**: [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) *** ### Company billing Now the owner of a bill or invoice can be a **company** or an individual **customer**, to clearly indicate who the payer is, whilst company information can still be attached for cases where a customer pays the bill but is reimbursed by their company. It’s simpler and clearer to bill to a company, and all use cases are covered. * **API Operations**: [Add order](https://mews-systems.gitbook.io/connector-api/operations/orders#add-order), [Add external payment](https://mews-systems.gitbook.io/connector-api/operations/payments#add-external-payment), [Add bill](https://mews-systems.gitbook.io/connector-api/operations/bills#add-bill) * **Mews Help**: [How to create and manage company bills](https://help.mews.com/s/article/How-to-create-and-manage-company-bills?language=en_US) *** ### More pagination All the most popular ‘Get’ operations now support [pagination](https://mews-systems.gitbook.io/connector-api/guidelines/pagination). Use pagination for more efficient fetching of data, to avoid [request timeouts](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-timeouts) and to benefit from a **higher quota** – all part of API [best practices](https://mews-systems.gitbook.io/connector-api/guidelines/best-practices). *** ### Time filters We’ve added support for **UpdatedUtc** to several API Operations, such as [Get all bills](https://mews-systems.gitbook.io/connector-api/operations/bills#get-all-bills) and [Get all outlet items](https://mews-systems.gitbook.io/connector-api/operations/outletitems#get-all-outlet-items). Filter against dates when the data was updated to optimize your searches and reduce unnecessary data transfer. Find them all in the [API Changelog](https://mews-systems.gitbook.io/connector-api/changelog). *** ### Mews Payment Terminals For **Kiosk** and **POS** partners, we’ve added [a new use case](https://mews-systems.gitbook.io/connector-api/use-cases/mews-terminals) to explain how to connect to Mews Payment Terminals. Increase customer revenue and customer convenience by taking advantage of Mews Terminals. *** ### Multi-property API You will soon be able to access data and services for an entire property chain through **a single Access Token**. Manage common resources like companies and customers more efficiently at the chain level. Stay tuned for news on this exciting development! *** ### Availability blocks You will soon be able to release blocks of inventory back into public availability **on a rolling basis**. Fine-tune your availability management to maximize your revenue potential. Keep an eye on the [Changelog](https://mews-systems.gitbook.io/connector-api/changelog) for changes as they occur. Until next time... \~ The Mews Connectivity Team # Oct 2022 Mewsletter *21 Oct 2022* ## All About Deprecations Hello from the Mews Connectivity Team. In this Mewsletter, we have three things for you: * **An Important Call to Action!** * **A Thank You** * **Exciting News about Future Releases** ### An Important Call to Action! First and foremost, we are stopping support of the old URL **mews.li** on November 1st. This has been mentioned repeatedly over the past year, and the time has now come to move over 100% to the new URL **mews.com**. If you are among the tiny percentage of users still using the old URL... **PLEASE MOVE TO api.mews.com IMMEDIATELY!** ### A Thank You A warm thank you to our partners who completed the [Survey Questionnaire](https://mews.typeform.com/to/JCpBXN9h) and gave us valuable feedback on our plans to develop the **Mews Open API**. We are always keen to hear your opinions. You may notice we have added a feedback widget to all our documentation pages. We hope you will use this to let us know which pages are working for you and which ones need attention.
 ### Exciting News about Future Releases Let's talk about deprecations! We realize this is important, especially as we continue to roll out new features, and we've listened to your feedback. As a result, we are developing a detailed **Policy and FAQ** which we will share through our documentation. In summary: * Minor breaking changes will have a 6-month deprecation period * Major breaking changes will have a 12-month deprecation period * All deprecations will be listed, complete with planned stoppage dates Talking of documentation, we now have a single landing page for the [**Mews Open API**](https://mews-systems.gitbook.io/open-api/) – this sits over our three individual APIs. Not sure which is the right one for you? This is the place to go. There is plenty more happening, so keep an eye on the **Changelogs** for new features! And as always, if you have questions, just get in touch! 
Until next time... \~ The Mews Connectivity Team # Jul 2022 Mewsletter *26 Jul 2022* ## API Versioning – Share your thoughts TL;DR: We have a plan to add versioning to the Mews Connector API, but, first, we want to get your opinions. Click [here](https://mews.typeform.com/to/JCpBXN9h) to take a quick survey. Now the full story: We’ve come up with a strategy to speed up our development in a way that will provide you with higher performance endpoints, more rapidly roll out functionality for earlier adopters, and give all partners sufficient time to plan for upcoming, potentially high-impact changes. What we’re talking about is adding versioning to the Mews Connector API. With the new approach, we would continue to make improvements that remain compatible with the current implementation, but if we need to make larger changes that cannot be made backwards compatible, we would then introduce a new version of the same endpoint that you have the choice to opt into. Before we move ahead, though, **we want to get your thoughts on what would work best for your needs**. Of course, we’re also happy to talk further if you'd like. | | | :------------------------------------------------------------: | | [API Versioning Survey](https://mews.typeform.com/to/JCpBXN9h) | Your feedback is greatly appreciated. \~ The Mews Team # Changelogs # Deprecations # Deprecations Policy Sep 3rd, 2024 ## Contents This policy addresses the following: * [Why we have this policy](#why-we-have-this-policy) * [What do we mean by deprecated?](#what-do-we-mean-by-deprecated) * [What we deprecate and why](#what-we-deprecate-and-why) * [When we deprecate](#when-we-deprecate) * [How we deprecate](#how-we-deprecate) * [How long is the stoppage notice period?](#how-long-is-the-stoppage-notice-period) * [How deprecations are communicated](#how-deprecations-are-communicated) * [As a user, what should I do?](#as-a-user-what-should-i-do) * [Deprecations and versioning](#deprecations-and-versioning) * [Questions and feedback](#questions-and-feedback) ## Why we have this policy Changes to the APIs are necessary and inevitable as part of continuous improvement to our products and services. We try to make those changes in such a way that there is only positive impact on users. For example, we announce new features and other changes, we encourage you to take advantage of them and we actively try to avoid making breaking changes, i.e. changes that would impact your current implementation. Sometimes, however, breaking changes are unavoidable. So the question becomes, how can we manage these changes in a way that has the least negative impact on users? The answer is not to simply stop a feature or make a breaking change without plenty of notice. Making a feature `deprecated` is us giving notice that this feature will be stopped in the future. ## What do we mean by deprecated? * **Deprecated**\ A feature which is `deprecated` is considered an old feature that users should migrate away from; it is no longer up to date; the implication is that there is a better way to do something, or else this something should no longer be done at all; a `deprecated` feature is still supported, it still works, but this is likely to be only for a limited period of time to allow users to migrate away to the preferred alternative. * **Discontinued**\ A feature which is `discontinued` no longer exists, it is no longer supported, it is withdrawn, gone, kaput, dead; we might also use `stopped` to mean the same thing. * **Breaking changes**\ `Breaking changes` are changes that could potentially impact your current implementation, assuming you use the changed feature. * **Non-breaking changes**\ `Non-breaking changes` are changes that should *not* impact your current implementation, regardless of what features you use. * **Stoppage notice period**\ The `stoppage notice period` or `deprecation period` is the notice period between a feature being deprecated and it being discontinued. ## What we deprecate and why In the context of our APIs, *feature* could mean any of these things: * An entire API endpoint or operation * A part of the functionality of an API operation * A data field or property of an API operation * A URL or part of a URL * A way of communicating, e.g. use of webhooks or methods for authentication As to the why, we deprecate features because we need to make breaking changes and this is a way to let you know that you should change your implementation, and to give you time to do so - see [Why we have this policy](#why-we-have-this-policy). ## When we deprecate Most changes to the API do not in fact involve deprecation. For example: * Adding a new endpoint * Adding fields to an existing endpoint These are considered non-breaking changes, in other words changes that do not require any change to legacy implementations for their continued working. Deprecations are planned breaking changes, i.e. a statement that we intend to make a breaking change. We plan it so that any such change does not produce unexpected behaviour (see [As a user, what should I do?](#as-a-user-what-should-i-do)) and we follow a clear deprecation process (see [How we deprecate](#how-we-deprecate)) to keep you informed and allow you to implement the necessary changes to your implementation. ## How we deprecate This is the process or life cycle for a deprecated feature: 1. **Announcement** - We announce in the Changelog what feature is deprecated and add it to the Deprecations table; a discontinuation or stoppage date will be set. 2. **Push back** - (Optional) The discontinuation or stoppage date may be pushed back, according to circumstances; it will never be brought forward. 3. **Reminder** - (Optional) We may remind users of pending stoppages prior to the stoppage occurring, but this depends on circumstances such as the scale and importance of the change. 4. **Stoppage** - We permanently stop support for the feature. What we *won't* do: * We won't just discontinue any feature of the API without first going through a deprecation process. * We won't bring forward the discontinuation or stoppage date. * We won't plan a change that could cause unexpected behaviour if a user continues to try and use a discontinued feature. > **Soft stoppage** > > When a feature is stopped or discontinued, it is removed from the documentation and no longer supported or maintained. However, we do not immediately 'switch off the lights'. We try to contact affected partners to make sure they are aware of the stoppage, and we temporarily remove the feature via brown-outs, as a way of communicating with those partners that were otherwise not informed or failed to take action. We do this for a period of time that is agreed with affected partners, or at our own discretion, before finally pulling the plug and permanently terminating the feature. ## How long is the stoppage notice period? The stoppage notice period or deprecation period is the notice period between a feature being deprecated and it being discontinued. We reserve the right to change the duration of this period in order to optimise the process, but our guideline is: * Minimum of **ONE YEAR** for all changes * All changes batched to fall on the next **JANUARY** > **For example**: A feature deprecated on June 28th, 2024 would be discontinued in January of 2026. A feature deprecated on October 28th, 2024 would also be discontinued in January of 2026. Batching the changes like this is intended to make the maintenance task much easier for our customers and partners, and indeed for us. ## How deprecations are communicated * **Changelog**\ The Changelog tracks individual changes to the API, including deprecations. * **Deprecations table**\ The documentation for each individual API includes a Deprecations page which summarises all deprecations in the API. It provides the necessary information in these table columns: * **Feature** - What is deprecated * **Comments** - Additional information, such as the reason for the deprecation and what the replacement feature is * **Deprecated** - The date when the deprecation occurred, i.e. was announced in the Changelog * **Discontinued** - The date when the deprecated feature will be discontinued altogether (or *was* discontinued if the date has passed), or '-' if no date has been set * **API Operations**\ Deprecated features are shown in the API reference documentation with strikethrough (e.g. ~~TaxValues~~), followed by the label **Deprecated!**. * **OpenAPI definition**\ Where we publish an OpenAPI definition for the API (linked from the home page), deprecated features are indicated, as per the OpenAPI specification. ## As a user, what should I do? Check the Changelog periodically, but not less often than once a month; optionally, you can set up a notification alert on the GitHub repository for our API Docs to be informed whenever there is an update to the master branch. Where a deprecation is announced, check your implementation and, if relevant, plan a change to your implementation. This change must be completed within the deprecation period (stoppage notice period). If you are stuck for any reason, get in touch! (see [Questions and feedback](#questions-and-feedback)). > **What will be the impact if I fail to change my implementation in time?** > > If you try to use a `deprecated` feature after its discontinuation / stoppage date, then the functionality will simply not work. We plan that all discontinued features will not produce unexpected behaviour, but will fail in a safe manner. For example, if you call a discontinued endpoint, we will return an http `410` code, indicating "this resource no longer exists". What should never happen is that you use some feature and it works, but works differently to how it did before. Discontinued features should always fail outright. ## Deprecations and versioning The deprecations policy remains the same if versioning is implemented within an API. For example, if an endpoint or operation moves from v1 to v2, then v1 will be a deprecated feature and subject to the normal policy and process. ## Questions and feedback If you have any questions that are not answered by this policy, or you think that a change is needed to this policy, you require further information, or have any other reason as an API user to communicate about this policy, please as always just get in touch through any available channels, including email to . # Mews Connector API General-purpose API that enables partners of Mews to access data and services in Mews Operations. 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](/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](/connector-api/guidelines). To gain deeper insights into Mews concepts, see [Concepts](/connector-api/concepts). For guidance on using the API for specific scenarios, our [Use cases](/connector-api/use-cases) section will help you through your implementation. Detailed information on all API operations can be found in [API Operations](/connector-api/operations), and information on event mechanisms like Webhooks in [API Events](/connector-api/events). If you have any questions or you encounter issues, please [contact support](/connector-api/contact-support). #### Changes to this API * For the history of changes to the API, see the [Changelog](/connector-api/changelog). * For important information on deprecations, see [Deprecations](/connector-api/deprecations). * To track changes and updates, you can follow the [GitHub repository](https://github.com/MewsSystems/open-api-docs). {% hint style="info" %} #### 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. {% endhint %} # Getting started 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. {% hint style="info" %} #### Ready to try a test call? Jump to [Step 2: Make your first API call](#make-your-first-api-call). {% endhint %} ## 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](/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](/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](/connector-api/guidelines/requests#request-limits). {% hint style="info" %} #### Want to know more? For full details, see [Authentication](/connector-api/guidelines/authentication) and [Environments](/connector-api/guidelines/environments). {% endhint %} {% stepper %} {% step %} ### Set up your environment To begin testing: 1. **Choose a demo property** from the list in [Demo environments](/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)** [Request a dedicated Demo Property](/connector-api/guidelines/environments#mews-operations-credentials) in **Mews Operations** to explore the UI and sample data. You’ll use these credentials to make authenticated API requests. {% endstep %} {% step %} ### Make your first API call Let’s start by calling [Get configuration](/connector-api/operations/configuration#get-configuration), which returns details about the test property — a useful check that your setup is working. * **Endpoint URL** ``` https://api.mews-demo.com/api/connector/v1/configuration/get ``` * **Request body** ```json { "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: ```json { "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" } } ``` {% hint style="info" %} #### Requests and responses For more on request formatting and response codes, see [Requests](/connector-api/guidelines/requests) and [Responses](/connector-api/guidelines/responses) respectively. {% endhint %} {% endstep %} {% step %} ### Learn the API essentials #### Time and data serialization * All dates and times are in UTC. * Dates, durations and other data types follow specific [serialization rules](/connector-api/guidelines/serialization). #### Pagination * Some operations (like [Get all reservations](/connector-api/operations/reservations#get-all-reservations-2023-06-06)) use [pagination](/connector-api/guidelines/pagination) to handle large result sets. #### 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. #### Error handling * Check the [response code](/connector-api/guidelines/responses#response-codes) and [details](/connector-api/guidelines/responses#error-response-details) to diagnose issues. * Always validate required fields and timezones in your request payloads. {% hint style="info" %} #### Best practices For additional tips on how to get the most out of your integration, see our best practices. {% endhint %} {% endstep %} {% endstepper %} ## Next steps Now that you've made a successful call, here’s where to go next: * [Usage guidelines](/connector-api/guidelines) – How to structure requests, handle authentication, best practices, and more. * [API Operations](/connector-api/operations) – Full list of API Operations. * [API Events](/connector-api/events) – How to receive near-real-time event notifications. * [Concepts](/connector-api/concepts) – Deeper insights into selected Mews concepts. * [Use cases](/connector-api/use-cases) – Guidance on using the API for common scenarios. * [Certification](/connector-api/your-journey/certification) – What’s required before going live. * [Mews Glossary for Open API users](/getting-started/glossary) – Terminology for terms like *enterprise*, *customer*, and *resource*. # Usage guidelines This section provides important guidelines on how to use the **Mews Connector API**. For a deeper understanding of Mews concepts, see [Concepts](/connector-api/concepts). For information about individual endpoints or operations, see [API Operations](/connector-api/operations). {% hint style="info" %} #### 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](/getting-started/glossary). {% endhint %} ## Contents * [Authentication](/connector-api/guidelines/authentication)\ Details of how API Operation requests are authenticated. * [Requests](/connector-api/guidelines/requests)\ Details of how to make API Operation requests. * [Responses](/connector-api/guidelines/responses)\ Details of API Operation responses, including error messages. * [Environments](/connector-api/guidelines/environments)\ A description of the different environments available and how to access them, including test credentials, request limits and more. * [Serialization](/connector-api/guidelines/serialization)\ Various topics related to data formats. * [Pagination](/connector-api/guidelines/pagination)\ An explanation of the pagination feature and how to use it to fetch data. * [Best practices](/connector-api/guidelines/best-practices)\ Advice on best practices for using the API. # Authentication 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. ## 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. ### 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](/connector-api/concepts/multi-property). ## Obtaining your tokens ### Demo environment Public tokens are available for the demo environment. For more details, see [Environments](/connector-api/guidelines/environments). ### Production environment To receive credentials for production usage, you must successfully complete a [certification process](/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. # Requests 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: ``` [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. ## 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](/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. ```javascript { "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](/connector-api/operations/languages#language). | | `CultureCode` | string | optional | Code of the culture. | ## 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](/connector-api/guidelines/environments#request-limits). Request limits are enforced using a sliding window, not fixed time buckets. This means the 30-second window is anchored to the first request in a burst, not to clock boundaries such as `:00` or `:30`. If your system measures its own request rate using fixed intervals, it may undercount requests and still receive `429 Too Many Requests` responses even when it appears to be below the documented limit. Rate limits are also enforced on a best-effort basis. Under certain conditions, such as traffic being routed across multiple edge locations, the observed behavior may differ slightly from the documented limit. The stated limit is a guideline, not a strict guarantee in either direction. Regardless, your system should be prepared to receive a `429 Too Many Requests` response in cases where you hit such a limit - see [Responses](/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. The `Retry-After` header should be the primary signal for backoff timing. In some cases the header may not be present, so your implementation should fall back to an exponential backoff strategy. Using a progressively longer wait between re-tries for consecutive error responses is recommended. 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. ## 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](/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? This error usually means the request is taking too long because too much data is being loaded to prepare the response. The best solution is to reduce the amount of data returned. Follow our [Best practices](/connector-api/guidelines/best-practices) to reduce the likelihood of timeouts and specifically use [Pagination](/connector-api/guidelines/pagination) to fetch data in smaller batches where supported. ## Request minimal response > ### 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. ```http 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](/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](/connector-api/operations/accountnotes#delete-account-notes). # Responses ## 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](/connector-api/guidelines/requests#request-minimal-response)), the `Content-Type` header is *not* set and the response body is empty. ## 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](/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 identification of the request, that can be used when [contacting the support](/connector-api/contact-support). ### 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](/connector-api/guidelines/requests#request-minimal-response). ### 400 Bad request The request is invalid or cannot be processed due to a client-side error, such as malformed input or an invalid resource identifier. In most cases, this response indicates an issue in the client application. `Invalid {Parameter}`: The referenced resource does not exist or is in an invalid state for the given endpoint (for example, attempting to close a bill that is already closed). If you are unable to identify the issue in the request, [contact support](/connector-api/contact-support). `Invalid JSON`: The request body is not valid JSON. The API enforces strict JSON formatting and does not allow issues such as trailing commas after the last field or bracket. Use a JSON validator that strictly follows the JSON specification to identify formatting errors. ### 401 Forbidden The request could not be authorized due to invalid or expired credentials, or because the client does not have sufficient permissions to access the endpoint. The provided `ClientToken` or `AccessToken` is invalid or has expired, see [Authentication](/connector-api/guidelines/authentication) for more information. Another cause might be the enterprise has been disabled in Mews or the integration is disabled either for the enterprise or in Mews. The client does not have permission to perform the requested operation. [Contact support](/connector-api/contact-support) to start or update the certification process to request access to the required endpoint. ### 403 Forbidden An error returned by the server that should be surfaced to the end user of the client application. This typically occurs when server-side validation fails or a business-logic rule is violated. Report the response message to the enterprise to cross-check their settings in Mews with the action they tried to complete. They should make a decision on which version should change. ### 404 Not found The server cannot find the resource requested by the client app. Verify the URL and request method. Make sure the URL of the endpoint matches operation's URL exactly, including case sensitive characters, and there are no extraneous slash characters. ### 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](/connector-api/guidelines/requests#request-timeouts). Make sure you're following all of our [Best practices](/connector-api/guidelines/best-practices), otherwise we will not be able to resolve the timeouts. Contact Partner Success in case you're consistently recieveing timeouts. ### 409 Conflict The request cannot be completed because the data has changed. Refresh data on the client and resubmit the request. ### 413 Content Too Large The request body is too large. Try reducing the amount and size of request parameters (for example, by splitting the payload to multiple requests). In case of binary file upload, consider reducing the resolution of photos and scanned documents. ### 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](/connector-api/guidelines/requests#request-limits). Follow the suggestions in [Request limits](/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. Retry the operation or [contact support](/connector-api/contact-support) if the issue persists. ## 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. Provide this unique identifier when [contacting support](/connector-api/contact-support) 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. | # Environments Mews supports two main environments: Demo and Production. Demo can be used for integration development and testing. Production is for live customer sites. ## 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. ## Demo environments ### 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. ### 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` ### 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](#taxations) for proper usage of the relevant [Tax rate](/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` ### 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](#taxations) for proper usage of the relevant [Tax rate](/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` ### Mews Operations credentials #### New Partners Partners who have not enrolled into the Certification Process can request access to **Mews Operations** for a dedicated Demo Property by following these steps: 1. Fill in the [Become a Mews Partner Form](https://www.mews.com/en/partners/new-partnerships). 2. An automated email will be sent to your email address to reset your password to log in into the Demo Property. 3. Reset the password. 4. Now, you can successfully log in into the Demo Property through [demo environment of Mews Operations](https://app.mews-demo.com). 5. You will be automatically opted in to both the [Gross Pricing](#api-tokens-gross-pricing-environment) and [Net Pricing](#api-tokens-net-pricing-environment) Demo Environment properties. If needed, you can opt out of either Gross or Net Demo Environment individually and remain integrated with only one Environment. #### Existing Partners Partners who are already enrolled in the Certification Process or Certified and Live should follow the steps below: 1. Do not use generic Credentials to connect to the Demo Properties 2. [Contact the partner succes team](/connector-api/contact-support) to request user access to the Demo properties. 3. Provide the following details for each user to be added: * Demo property name * User's first and last name * User's email address 4. The partner success team creates the user in the Demo properties. 5. An automated email will be sent to your email address to reset your password to log in into the Demo Property. 6. Reset the password. 7. Now, you can successfully log in into your demo property through the [demo environment of Mews Operations](https://app.mews-demo.com). ### 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](/connector-api/guidelines/requests#request-limits) for more information. Request limits are enforced using a sliding window, not fixed time buckets. The 30-second window is anchored to the first request in a burst, not to clock boundaries such as `:00` or `:30`. Rate limits are best-effort. Under certain conditions, such as traffic being routed across multiple edge locations, the observed limit may differ slightly from the documented value. The stated limit is a guideline, not as a strict guarantee in either direction. Your application must be prepared to handle `429 Too Many Requests` responses. The `Retry-After` response header is the primary signal for backoff timing. If the header is not present, implement exponential backoff as a fallback. See [Request limits](/connector-api/guidelines/requests#request-limits) for more information. ## Production environment ### Security Policy > **IMPORTANT!** To protect the live data of each enterprise, please store your production tokens securely and do not share them publicly. ### Addresses * **PlatformAddress** - `https://api.mews.com` * **WebSocketAddress** - `wss://ws.mews.com` * **Mews Web Application Address** - `https://app.mews.com` ### 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](/connector-api/your-journey). * **AccessToken** - Unique token per enterprise. Can be provided to you by the enterprise admin. ### 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](/connector-api/guidelines/requests#request-limits) for more information. Request limits are enforced using a sliding window, not fixed time buckets. The 30-second window is anchored to the first request in a burst, not to clock boundaries such as `:00` or `:30`. Rate limits are best-effort. Under certain conditions, such as traffic being routed across multiple edge locations, the observed limit may differ slightly from the documented value. The stated limit is a guideline, not as a strict guarantee in either direction. Your application must be prepared to handle `429 Too Many Requests` responses. The `Retry-After` response header is the primary signal for backoff timing. If the header is not present, implement exponential backoff as a fallback. See [Request limits](/connector-api/guidelines/requests#request-limits) for more information. ## Taxations Each enterprise operates within a specific [Tax environment](/connector-api/operations/taxenvironments#tax-environment), which defines the applicable [Taxations](/connector-api/operations/taxations#taxation). The tax rates are represented by [Tax rate](/connector-api/operations/taxations#tax-rate) codes accepted within that environment. Instead of using numeric tax rates like `0.1`, use [Tax rate](/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](/connector-api/operations/configuration#get-configuration) to identify the Tax Environment. 2. Filter for the applicable [Tax rate](/connector-api/operations/taxations#tax-rate) codes from the tax environment information retrieved via [Get all tax environments](/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. ## 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. # Serialization ## 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`. > #### 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. > #### 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. > #### 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. > #### 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` ## 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` ## Update values ```javascript { "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. ```javascript { "PropertyWithoutChange": null, "PropertyWithNewValue": { "Value": "NewValue" }, "PropertyWithDeletedValue": { "Value": null } } ``` ## Coproducts ```javascript { "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](/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. ```javascript { "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" } ``` # Pagination 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: ### Request `[PlatformAddress]/api/connector/v1/{entity}/getAll` ```javascript { "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](#limitation) | required | Limitation on the quantity of data returned (using cursor pagination). | #### 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. ### Response ```javascript { "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](#limitation) in a subsequent request to fetch the next batch of older data. If [Limitation](#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](/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. ### 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. # Best practices 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. * **Use RequestId**\ Every failed API request has `RequestId` property in the [Error response details](/connector-api/guidelines/responses#error-response-details). We highly recommend to include this information in your observability solution. Provide this value when [contacting support](/connector-api/contact-support). * **Handling HTTP status codes**\ Follow our recommendations on handling each [response code](/connector-api/guidelines/responses#response-codes) and how to resolve most common issues. * **Webhooks instead of polling**\ Instead of periodically polling for updates using a 'get' operation, use [Webhooks](/connector-api/events) instead and subscribe to updates. [Contact support](/connector-api/contact-support) if a Webhook for an event is not supported . For more information, see [Ways to communicate](/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](/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](/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](/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](/getting-started/glossary#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, [contact support](/connector-api/contact-support) with a request to add it. * **Cache data and limit high-traffic calls**\ Querying for static or frequently needed data on every request adds unnecessary traffic and slows down the user experience. Cache data that don't change often (e.g. resource categories, services, products, accounting categories, business segments, configuration, taxes). For high-traffic or get-all style endpoints (availability, restrictions, pricing), don't call on every page view, refresh, or keystroke. Cache responses (e.g. 30–60 seconds for search-like data), filter to the minimal scope, use [pagination](/connector-api/guidelines/pagination), and apply client-side rate limiting and exponential backoff when you see increased latency or errors. * **Graceful degradation and resiliency**\ Assume that API calls can be slow, fail, or be throttled, resulting in [error responses](/connector-api/guidelines/responses#500-internal-server-error-and-other-5xx-response-codes), [timeouts](/connector-api/guidelines/responses#408-request-timeout) or [blocking](/connector-api/guidelines/responses#429-too-many-requests). Degrade only the affected feature (e.g. availability refresh), not the whole product. Fail fast in interactive flows and retry in the background with exponential backoff. See [request limits](/connector-api/guidelines/requests#request-limits). * **Respect shared capacity**\ The API is multi-tenant: your traffic shares capacity with other properties and partners. Implement client-side rate limiting and backoff so that you don't keep sending requests when you receive 429 or see increased latency. Mews rate limiting protects the system, but your integration should avoid hitting it in the first place. Proactively monitor your traffic volume and resolve client-side issues before they escalate. Stay within documented limits. If your usage will change significantly, coordinate with Mews in advance so we can anticipate load and help avoid impact on your integration and others. * **Planned campaigns and traffic spikes**\ When planning activities resulting in substantially higher traffic (e.g. marketing campaigns, bulk operations), inform Mews via your partner contact or [contact support](/connector-api/contact-support) with the planned time window, expected traffic multiplier, and affected endpoints, so we're aware in case something goes wrong and have a quick contact point. We do not offer increased rate limits; ensure your integration fits within [request limits](/connector-api/guidelines/requests#request-limits) and handles being rate limited. Your integration should use caching, [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff), rate limiting, and [circuit breakers](https://en.wikipedia.org/wiki/Circuit_breaker_design_pattern) in place. * **Consequences of not following best practices**\ Integrations that repeatedly ignore basic best practices (for example, continuing to send requests at high volume after being rate limited) may be blocked by Mews to protect our systems and other users. # Concepts 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. {% hint style="info" %} #### 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](/getting-started/glossary). {% endhint %} ## Contents * [Multi-property](/connector-api/concepts/multi-property)\ An explanation of multi-property operation with Portfolio Access Tokens. * [Restrictions](/connector-api/concepts/restrictions)\ An explanation of the algorithms used to support setting and clearing restrictions. * [Taxation](/connector-api/concepts/taxation)\ An explanation of the different tax environments and how they impact your integration. * [Time units](/connector-api/concepts/time-units)\ A detailed explanation of the time units used to describe service reservations. # Multi-property {% hint style="info" %} #### 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](/getting-started/glossary). {% endhint %} **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. ## 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. ![](/files/FeQAHzp7ZY5hP4ebPFok) ## 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](/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](/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](/connector-api/operations/configuration#get-configuration), the operation returns information on the 'dummy' enterprise used to identify the portfolio. ## 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](/connector-api/operations/companies#get-all-companies) and [Get all loyalty programs](/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`. ![](/files/E5nSEFkcPW90xWLAbhfU) ## FAQ ### 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 [contact support](/connector-api/contact-support). ### 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. ### 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](/connector-api/operations/orderitems#get-all-order-items). Such operations will normally also have `EnterpriseId` or `EnterpriseIds` as a request parameter. # Restrictions An explanation of the algorithms used to support [Set restrictions](/connector-api/operations/restrictions#set-restrictions) and [Clear restrictions](/connector-api/operations/restrictions#clear-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) {% hint style="info" %} #### 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) {% endhint %} ## Restrictions in the API To retrieve information about restrictions, use [Get all restrictions](/connector-api/operations/restrictions#get-all-restrictions). To add and remove restrictions, use [Set restrictions](/connector-api/operations/restrictions#set-restrictions) and [Clear restrictions](/connector-api/operations/restrictions#clear-restrictions) respectively. | 'How to' use case | API Operations | | ---------------------------------- | ----------------------------------------------------------------------------------- | | How to get service restrictions | [Get all restrictions](/connector-api/operations/restrictions#get-all-restrictions) | | How to add service restrictions | [Set restrictions](/connector-api/operations/restrictions#set-restrictions) | | How to remove service restrictions | [Clear restrictions](/connector-api/operations/restrictions#clear-restrictions) | {% hint style="warning" %} #### Restrictions are independent of user and API restrictions As an API user you can only set and clear your own restrictions, independently of restrictions set within the user interface of **Mews Operations**.. See [Scope of restrictions](#scope-of-restrictions) for more details. {% endhint %} ## Restrictions quota limit Each service can have up to 150,000 active restrictions at any given time. This includes restrictions created both through the API and through the user interface of **Mews Operations**. In practice, the risk of hitting this quota is low because [Set restrictions](/connector-api/operations/restrictions#set-restrictions) merges multiple similar restrictions into a single restriction. Its sibling operation [Clear restrictions](/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. ## Merging algorithm When using [Set restrictions](/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](#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. ## Matching conditions The conditions specified in [Set restrictions](/connector-api/operations/restrictions#set-restrictions) and [Clear restrictions](/connector-api/operations/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](/connector-api/operations/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. ## 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](/connector-api/operations/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. ## 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. {% hint style="danger" %} #### Single third-party integration per enterprise 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 Operations** 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 restrictions](/connector-api/operations/restrictions#get-all-restrictions). {% endhint %} # Taxation ## 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. ## 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](/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](/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](/connector-api/operations/taxations#get-all-taxations) to retrieve the individual tax `Codes`, their names and values. ## 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. ## 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. ```javascript "TaxCodes": [ "US-MA-S", "US-MA-EXCISE-0.75%" ] ``` ## 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](/connector-api/operations/taxenvironments#get-all-tax-environments). # Time units 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](#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. #### Figure 1: Illustration of a nightly service ![](/files/gDsyqmJFIgCzwetULSk9) #### Figure 2: Illustration of a daytime service ![](/files/26JJlq0fryIHnvp23iS8) # Use cases 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. ## 'How to' use cases * ['How to' use cases](/connector-api/use-cases/how-to) ## Business use cases * [Accounting](/connector-api/use-cases/accounting) * [Allowances](/connector-api/use-cases/allowances) * [Customer loyalty](/connector-api/use-cases/loyalty) * [Customer management](/connector-api/use-cases/customer-management) * [Events](/connector-api/use-cases/events) * [Guest technology](/connector-api/use-cases/guest-technology) * [Housekeeping](/connector-api/use-cases/housekeeping) * [Kiosk](/connector-api/use-cases/kiosk) * [Point of sale](/connector-api/use-cases/point-of-sale) * [Reputation management](/connector-api/use-cases/reputation-management) * [Revenue management](/connector-api/use-cases/revenue-management) * [Upsell](/connector-api/use-cases/upsell) ## Functional use cases * [Data export](/connector-api/use-cases/data-export) * [Device integration](/connector-api/use-cases/device-integration) * [Customer messaging](/connector-api/use-cases/messaging) * [Payments - Mews Payment Terminals](/connector-api/use-cases/mews-terminals) * [Payments - Payment automation](/connector-api/use-cases/payment-automation) # 'How to' use cases 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](/getting-started/glossary) to explain the particular terminology used in Mews. If you still can't find what you're looking for, [contact support](/connector-api/contact-support). ## Configuration | 'How to' use case | API Operations | Use cases | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | How to get enterprise or property configuration | [Get configuration](/connector-api/operations/configuration#get-configuration) | [Events](/connector-api/use-cases/events), [Kiosk](/connector-api/use-cases/kiosk) | | How to get the list of supported countries | [Get all countries](/connector-api/operations/countries#get-all-countries) | [Events](/connector-api/use-cases/events) | | How to get the list of supported currencies | [Get all currencies](/connector-api/operations/currencies#get-all-currencies) | [Events](/connector-api/use-cases/events) | | How to get the list of supported languages | [Get all languages](/connector-api/operations/languages#get-all-languages) | [Events](/connector-api/use-cases/events), [Kiosk](/connector-api/use-cases/kiosk) | | How to get applicable tax rates | [Get all tax environments](/connector-api/operations/taxenvironments#get-all-tax-environments), [Get all taxations](/connector-api/operations/taxations#get-all-taxations) | [Events](/connector-api/use-cases/events) | | How to get editable history window | [Get configuration](/connector-api/operations/configuration#get-configuration) | [Accounting](/connector-api/use-cases/accounting) | ## Finance | 'How to' use case | API Operations | Use cases | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | How to get configured accounting categories | [Get all accounting categories](/connector-api/operations/accountingcategories#get-all-accounting-categories) | [Accounting](/connector-api/use-cases/accounting), [Events](/connector-api/use-cases/events), [Point of sale](/connector-api/use-cases/point-of-sale) | | How to get the list of accounting categories | [Get all accounting categories](/connector-api/operations/accountingcategories#get-all-accounting-categories) | [Upsell](/connector-api/use-cases/upsell), [Guest technology](/connector-api/use-cases/guest-technology), [Kiosk](/connector-api/use-cases/kiosk) | | How to add accounting items to a bill | [Update accounting items](https://github.com/MewsSystems/open-api-docs/tree/main/connector-api/operations/finance.md#update-accounting-items) | [Events](/connector-api/use-cases/events) | | How to move bill items to a new bill | [Update accounting items](/connector-api/operations/accountingitems#update-accounting-items) | [Kiosk](/connector-api/use-cases/kiosk) | | How to get accounting items consumed over a period | [Get all payments](/connector-api/operations/payments#get-all-payments), [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | [Accounting](/connector-api/use-cases/accounting) | | How to get payment items paid over a period | [Get all payments](/connector-api/operations/payments#get-all-payments) | [Accounting](/connector-api/use-cases/accounting) | | How to get order items consumed over a period | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | [Accounting](/connector-api/use-cases/accounting) | | How to get a list of revenue items for a reservation | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | [Accounting](/connector-api/use-cases/accounting) | | How to get order items linked to a reservation | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | [Revenue management](/connector-api/use-cases/revenue-management) | | How to find the original order item for a rebate item | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | [Accounting](/connector-api/use-cases/accounting) | | How to get outlet items consumed over a period | [Get all outlet items](/connector-api/operations/outletitems#get-all-outlet-items) | [Accounting](/connector-api/use-cases/accounting) | | How to get bills and invoices | [Get all bills](/connector-api/operations/bills#get-all-bills) | [Accounting](/connector-api/use-cases/accounting) | | How to get the customer or guest bill | [Get all bills](/connector-api/operations/bills#get-all-bills) | [Kiosk](/connector-api/use-cases/kiosk) | | How to create a new bill | [Add bill](https://github.com/MewsSystems/open-api-docs/tree/main/connector-api/operations/finance.md#add-bill) | [Events](/connector-api/use-cases/events), [Kiosk](/connector-api/use-cases/kiosk) | | How to close a bill against change | [Close bill](https://github.com/MewsSystems/open-api-docs/tree/main/connector-api/operations/finance.md#close-bill) | [Events](/connector-api/use-cases/events), [Kiosk](/connector-api/use-cases/kiosk) | | How to get a printable bill | [Get bill PDF](/connector-api/operations/bills#close-bill) | [Kiosk](/connector-api/use-cases/kiosk) | | How to charge a guest credit card using Mews Payments | [Charge credit card](/connector-api/operations/creditcards#charge-credit-card) | [Kiosk](/connector-api/use-cases/kiosk), [Payment automation](/connector-api/use-cases/payment-automation) | | How to add a credit card to the guest profile | [Add tokenized credit card](/connector-api/operations/creditcards#add-tokenized-credit-card) | [Kiosk](/connector-api/use-cases/kiosk) | | How to get details of stored credit cards | [Get all credit cards](/connector-api/operations/creditcards#get-all-credit-cards) | [Kiosk](/connector-api/use-cases/kiosk), [Payment automation](/connector-api/use-cases/payment-automation) | | How to check if a credit card is stored against a guest profile | [Get all credit cards](/connector-api/operations/creditcards#get-all-credit-cards) | [Kiosk](/connector-api/use-cases/kiosk), [Payment automation](/connector-api/use-cases/payment-automation) | | How to record a general external payment | [Add external payment](/connector-api/operations/payments#add-external-payment) | [Kiosk](/connector-api/use-cases/kiosk) | | How to record an alternative external payment | [Add alternative payment](/connector-api/operations/payments#add-alternative-payment) | [Kiosk](/connector-api/use-cases/kiosk) | | How to post end-of-day accounting items | [Add outlet bill](/connector-api/operations/outletbills#add-outlet-bills) | [Point of sale](/connector-api/use-cases/point-of-sale) | ## Allowances | 'How to' use case | API Operations | Use cases | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | How to get all order items for a reservation (including allowance items) | [`Get all order items`](/connector-api/operations/orderitems#get-all-order-items) (use `ServiceOrderIds`) | [Allowances](/connector-api/use-cases/allowances) | | How to get allowance discount items | [`Get all order items`](/connector-api/operations/orderitems#get-all-order-items) (use `Types` with `AllowanceDiscount`) | [Allowances](/connector-api/use-cases/allowances) | | How to get breakage items for reconciliation | [`Get all order items`](/connector-api/operations/orderitems#get-all-order-items) (use `Types` with `AllowanceBreakage` and `AllowanceContraBreakage`) | [Allowances](/connector-api/use-cases/allowances) | | How to get all allowance-related items on a bill | [`Get all order items`](/connector-api/operations/orderitems#get-all-order-items) (use `BillIds`) | [Allowances](/connector-api/use-cases/allowances) | | How to get allowance items over a period | [`Get all order items`](/connector-api/operations/orderitems#get-all-order-items) (use `ClosedUtc` or `ConsumedUtc`) | [Allowances](/connector-api/use-cases/allowances) | | How to identify allowance product items among order items | [`Get all order items`](/connector-api/operations/orderitems#get-all-order-items) (check `Data.Product.ProductType = Allowance`) | [Allowances](/connector-api/use-cases/allowances) | | How to find the original charge for an allowance discount | [`Get all order items`](/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `DiscountedOrderItemId`) | [Allowances](/connector-api/use-cases/allowances) | | How to find which allowance funded a discount | [`Get all order items`](/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId`) | [Allowances](/connector-api/use-cases/allowances) | | How to find which allowance generated a breakage item | [`Get all order items`](/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId` from breakage item's `Data`) | [Allowances](/connector-api/use-cases/allowances) | | How to post a charge that triggers an allowance discount | [`Add order`](/connector-api/operations/orders#add-order) | [Allowances](/connector-api/use-cases/allowances) | | How to post a custom item against an allowance | [`Add order`](/connector-api/operations/orders#add-order) (use `Items` with `AccountingCategoryId`) | [Allowances](/connector-api/use-cases/allowances) | | How to post an existing Mews product against an allowance | [`Add order`](/connector-api/operations/orders#add-order) (use `ProductOrders`) | [Allowances](/connector-api/use-cases/allowances) | ## Enterprises & Resources | 'How to' use case | API Operations | Use cases | | ------------------------------------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | How to get configured rooms and spaces | [Get all resources](/connector-api/operations/resources#get-all-resources) | [Point of sale](/connector-api/use-cases/point-of-sale), [Housekeeping](/connector-api/use-cases/housekeeping), [Events](/connector-api/use-cases/events) | | How to get resource categories or room types | [Get all resources](/connector-api/operations/resources#get-all-resources) | [Kiosk](/connector-api/use-cases/kiosk) | | How to update the state of a resource or room | [Update resources](/connector-api/operations/resources#update-resources) | [Housekeeping](/connector-api/use-cases/housekeeping) | | How to get resource blocks (out of order, etc.) | [Get all resource blocks](/connector-api/operations/resourceblocks#get-all-resource-blocks) | [Kiosk](/connector-api/use-cases/kiosk), [Housekeeping](/connector-api/use-cases/housekeeping) | | How to get information about out-of-order blocks | [Get all resource blocks](/connector-api/operations/resourceblocks#get-all-resource-blocks) | [Revenue management](/connector-api/use-cases/revenue-management) | | How to add a resource block | [Add resource block](/connector-api/operations/resourceblocks#add-resource-block) | [Housekeeping](/connector-api/use-cases/housekeeping) | | How to delete resource blocks | [Delete resource blocks](/connector-api/operations/resourceblocks#delete-resource-blocks) | [Housekeeping](/connector-api/use-cases/housekeeping) | | How to get the configured outlets | [Get all outlets](/connector-api/operations/outlets#get-all-outlets) | [Point of sale](/connector-api/use-cases/point-of-sale) | | How to get company profiles | [Get all companies](/connector-api/operations/companies#get-all-companies) | [Events](/connector-api/use-cases/events) | | How to find an existing company | [Get all companies](/connector-api/operations/companies#get-all-companies) | [Events](/connector-api/use-cases/events) | | How to add a new company | [Add company](/connector-api/operations/companies#add-company) | [Events](/connector-api/use-cases/events) | | How to get information about departments | [Get all departments](/connector-api/operations/departments#get-all-departments) | [Housekeeping](/connector-api/use-cases/housekeeping) | | How to get the list of staff tasks | [Get all tasks](/connector-api/operations/tasks#get-all-tasks) | [Housekeeping](/connector-api/use-cases/housekeeping) | | How to add a staff task | [Add task](/connector-api/operations/tasks#add-task) | [Housekeeping](/connector-api/use-cases/housekeeping) | | How to create staff reminders | [Add task](/connector-api/operations/tasks#add-task) | [Upsell](/connector-api/use-cases/upsell) | ## Customer Profiles | 'How to' use case | API Operations | Use cases | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | How to create a customer or guest profile | [Add customer](/connector-api/operations/customers#add-customer) | [Kiosk](/connector-api/use-cases/kiosk) | | How to update a customer or guest profile | [Update customer](/connector-api/operations/customers#update-customer) | [Kiosk](/connector-api/use-cases/kiosk), [Reputation management](/connector-api/use-cases/reputation-management) | | How to create a Paymaster profile | [Add customer](/connector-api/operations/customers#add-customer) | [Events](/connector-api/use-cases/events) | | How to update a profile to be a Paymaster | [Update customer](/connector-api/operations/customers#update-customer) | [Events](/connector-api/use-cases/events) | | How to remove the Paymaster classification | [Update customer](/connector-api/operations/customers#update-customer) | [Events](/connector-api/use-cases/events) | | How to get a list of profiles created over a period of time | [Get all customers](/connector-api/operations/customers#get-all-customers) | [Events](/connector-api/use-cases/events) | | How to get checked in and checked out guests | [Get all customers](/connector-api/operations/customers#get-all-customers) | [Upsell](/connector-api/use-cases/upsell) | | How to search for a customer or guest | [Search customers](/connector-api/operations/customers#search-customers) | [Point of sale](/connector-api/use-cases/point-of-sale) | | How to get only checked in guests | [Search customers](/connector-api/operations/customers#search-customers) | [Upsell](/connector-api/use-cases/upsell) | | How to review already posted items | [Get all payments](/connector-api/operations/payments#get-all-payments), [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | [Events](/connector-api/use-cases/events) | | How to get the list of open revenue items for a guest | [Get all payments](/connector-api/operations/payments#get-all-payments), [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | [Kiosk](/connector-api/use-cases/kiosk) | ## Reservations | 'How to' use case | API Operations | Use cases | | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | How to listen for changes to reservations | [General Webhooks](/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](/connector-api/events/websockets) (`Reservation` event) | [Guest technology](/connector-api/use-cases/guest-technology), [Customer management](/connector-api/use-cases/customer-management), [Housekeeping](/connector-api/use-cases/housekeeping), [Reputation management](/connector-api/use-cases/reputation-management), [Revenue management](/connector-api/use-cases/revenue-management), [Events](/connector-api/use-cases/events) | | How to get reservation and customer details | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | [Guest technology](/connector-api/use-cases/guest-technology), [Customer management](/connector-api/use-cases/customer-management), [Housekeeping](/connector-api/use-cases/housekeeping) | | How to get reservation details | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | [Revenue management](/connector-api/use-cases/revenue-management) | | How to get reservations updated over a time period | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | [Customer management](/connector-api/use-cases/customer-management) | | How to look up a guest reservation | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | [Kiosk](/connector-api/use-cases/kiosk) | | How to get checked-out reservations | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | [Reputation management](/connector-api/use-cases/reputation-management) | | How to get historical reservations data | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | [Revenue management](/connector-api/use-cases/revenue-management) | | How to get a specific reservation | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | [Upsell](/connector-api/use-cases/upsell) | | How to update the details of a reservation | [Update reservations](/connector-api/operations/reservations#update-reservations) | [Kiosk](/connector-api/use-cases/kiosk) | | How to add a guest to a reservation | [Add reservation companion](/connector-api/operations/reservations#add-reservation-companion) | [Kiosk](/connector-api/use-cases/kiosk), [Events](/connector-api/use-cases/events) | | How to remove a guest from a reservation | [Delete reservation companion](/connector-api/operations/reservations#delete-reservation-companion) | [Kiosk](/connector-api/use-cases/kiosk), [Events](/connector-api/use-cases/events) | | How to change the reservation owner | [Update reservation customer](/connector-api/operations/reservations#update-reservation-customer) | [Kiosk](/connector-api/use-cases/kiosk) | | How to modify the date or time of a reservation | [Update reservation interval](/connector-api/operations/reservations#update-reservation-interval) | [Kiosk](/connector-api/use-cases/kiosk) | | How to check in a guest reservation | [Start reservation](/connector-api/operations/reservations#start-reservation) | [Kiosk](/connector-api/use-cases/kiosk) | | How to check out a guest reservation | [Process reservation](/connector-api/operations/reservations#process-reservation) | [Kiosk](/connector-api/use-cases/kiosk) | | How to add a product to a reservation | [Add reservation product](/connector-api/operations/reservations#add-reservation-product) | [Kiosk](/connector-api/use-cases/kiosk) | | How to add a product order to a reservation | [Add reservation product](/connector-api/operations/reservations#add-reservation-product) | [Upsell](/connector-api/use-cases/upsell) | | How to push a reservation to Mews | [Add reservations](/connector-api/operations/reservations#add-reservations) | [Events](/connector-api/use-cases/events) | | How to make a new booking | [Add reservations](/connector-api/operations/reservations#add-reservations) | [Kiosk](/connector-api/use-cases/kiosk) | | How to place an existing reservation into an availability block | [Update reservations](/connector-api/operations/reservations#update-reservations) | [Events](/connector-api/use-cases/events) | | How to remove a reservation from an availability block | [Update reservation](/connector-api/operations/reservations#update-reservations) | [Events](/connector-api/use-cases/events) | | How to price a specific reservation | [Price reservations](/connector-api/operations/reservations#price-reservations) | [Kiosk](/connector-api/use-cases/kiosk) | ## Data Export | 'How to' use case | API Operations | Use cases | | ------------------------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | How to create a bulk data export | [Add export](/connector-api/operations/exports#add-export) | [Data export](/connector-api/use-cases/data-export), [Revenue management](/connector-api/use-cases/revenue-management) | | How to check on data export progress | [Get all exports](/connector-api/operations/exports#get-all-exports) | [Data export](/connector-api/use-cases/data-export), [Revenue management](/connector-api/use-cases/revenue-management) | ## Services & Products | 'How to' use case | API Operations | Use cases | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | How to get the list of property services | [Get all services](/connector-api/operations/services#get-all-services) | [Guest technology](/connector-api/use-cases/guest-technology) | | How to get the list of services offered | [Get all services](/connector-api/operations/services#get-all-services) | [Events](/connector-api/use-cases/events), [Upsell](/connector-api/use-cases/upsell), [Point of sale](/connector-api/use-cases/point-of-sale) | | How to get the list of products linked to services | [Get all products](/connector-api/operations/products#get-all-products) | [Events](/connector-api/use-cases/events), [Upsell](/connector-api/use-cases/upsell) | | How to get the list of available products | [Get all products](/connector-api/operations/products#get-all-products) | [Events](/connector-api/use-cases/events) | | How to get configured rates | [Get all rates](/connector-api/operations/rates#get-all-rates) | [Revenue management](/connector-api/use-cases/revenue-management), [Kiosk](/connector-api/use-cases/kiosk), [Events](/connector-api/use-cases/events) | | How to get configured rate groups | [Get all rate groups](/connector-api/operations/rates#get-all-rate-groups) | [Revenue management](/connector-api/use-cases/revenue-management) | | How to get rate pricing | [Get rate pricing](/connector-api/operations/rates#get-rate-pricing) | [Kiosk](/connector-api/use-cases/kiosk) | | How to get the price for a given rate | [Get rate pricing](/connector-api/operations/rates#get-rate-pricing) | [Events](/connector-api/use-cases/events) | | How to get the price for a specific rate and time period | [Get rate pricing](/connector-api/operations/rates#get-rate-pricing) | [Revenue management](/connector-api/use-cases/revenue-management) | | How to listen for changes to rate prices | [WebSockets](/connector-api/events/websockets) (`PriceUpdate` event) | [Revenue management](/connector-api/use-cases/revenue-management) | | How to get rate package rules | [Get all rules](/connector-api/operations/rules#get-all-rules) | [Kiosk](/connector-api/use-cases/kiosk) | | How to get all configured business segments | [Get all business segments](/connector-api/operations/businesssegments#get-all-business-segments) | [Revenue management](/connector-api/use-cases/revenue-management) | | How to get service restrictions | [Get all restrictions](/connector-api/operations/restrictions#get-all-restrictions) | [Revenue management](/connector-api/use-cases/revenue-management) | | How to add or remove restrictions | [Set restrictions](/connector-api/operations/restrictions#set-restrictions), [Clear restrictions](/connector-api/operations/restrictions#clear-restrictions) | [Revenue management](/connector-api/use-cases/revenue-management) | | How to get availability | [Get service availability](/connector-api/operations/services#get-service-availability) | [Events](/connector-api/use-cases/events), [Kiosk](/connector-api/use-cases/kiosk) | | How to get room or resource availability | [Get service availability](/connector-api/operations/services#get-service-availability) | [Upsell](/connector-api/use-cases/upsell) | | How to update or amend service availability | [Update service availability](/connector-api/operations/services#update-service-availability) | [Events](/connector-api/use-cases/events) | | How to post an order for a guest | [Add order](/connector-api/operations/orders#add-order) | [Kiosk](/connector-api/use-cases/kiosk) | | How to post an order item to a guest profile | [Add order](/connector-api/operations/orders#add-order) | [Guest technology](/connector-api/use-cases/guest-technology) | | How to add a product order item to a customer profile | [Add order](/connector-api/operations/orders#add-order) | [Events](/connector-api/use-cases/events) | | How to add a product order to a guest profile | [Add order](/connector-api/operations/orders#add-order) | [Upsell](/connector-api/use-cases/upsell) | | How to post a charge to a customer profile | [Add order](/connector-api/operations/orders#add-order) | [Point of sale](/connector-api/use-cases/point-of-sale) | | How to link an order to a reservation | [Add order](/connector-api/operations/orders#add-order) (use `LinkedReservationId`) | [Events](/connector-api/use-cases/events), [Kiosk](/connector-api/use-cases/kiosk), [Guest technology](/connector-api/use-cases/guest-technology), [Upsell](/connector-api/use-cases/upsell), [Point of sale](/connector-api/use-cases/point-of-sale), [Allowances](/connector-api/use-cases/allowances) | ## Availability Blocks | 'How to' use case | API Operations | Use cases | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------- | | How to create an availability block | [Add availability blocks](/connector-api/operations/availabilityblocks#add-availability-blocks) | [Events](/connector-api/use-cases/events) | | How to get existing availability blocks | [Get all availability blocks](/connector-api/operations/availabilityblocks#get-all-availability-blocks) | [Events](/connector-api/use-cases/events) | | How to delete an availability block | [Delete availability blocks](/connector-api/operations/availabilityblocks#delete-availability-blocks) | [Events](/connector-api/use-cases/events) | | How to place an existing reservation into an availability block | [Update reservations](/connector-api/operations/reservations#update-reservations) | [Events](/connector-api/use-cases/events) | | How to remove a reservation from an availability block | [Update reservation](/connector-api/operations/reservations#update-reservations) | [Events](/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). ## Customer Loyalty | 'How to' use case | API Operations | Use cases | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | How to add a Loyalty Program | [Add loyalty programs](/connector-api/operations/loyaltyprograms#add-loyalty-programs) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to get a list of Loyalty Programs | [Get all loyalty programs](/connector-api/operations/loyaltyprograms#get-all-loyalty-programs) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to get the Chain identifier for a property | [Get configuration](/connector-api/operations/configuration#get-configuration) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to update a Loyalty Program | [Update loyalty programs](/connector-api/operations/loyaltyprograms#update-loyalty-programs) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to delete a Loyalty Program | [Delete loyalty programs](/connector-api/operations/loyaltyprograms#delete-loyalty-programs) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to add a Loyalty Tier | [Add loyalty tiers](/connector-api/operations/loyaltytiers#add-loyalty-tiers) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to get a list of Loyalty Tiers | [Get all loyalty tiers](/connector-api/operations/loyaltytiers#get-all-loyalty-tiers) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to update a Loyalty Tier | [Update loyalty tiers](/connector-api/operations/loyaltytiers#update-loyalty-tiers) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to delete a Loyalty Tier | [Delete loyalty tiers](/connector-api/operations/loyaltytiers#delete-loyalty-tiers) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to add a Loyalty Membership | [Add loyalty memberships](/connector-api/operations/loyaltymemberships#add-loyalty-memberships) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to get a list of Loyalty Memberships | [Get all loyalty memberships](/connector-api/operations/loyaltymemberships#get-all-loyalty-memberships) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to update a Loyalty Membership | [Update loyalty memberships](/connector-api/operations/loyaltymemberships#update-loyalty-memberships) | [Customer loyalty](/connector-api/use-cases/loyalty) | | How to delete a Loyalty Membership | [Delete loyalty memberships](/connector-api/operations/loyaltymemberships#delete-loyalty-memberships) | [Customer loyalty](/connector-api/use-cases/loyalty) | ## Customer Messaging | 'How to' use case | API Operations | Use cases | | -------------------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | How to get your message threads | [Get all message threads](/connector-api/operations/messagethreads#get-all-message-threads) | [Customer messaging](/connector-api/use-cases/messaging) | | How to get messages for your message threads | [Get all messages](/connector-api/operations/messages#get-all-messages) | [Customer messaging](/connector-api/use-cases/messaging) | | How to create a new message thread | [Add message thread](/connector-api/operations/messagethreads#add-message-thread) | [Customer messaging](/connector-api/use-cases/messaging) | | How to create a new message within a thread | [Add messages](/connector-api/operations/messages#add-messages) | [Customer messaging](/connector-api/use-cases/messaging) | | How to listen for new customer messages | [General Webhooks](/connector-api/events/wh-general) (`MessageAdded` event) | [Customer messaging](/connector-api/use-cases/messaging) | ## Device Commands | 'How to' use case | API Operations | Use cases | | ------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | How to listen for new device commands | [WebSockets](/connector-api/events/websockets) | [Device integration](/connector-api/use-cases/device-integration) | | How to get details of a device command | [Get all commands by ids](/connector-api/operations/commands#get-all-commands-by-ids) | [Device integration](/connector-api/use-cases/device-integration) | | How to get all unprocessed device commands | [Get all commands](/connector-api/operations/commands#get-all-commands) | [Device integration](/connector-api/use-cases/device-integration) | | How to update the state of a device command | [Update command](/connector-api/operations/commands#update-command) | [Device integration](/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](/connector-api/use-cases/device-integration) use case. # Accounting 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. ## 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](/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](/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](/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](/getting-started/glossary). > **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). ## 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](/connector-api/operations/payments#get-all-payments), [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | | How to get order items consumed over a period | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | | How to get payment items paid over a period | [Get all payments](/connector-api/operations/payments#get-all-payments) | | How to get outlet items consumed over a period | [Get all outlet items](/connector-api/operations/outletitems#get-all-outlet-items) | | How to get bills and invoices | [Get all bills](/connector-api/operations/bills#get-all-bills) | ## 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](/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](/connector-api/operations/orderitems#get-all-order-items) | > **Accounting item states**: Accounting items will always be assigned one of four [accounting item states](/connector-api/operations/accountingitems#accounting-item-state) (`Open`, `Closed`, `Inactive`, `Canceled`). ## 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](/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](/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](/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](/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. ## Testing your integration Please follow our general [Usage guidelines](/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. ## 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) # Allowances ## Overview An Allowance is a packaged spending benefit that a Property attaches to a Rate, giving guests a defined amount they can redeem against specified on-property services — for example, food & beverage, spa, or minibar charges. Rather than discounting the room Rate, the Property adds value while protecting its Average Daily Rate (ADR). From an accounting perspective, the allowance represents a liability the Property assumes at activation: the Property has committed to absorbing qualifying charges on the guest's behalf, up to the specified amount. When an allowance is activated for a Reservation, the system posts an allowance product order item (a `ProductOrder` with `ProductType = Allowance`) to the guest's Bill. When a qualifying charge is subsequently posted — one whose Accounting Category matches the allowance's permitted consumption categories — the system automatically creates an `AllowanceDiscount` order item that offsets the charge up to the remaining allowance balance. Any unspent allowance is retained by the Property as additional revenue, which is known as Breakage. Integrations — such as point-of-sale (POS) systems, accounting systems, and kiosk or self-service applications — can use the **Mews Connector API** to: * post charges that are automatically offset against a guest's allowance * retrieve allowance-related order items for billing, reconciliation, and balance reporting ## Key concepts There are several types of order item specific to allowances. Understanding these is essential for working with allowance data through the API. ### Allowance-related order item types | Order item type | What it represents | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `ProductOrder` (with `ProductType = Allowance`) | The allowance product — the liability posted to the guest's bill when the allowance is activated. | | `AllowanceDiscount` | A discount automatically applied to a qualifying charge, offsetting the charge up to the remaining allowance balance. | | `AllowanceBreakage` | Unspent allowance retained by the Property as revenue at checkout. See Breakage. | | `AllowanceContraBreakage` | The accounting contra entry for breakage, ensuring double-entry accounting integrity. | ### Automatic discounting When a charge is posted to a guest who has an active allowance, and the charge's accounting category matches the allowance's permitted consumption categories, the system automatically creates an `AllowanceDiscount` item to offset the charge. {% hint style="info" %} No additional API call is needed to trigger the discount. {% endhint %} ## Retrieving allowance-related order items Use [Get all order items](/connector-api/operations/orderitems#get-all-order-items) to retrieve order items related to allowances. You can filter: * by reservation using `ServiceOrderIds` * by bill using `BillIds` * by time period using, for example, `CreatedUtc`, `UpdatedUtc`, or `ClosedUtc` * by item type using `Types` ### "How to" use cases (retrieving items) | "How to" use case | API operations | | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | How to get all order items for a reservation (including allowance items) | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) (use `ServiceOrderIds`) | | How to get allowance discount items | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) (use `Types` filter with `AllowanceDiscount`) | | How to get breakage items | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) (use `Types` filter with `AllowanceBreakage` and `AllowanceContraBreakage`) | | How to get all allowance-related items on a bill | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) (use `BillIds`) | | How to get allowance items over a period | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) (use `ClosedUtc` or `ConsumedUtc`) | ## Identifying allowance products To identify whether an order item is an allowance product (as opposed to a regular product), check the item's `Data` field. An order item with: * `Data.Discriminator` set to `Product`, and * `Data.Product.ProductType` set to `Allowance` is an **allowance product** — the allowance amount itself, as opposed to a charge or discount. ### "How to" use cases (identifying products) | "How to" use case | API operations | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | How to identify allowance product items among order items | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) (check `Data.Product.ProductType = Allowance`) | ## Working with allowance discounts When you retrieve order items of type `AllowanceDiscount`, the item's `Data` field contains additional information that links the discount back to both: * the original charge * the allowance product that funded it Specifically, an [Order item](/connector-api/operations/orderitems#order-item) with `Data.Discriminator` set to `AllowanceDiscount` will have: * `DiscountedOrderItemId` — the unique identifier of the original charge item that was discounted. * `AllowanceProductOrderItemId` — the unique identifier of the allowance product order item which consumed the item. You can use [Get all order items](/connector-api/operations/orderitems#get-all-order-items) with the `OrderItemIds` filter to fetch the details of either: * the original charge, or * the allowance product. ### "How to" use cases (discount links) | "How to" use case | API operations | | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | How to find the original charge for an allowance discount | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `DiscountedOrderItemId`) | | How to find which allowance funded a discount | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId`) | {% hint style="info" %} Discount amounts are negative. An `AllowanceDiscount` order item carries a negative `Amount`, which offsets the positive amount of the original charge on the guest's bill. {% endhint %} ## Working with breakage and profits When a guest checks out or an allowance expires, the system generates profit-related items. The most common case is breakage, where unspent allowance is retained by the Property as revenue. In other accounting scenarios, the system may instead generate loss entries (`AllowanceLoss`, `AllowanceContraLoss`). An [Order item](/connector-api/operations/orderitems#order-item) with `Data.Discriminator` set to `AllowanceProfits` will have: * `AllowanceProductOrderItemId` — the unique identifier of the allowance product whose amount was not fully consumed. * `AllowanceProfitType` — the type of profit entry, which can be one of: * `AllowanceBreakage` — the profit from unspent allowance amount. * `AllowanceContraBreakage` — the accounting balance entry for the breakage. * `AllowanceLoss` — the loss from the allowance product. * `AllowanceContraLoss` — the accounting balance entry for the loss. ### "How to" use cases (breakage and profits) | "How to" use case | API operations | | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | How to get breakage items for reconciliation | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) (use `Types` with `AllowanceBreakage` and `AllowanceContraBreakage`) | | How to find which allowance generated a breakage item | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) (use `OrderItemIds` with `AllowanceProductOrderItemId` from the breakage item's `Data`) | {% hint style="info" %} Breakage and contra-breakage always occur in pairs. For every `AllowanceBreakage` item, there is a corresponding `AllowanceContraBreakage` item to maintain double-entry accounting balance. Accounting integrations should expect and reconcile both. {% endhint %} ## Posting charges against an allowance External systems such as POS integrations can post charges to a guest's profile using [Add order](/connector-api/operations/orders#add-order). If the guest has an active allowance and the charge falls within the allowance's permitted consumption categories (matched by `AccountingCategoryId`), the system will automatically generate an `AllowanceDiscount` order item that offsets the charge — up to the remaining allowance balance. Both `ProductOrders` (for products already configured in Mews) and `Items` (for custom items not configured in Mews) are supported. In both cases, the `AccountingCategoryId` on the item determines whether the charge qualifies for allowance discounting. ### Linking orders to reservations Specify parameter `LinkedReservationId` when using [Add order](/connector-api/operations/orders#add-order) to link the order to the guest's reservation. This is especially important for allowances because it ensures the charge and the resulting allowance discount are associated with the correct reservation and its billing automation rules. ### "How to" use cases (posting charges) | "How to" use case | API operations | | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | How to post a charge that triggers an allowance discount | [Add order](/connector-api/operations/orders#add-order) | | How to post a custom item against an allowance | [Add order](/connector-api/operations/orders#add-order) (use `Items` with `AccountingCategoryId`) | | How to post an existing Mews product against an allowance | [Add order](/connector-api/operations/orders#add-order) (use `ProductOrders`) | ## Partial consumption If the charge amount exceeds the remaining allowance balance, the discount is applied only up to the remaining balance. The guest is responsible for the remainder. For example, if a guest has €30 remaining on their F\&B allowance and a €45 dinner charge is posted, an `AllowanceDiscount` of €30 is created and the guest owes €15. ## Charges that do not qualify If the posted item's accounting category is not in the allowance's permitted consumption list, no discount is generated. The charge is posted normally to the guest's bill. ## Testing your integration Ensure you follow the general [Usage guidelines](/connector-api/guidelines) for testing integrations. When testing an integration that works with allowances, verify the following scenarios: * Post a charge with an accounting category that matches the allowance's permitted consumption — confirm an `AllowanceDiscount` item is automatically created. * Post a charge with an accounting category that does not match — confirm no discount is created. * Post a charge that exceeds the remaining allowance balance — confirm the discount is capped at the remaining balance. * Post a charge of amount 0 — confirm no discount is created. * Retrieve order items for a reservation and confirm you can identify all allowance-related item types (`AllowanceDiscount`, `AllowanceBreakage`, `AllowanceContraBreakage`). * Confirm that breakage items are created after checkout when allowance amount remains unspent. * Reconcile the sum of allowance product amount, discount amounts, and breakage amounts — they should balance to zero. To cross-check allowance financial data, you can use the [Accounting Report](https://help.mews.com/s/article/accounting-report?language=en_US) and the [Bills and Invoices Report](https://help.mews.com/s/article/bills-and-invoices-report?language=en_US) in **Mews Operations**. # Customer loyalty 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. > #### 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. ## 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. > #### Where can I obtain the Chain identifier? > > You can obtain the Chain identifier for an enterprise or property using [Get configuration](/connector-api/operations/configuration#get-configuration). ## Set up loyalty programs Use [Add loyalty programs](/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](https://github.com/MewsSystems/poc-open-api-docs/blob/main/connector-api/guidelines/multi-property.md), 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](/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](/connector-api/operations/loyaltyprograms#add-loyalty-programs) | | How to get a list of Loyalty Programs | [Get all loyalty programs](/connector-api/operations/loyaltyprograms#get-all-loyalty-programs) | | How to get the Chain identifier for a property | [Get configuration](/connector-api/operations/configuration#get-configuration) | > #### 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) ## Maintain your loyalty programs To make changes to existing loyalty programs, use [Update loyalty programs](/connector-api/operations/loyaltyprograms#update-loyalty-programs). To delete unwanted loyalty programs, use [Delete loyalty programs](/connector-api/operations/loyaltyprograms#delete-loyalty-programs). | 'How to' use case | API Operations | | ------------------------------- | -------------------------------------------------------------------------------------------- | | How to update a Loyalty Program | [Update loyalty programs](/connector-api/operations/loyaltyprograms#update-loyalty-programs) | | How to delete a Loyalty Program | [Delete loyalty programs](/connector-api/operations/loyaltyprograms#delete-loyalty-programs) | ## 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](/connector-api/operations/loyaltytiers#add-loyalty-tiers). To see what loyalty tiers are already set up, use [Get all loyalty tiers](/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](/connector-api/operations/loyaltytiers#update-loyalty-tiers). To delete unwanted loyalty tiers, use [Delete loyalty tiers](/connector-api/operations/loyaltytiers#delete-loyalty-tiers). | 'How to' use case | API Operations | | ---------------------------------- | ------------------------------------------------------------------------------------- | | How to add a Loyalty Tier | [Add loyalty tiers](/connector-api/operations/loyaltytiers#add-loyalty-tiers) | | How to get a list of Loyalty Tiers | [Get all loyalty tiers](/connector-api/operations/loyaltytiers#get-all-loyalty-tiers) | | How to update a Loyalty Tier | [Update loyalty tiers](/connector-api/operations/loyaltytiers#update-loyalty-tiers) | | How to delete a Loyalty Tier | [Delete loyalty tiers](/connector-api/operations/loyaltytiers#delete-loyalty-tiers) | ## 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](/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](/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](/connector-api/operations/loyaltymemberships#add-loyalty-memberships) | | How to get a list of Loyalty Memberships | [Get all loyalty memberships](/connector-api/operations/loyaltymemberships#get-all-loyalty-memberships) | ## Maintain your guest memberships To make changes to guest loyalty memberships, use [Update loyalty memberships](/connector-api/operations/loyaltymemberships#update-loyalty-memberships). To remove guest loyalty memberships, use [Delete loyalty memberships](/connector-api/operations/loyaltymemberships#delete-loyalty-memberships). | 'How to' use case | API Operations | | ---------------------------------- | ----------------------------------------------------------------------------------------------------- | | How to update a Loyalty Membership | [Update loyalty memberships](/connector-api/operations/loyaltymemberships#update-loyalty-memberships) | | How to delete a Loyalty Membership | [Delete loyalty memberships](/connector-api/operations/loyaltymemberships#delete-loyalty-memberships) | ## Testing your integration Ensure you follow our general [Usage guidelines](/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) # Customer management 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. ## 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](/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](/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](/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](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) with specified [Reservation states](/connector-api/operations/reservations#reservation-state) and [Reservation time filters](/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](/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](/connector-api/events/websockets) (`Reservation` event) | | How to get reservation and customer details | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | | How to get reservations updated over a time period | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | ## 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](/connector-api/use-cases/upsell) use case. ## Testing your integration Please ensure you follow our general [Usage guidelines](/connector-api/guidelines) for testing integrations. ## 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) # Customer messaging 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](/connector-api/operations#messages) collection of API operations, in conjunction with the `MessageAdded` [General Webhook](/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](#1-customer-creates-a-message-within-your-app) 2. [Your app creates a new message thread in Mews](#2-your-app-creates-a-new-message-thread-in-mews) 3. [Your app listens for MessageAdded events](#3-your-app-listens-for-messageadded-events) 4. [Continue the conversation!](#4-continue-the-conversation) ## 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"` ## 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](/connector-api/operations/messagethreads#add-message-thread) to create a new message thread, then [Add messages](/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](/connector-api/operations/messagethreads#add-message-thread) | | How to create a new message within a thread | [Add messages](/connector-api/operations/messages#add-messages) | ## 3. Your app listens for MessageAdded events To get message responses in near real time, listen to the `MessageAdded` [General Webhook](/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](/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](/connector-api/events/wh-general) (`MessageAdded` event) | > **Property:** `"Hello Ms Penelope! Thank you for contacting us. What time do you expect to arrive?"` ## 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](/connector-api/operations/messages#get-all-messages) and [Get all message threads](/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](/connector-api/operations/messages#get-all-messages) | | How to get your message threads | [Get all message threads](/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."` ## Testing your integration Please refer to our general [Usage guidelines](/connector-api/guidelines) for testing integrations. ## 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) # Data export 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](/connector-api/operations/orderitems#order-item), without the hassle of making multiple paginated requests subject to timeouts and other constraints. ### 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 ### 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 > #### Restricted! > > This feature is currently under beta test and is subject to change. If you would like to take advantage of the feature, please [contact support](/connector-api/contact-support). ## Initiate the export To initiate a bulk data export, use the [Add export](/connector-api/operations/exports#add-export) operation, specifying the data *Entity type*, e.g. `OrderItem`. The operation returns an [Export](/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](/connector-api/operations/exports#add-export) | ## Check export status To monitor the progress of the export and retrieve the exported data, use the [Get all exports](/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](/connector-api/operations/exports#get-all-exports) | ## Download exported data Once the export status changes to `Success`, you can download the exported data from the provided [file URLs](/connector-api/operations/exports#exported-file). For example: ```javascript { "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. ## Frequently Asked Questions ### 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. ### 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. ### Can I export data from multiple enterprises in one request? Yes, you can use a [Portfolio Access Token](https://github.com/MewsSystems/poc-open-api-docs/blob/main/connector-api/guidelines/multi-property.md) to request data from multiple enterprises. Doing so will generate an export of data for all enterprises within scope of the Access Token. ### 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](/connector-api/operations/exports#export) object. # Device integration 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](/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/poc-open-api-docs/blob/main/connector-api/guidelines/communicate.md). | 'How to' use case | API Operations | | ------------------------------------- | ---------------------------------------------- | | How to listen for new device commands | [WebSockets](/connector-api/events/websockets) | ## 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](#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. ## Retrieving commands Using [WebSockets](/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](/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](/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](/connector-api/events/websockets) | | How to get details of a device command | [Get all commands by ids](/connector-api/operations/commands#get-all-commands-by-ids) | | How to get all unprocessed device commands | [Get all commands](/connector-api/operations/commands#get-all-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](/connector-api/operations/commands#update-command). | 'How to' use case | API Operations | | ------------------------------------------- | ------------------------------------------------------------------- | | How to update the state of a device command | [Update command](/connector-api/operations/commands#update-command) | ## Types of device command The [device command data](/connector-api/operations/commands#command-data) depends on the [device type](/connector-api/operations/devices#device-type). Mews supports several device types, including Printer, Payment Terminal, Passport Scanner, Fiscal Machine, and Key Cutter. ### Fiscal Machine commands For Fiscal Machines (whether a virtual or a physical one), you will receive a command containing [Fiscal machine command data](/connector-api/operations/commands#fiscal-machine-command-data). This includes all data of the related [Bill](/connector-api/operations/bills#bill), including all the payments and revenue items in the form of an [Accounting item](/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. ### Key Cutter commands For Key Cutters, you will receive a command containing [Key cutter command data](/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. ## Testing your integration Ensure you follow our general [Usage guidelines](/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. # Events 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. ## Enterprise information To automate the onboarding of a new property as much as possible, use a combination of [Configuration](/connector-api/operations#configuration) operations, [Enterprises](/connector-api/operations#enterprises) operations and [Services](/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](/connector-api/operations/configuration#get-configuration) | | How to get rooms and resources configuration | [Get all resources](/connector-api/operations/resources#get-all-resources) | | How to get applicable tax rates | [Get all tax environments](/connector-api/operations/taxenvironments#get-all-tax-environments), [Get all taxations](/connector-api/operations/taxations#get-all-taxations) | | How to get the list of services offered | [Get all services](/connector-api/operations/services#get-all-services) | | How to get the list of products linked to services | [Get all products](/connector-api/operations/products#get-all-products) | | How to get company profiles | [Get all companies](/connector-api/operations/companies#get-all-companies) | | How to get the list of supported countries | [Get all countries](/connector-api/operations/countries#get-all-countries) | | How to get the list of supported currencies | [Get all currencies](/connector-api/operations/currencies#get-all-currencies) | | How to get the list of supported languages | [Get all languages](/connector-api/operations/languages#get-all-languages) | ## Rates and availability Use [Get all rates](/connector-api/operations/rates#get-all-rates) and [Get rate pricing](/connector-api/operations/rates#get-rate-pricing) to pull data about rates offered in the property or enterprise. Use [Get service availability](/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](/connector-api/operations/rates#get-all-rates) | | How to get the price for a given rate | [Get rate pricing](/connector-api/operations/rates#get-rate-pricing) | | How to get availability | [Get service availability](/connector-api/operations/services#get-service-availability) | > **Availability blocks:** The `Availabilities` array returned by [Get service availability](/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. ## 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](/connector-api/operations/companies#add-company) or find an existing company via [Get all companies](/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](/connector-api/operations/companies#add-company) | | How to find an existing company | [Get all companies](/connector-api/operations/companies#get-all-companies) | ### Paymaster accounts Use a [Paymaster](/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](/connector-api/operations/customers#add-customer) to create a profile. > **Mews tip:** Make sure that only active [Paymaster](/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](/connector-api/operations/customers#customer-classification) classification when the event management system starts posting charges to the customer profile. Use [Update customer](/connector-api/operations/customers#update-customer) to mark the profile as a [Paymaster](/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](/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](/connector-api/operations/customers#update-customer) operation to remove the [Paymaster](/connector-api/operations/customers#customer-classification) classification. Refer to the [Update values](/connector-api/guidelines/serialization#update-values) section on how to change or remove a value. You can also use [Update customer](/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](/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](/connector-api/operations/customers#add-customer) | | How to update a profile to be a Paymaster | [Update customer](/connector-api/operations/customers#update-customer) | | How to remove the Paymaster classification | [Update customer](/connector-api/operations/customers#update-customer) | | How to get a list of profiles created over a period of time | [Get all customers](/connector-api/operations/customers#get-all-customers) | ## 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](/connector-api/operations/orders#add-order). If the product item that is being posted already exists in Mews, use [Product order parameters](/connector-api/operations/orders#product-order-parameters). If the product is a custom item that does not exist in Mews then use [Item parameters](/connector-api/operations/orders#item-parameters). Note that in order to use [Product order parameters](/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](/connector-api/operations/products#get-all-products). To ensure correct reporting, all revenue items posted into Mews using [Item parameters](/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/open-api-docs/blob/main/connector-api/operations/finance.md#get-all-accounting-categories). > #### Linking orders to reservations > > When using [Add order](/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](/connector-api/operations/orders#add-order) | | How to get the list of available products | [Get all products](/connector-api/operations/products#get-all-products) | | How to get accounting categories | [Get all accounting categories](/connector-api/operations/accountingcategories#get-all-accounting-categories) | | How to link an order to a reservation | [Add order](/connector-api/operations/orders#add-order) (use `LinkedReservationId`) | ### Recording external payments In case payment was taken outside of Mews, or directly in the event management system, use [Finance operations](/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. ### Further automation possibilities Call [Get all payments](/connector-api/operations/payments#get-all-payments) and [Get all order items](/connector-api/operations/orderitems#get-all-order-items), filtered by the relevant customer account (e.g. using `AccountIds`), 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](/connector-api/operations/bills#add-bill) for a certain group of revenue and payment items. Use [Update accounting items](/connector-api/operations/accountingitems#update-accounting-items) to redirect these items to the relevant bill and then use [Close bill](/connector-api/operations/bills#close-bill) to finalise the financial document. | 'How to' use case | API Operations | | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | How to review already posted items | [Get all payments](/connector-api/operations/payments#get-all-payments), [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | | How to create a new bill | [Add bill](/connector-api/operations/bills#add-bill) | | How to add accounting items to a bill | [Update accounting items](/connector-api/operations/accountingitems#update-accounting-items) | | How to close a bill against change | [Close bill](/connector-api/operations/bills#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). ## 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. ### Creating availability blocks First call [Add availability blocks](/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](/connector-api/operations/availabilityblocks#add-availability-blocks) | ### 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](/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](/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](/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. ### 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](/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](/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](/connector-api/operations/reservations#update-reservations) operation, by including `AvailabilityBlockId` in the [reservations parameters](/connector-api/operations/reservations#reservation-parameters). If applicable, you can attach a company to a reservation when calling [Add reservations](/connector-api/operations/reservations#add-reservations) or [Update reservations](/connector-api/operations/reservations#update-reservations). | 'How to' use case | API Operations | | --------------------------------------------------------------- | --------------------------------------------------------------------------------- | | How to push a reservation to Mews | [Add reservations](/connector-api/operations/reservations#add-reservations) | | How to place an existing reservation into an availability block | [Update reservations](/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](/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](/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. ### 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](/connector-api/operations/reservations#add-reservation-companion) or [Delete reservation companion](/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](/connector-api/operations/reservations#add-reservation-companion) | | How to remove a guest from a reservation | [Delete reservation companion](/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](/getting-started/glossary). ### Managing availability block inventory and pickup Call [Get all availability blocks](/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](/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](/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](/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](/connector-api/operations/availabilityblocks#get-all-availability-blocks) | | How to listen for changes to reservations | [General Webhooks](/connector-api/events/wh-general) (`ServiceOrderUpdated` event) | | How to delete an availability block | [Delete availability blocks](/connector-api/operations/availabilityblocks#delete-availability-blocks) | | How to remove a reservation from an availability block | [Update reservation](/connector-api/operations/reservations#update-reservations) | ## Testing your integration Ensure you follow our general [Usage guidelines](/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. ## 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) # Guest technology 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. ## Setup Firstly, use [Get all services](/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](/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](/connector-api/operations/services#get-all-services) | | How to get the list of accounting categories | [Get all accounting categories](/connector-api/operations/accountingcategories#get-all-accounting-categories) | ## Checked-in status Guest technology integrations typically require information on changes to [reservation state](/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](/connector-api/events) or [WebSockets](/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/poc-open-api-docs/blob/main/connector-api/guidelines/communicate.md). Once a reservation update event is received, use the reservation ID in a [Get all reservations](/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](/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](/connector-api/events/websockets) (`Reservation` event) | | How to get reservation and customer details | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | ## 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](/connector-api/operations/orders#add-order) operation. When using [Add order](/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](/connector-api/operations/orders#add-order) | | How to link an order to a reservation | [Add order](/connector-api/operations/orders#add-order) (use `LinkedReservationId`) | ## Testing your integration Please ensure you follow our general [Usage guidelines](/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. ## 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) # Housekeeping 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. ## Initial configuration The integration must first retrieve all the resources the property has configured in Mews using [Get all resources](/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](/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](/getting-started/glossary). ## 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](/connector-api/events) or [WebSockets](/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/open-api-docs/blob/main/connector-api/guidelines/communicate.md). | 'How to' use case | API Operations | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | How to listen for changes to reservations | [General Webhooks](/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](/connector-api/events/websockets) (`Reservation` event) | | How to get reservation and customer details | [Get all reservations](/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](/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](/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](/connector-api/operations/resourceblocks#get-all-resource-blocks). Housekeeping integrations can also manage blocks through [Add resource block](/connector-api/operations/resourceblocks#add-resource-block) and [Delete resource blocks](/connector-api/operations/resourceblocks#delete-resource-blocks). | 'How to' use case | API Operations | | -------------------------------------------- | ------------------------------------------------------------------------------------------- | | How to get information about resource blocks | [Get all resource blocks](/connector-api/operations/resourceblocks#get-all-resource-blocks) | | How to add a resource block | [Add resource block](/connector-api/operations/resourceblocks#add-resource-block) | | How to delete resource blocks | [Delete resource blocks](/connector-api/operations/resourceblocks#delete-resource-blocks) | ## Staff tasks If you need to create a task directly in Mews, this can be done using [Add task](/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](/connector-api/operations/departments#get-all-departments). A list of existing tasks can be retrieved from Mews using [Get all tasks](/connector-api/operations/tasks#get-all-tasks). | 'How to' use case | API Operations | | ---------------------------------------- | -------------------------------------------------------------------------------- | | How to add a staff task | [Add task](/connector-api/operations/tasks#add-task) | | How to get information about departments | [Get all departments](/connector-api/operations/departments#get-all-departments) | | How to get the list of staff tasks | [Get all tasks](/connector-api/operations/tasks#get-all-tasks) | ## 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. ## Testing your integration Please ensure you follow our general [Usage guidelines](/connector-api/guidelines) for testing integrations. In addition to this, using the [demo environment](/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. ## 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) # Kiosk 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. {% hint style="info" %} ### 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. {% endhint %} ## 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](/connector-api/operations/configuration#get-configuration) | | How to get the list of supported languages | [Get all languages](/connector-api/operations/languages#get-all-languages) | | How to get the list of services and products | [Get all services](/connector-api/operations/services#get-all-services), [Get all products](/connector-api/operations/products#get-all-products) | ## Guest check-in To look up a guest reservation, use the general-purpose operation [Get all reservations](/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](/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](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | | How to check in a guest reservation | [Start reservation](/connector-api/operations/reservations#start-reservation) | ## Working with guest profiles If the guest doesn't have a Mews customer profile, you can add one with [Add customer](/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](/connector-api/operations/customers#update-customer). To relate a guest profile to a specific reservation, use [Add reservation companion](/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](/connector-api/operations/customers#add-customer) | | How to update a guest profile | [Update customer](/connector-api/operations/customers#update-customer) | | How to add a guest to a reservation | [Add reservation companion](/connector-api/operations/reservations#add-reservation-companion) | ## 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](/connector-api/operations/bills#get-all-bills) | | How to get a printable bill | [Get bill PDF](/connector-api/operations/bills#get-bill-pdf) | | How to get the list of open revenue items for a guest | [Get all payments](/connector-api/operations/payments#get-all-payments), [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | | How to create a new bill | [Add bill](/connector-api/operations/bills#add-bill) | | How to move bill items to a new bill | [Update accounting items](/connector-api/operations/accountingitems#update-accounting-items) | | How to close a bill against change | [Close bill](/connector-api/operations/bills#close-bill) | {% hint style="warning" %} ### 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. {% endhint %} ## Taking payments Once you have confirmed the outstanding balance, you have three options for handling customer payments to settle the bill: * [Gateway payments](#gateway-payments) * [Non-Mews terminal payments](#non-mews-terminal-payments) * [Mews terminal payments](#mews-terminal-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 by specifying 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](/connector-api/operations/creditcards#charge-credit-card) | | How to add a credit card to the guest profile | [Add tokenized credit card](/connector-api/operations/creditcards#add-tokenized-credit-card) | | How to get details of stored credit cards | [Get all credit cards](/connector-api/operations/creditcards#get-all-credit-cards) | ### Non-Mews terminal payments You can take an external payment from a guest outside of Mews. In this case, the payment 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 a general external payment | [Add external payment](/connector-api/operations/payments#add-external-payment) | | How to record an alternative external payment | [Add alternative payment](/connector-api/operations/payments#add-alternative-payment) | {% hint style="info" %} #### Adding external payments * Use [Add external payment](/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](/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. {% endhint %} ### Mews terminal payments We also support the option to connect to Mews payment terminals, for which see our detailed use case [Mews Payment Terminals](/connector-api/use-cases/mews-terminals). ## 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](/connector-api/operations/reservations#process-reservation) | ## Modifying reservations A number of API operations are available to support modifications to reservations. [Update reservations](/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](/connector-api/operations/reservations#delete-reservation-companion), or change the primary guest or owner of the reservation with [Update reservation customer](/connector-api/operations/reservations#update-reservation-customer). To add additional products to a reservation, use [Add reservation product](/connector-api/operations/reservations#add-reservation-product). To modify only the start and/or end of the reservation, use [Update reservation interval](/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](/connector-api/operations/orders#add-order). If using [Item parameters](/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](/connector-api/operations/accountingcategories#get-all-accounting-categories). {% hint style="info" %} ### Linking orders to reservations When using [Add order](/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. {% endhint %} | 'How to' use case | API Operations | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | How to update the details of a reservation | [Update reservations](/connector-api/operations/reservations#update-reservations) | | How to remove an additional guest from a reservation | [Delete reservation companion](/connector-api/operations/reservations#delete-reservation-companion) | | How to change the reservation owner | [Update reservation customer](/connector-api/operations/reservations#update-reservation-customer) | | How to add a product to a reservation | [Add reservation product](/connector-api/operations/reservations#add-reservation-product) | | How to modify the date or time of a reservation | [Update reservation interval](/connector-api/operations/reservations#update-reservation-interval) | | How to post an order for a guest | [Add order](/connector-api/operations/orders#add-order) | | How to link an order to a reservation | [Add order](/connector-api/operations/orders#add-order) (use `LinkedReservationId`) | | How to get the list of accounting categories | [Get all accounting categories](/connector-api/operations/accountingcategories#get-all-accounting-categories) | ## 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](/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](/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](/connector-api/operations/resourceblocks#get-all-resource-blocks) to get this information. Use [Get all rates](/connector-api/operations/rates#get-all-rates) to retrieve all the rates configured at the property, and [Get rate pricing](/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](/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](/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](/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](#working-with-guest-profiles) above). | 'How to' use case | API Operations | | ----------------------------------------------- | ------------------------------------------------------------------------------------------- | | How to get resource categories (room types) | [Get all resources](/connector-api/operations/resources#get-all-resources) | | How to get availability | [Get service availability](/connector-api/operations/services#get-service-availability) | | How to get resource blocks (out of order, etc.) | [Get all resource blocks](/connector-api/operations/resourceblocks#get-all-resource-blocks) | | How to get configured rates | [Get all rates](/connector-api/operations/rates#get-all-rates) | | How to get rate pricing | [Get rate pricing](/connector-api/operations/rates#get-rate-pricing) | | How to price a specific reservation | [Price reservations](/connector-api/operations/reservations#price-reservations) | | How to get rate package rules | [Get all rules](/connector-api/operations/rules#get-all-rules) | | How to make a new booking | [Add reservations](/connector-api/operations/reservations#add-reservations) | ## Testing your integration Ensure you follow our general [Usage guidelines](/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. # Mews Payment Terminals This use case is for Mews customers and partners who want to access [Mews Payment Terminals](https://www.mews.com/en/products/terminals) to take payments from guests. ## Contents * [Introduction](#introduction) * [Caution!](#caution) * [Taking payments](#taking-payments) * [POS workflow](#pos-workflow) * [Kiosk workflow](#kiosk-workflow) * [Fiscal reporting](#fiscal-reporting) * [Operational procedures](#operational-procedures) * [Testing](#testing) * [Help and support](#help-and-support) ## Introduction This is most likely to be of interest if you have a Point Of Sale solution or a Kiosk solution – but we don't want to limit your imagination if you have a different application in mind! **POS:** Point Of Sale systems in outlets such as restaurants and shops will normally have their own payment terminals, but they may want to take payments through Mews Terminals for various reasons, perhaps because the terminals are located at reception, or to streamline the property's workflow. **Kiosk:** Typically, a guest uses a physical kiosk in the lobby for self-service, so they don't need to queue to see a member of staff at reception, if they choose to do so. The primary function of the kiosk is to check in at the property, but they might need to access a payment terminal, e.g. to make an on-site reservation, to pay the balance on an existing reservation, or to pay their bill on check-out. > **Terminology:** Remember that in the terminology of the Mews Connector API, the party connecting to the API (that's you!) is the *Client*; the hotel, hostel or other such property is the *Enterprise*; and the end-user or guest is the *Customer*. ## Caution! This use case is still considered a custom, special workflow. We are making the documentation publicly available due to popular demand, but it comes with some caveats. These are important, so please proceed with these caveats in mind. As always, we are open to feedback on the process. The caveats are as follows: * **Fiscal reporting** - this workflow may have important implications for [fiscal reporting](#fiscal-reporting) * **Operational procedures** - this workflow may have implications for [operational procedures](#operational-procedures) * **Development** - the integration may require significant development, because it uses a number of API Operations in conjunction with WebSockets * **Testing** - testing the workflow will require co-operation with our Partner Support team, because it needs Mews Terminals to be physically connected and configured Caveats aside, the functionality is available and documented, and certification is available as normal. ## Taking payments Mews Terminals are considered *devices*, and you communicate with them using [device integration commands](/connector-api/use-cases/device-integration). The most important API Operation you will need to use is [Add payment command](/connector-api/operations/commands#add-payment-command). This adds a device integration command to the device command queue, with an instruction to take a payment from a specified Mews Terminal device for a specified customer. Taking a payment is an asynchronous activity, so you will need to wait for a device command *event* to show that the payment is complete, or in case of error taking the payment. This is done using [WebSockets](/connector-api/events/websockets). Specifically, you will listen for [DeviceCommand](/connector-api/events/websockets#device-command-event) WebSocket events. ![Add payment command - message flow](/files/kGcDSTGt3uKMIjLeFm4C) ### Add payment command A call to [Add payment command](/connector-api/operations/commands#add-payment-command) looks something like this: Request URL: `https://api.mews.com/api/connector/v1/commands/addPaymentTerminal` Request body: ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "7059D2C25BF64EA681ACAB3A00B859CC-D91BFF2B1E3047A3E0DEC1D57BE1382", "Client": "MyPOS 1.0", "Type": "Payment", "TerminalId": "be35b39e-ad7e-460a-8de9-4c7581e016a2", "CustomerId": "35d4b117-4e60-44a3-9580-c582117eff98", "BillId": null, "Amount": { "Currency": "EUR", "Value": 230.00 } } ``` Response body: ```javascript { "CommandId": "2391a3df-1c61-4131-b6f8-c85b4234adcb" } ``` As well as the usual authentication parameters, required parameters are: * Type (either "Payment" or "Preauthorization") * TerminalId * CustomerId * Amount (Currency and Value) You must address the specific Mews Terminal with `TerminalId` (see [Obtaining the Terminal ID](#obtaining-the-terminal-id)), and identify the specific customer with `CustomerId` (see [Identifying the customer](#identifying-the-customer)). ### WebSocket event The WebSocket event you are listening for is a [DeviceCommand](/connector-api/events/websockets#device-command-event) event which matches the CommandId returned from [Add payment command](/connector-api/operations/commands#add-payment-command). For example: ```javascript { "Type": "DeviceCommand", "Id": "2391a3df-1c61-4131-b6f8-c85b4234adcb", "State": "Processed" } ``` The `State` field will tell you whether the payment was successful or not. ### Obtaining the Terminal ID A Mews Terminal is a type of *device*. The Terminal IDs for all connected Mews Terminals can be obtained by calling the [Get all devices](/connector-api/operations/devices#get-all-devices) API operation. You can call this operation on initialization and store the Terminal IDs. ### Identifying the customer As stated, you must identify the specific customer with `CustomerId` when communicating with a Mews Terminal through the API. `CustomerId` is the unique identifier of the customer profile or account profile, and can be obtained through the [Search customers](/connector-api/operations/customers#search-customers) API operation. For more information, see [POS Workflow](#pos-workflow) below. ## POS workflow As a POS system, you would normally use [Add outlet bills](/connector-api/operations/outletbills#add-outlet-bills) to send revenue and payments to Mews. However, if you need to use a Mews Terminal to take a payment, you instead use [Add payment command](/connector-api/operations/commands#add-payment-command) to add a card payment to a customer profile, and [Add order](/connector-api/operations/orders#add-order) to add order items, instead of using outlet items. The following workflow describes the steps of the process: * [Pre-conditions](#pre-conditions) * [Step 1: How does the customer want to pay?](#step-1-how-does-the-customer-want-to-pay) * [Step 2: Choose how to search for the customer](#step-2-choose-how-to-search-for-the-customer) * [Step 3: Instruct the terminal to take the payment](#step-3-instruct-the-terminal-to-take-the-payment) * [Step 4: Add the order items and prepare the bill](#step-4-add-the-order-items-and-prepare-the-bill) * [Step 5: Print the bill for the customer](#step-5-print-the-bill-for-the-customer) ### Pre-conditions You must fetch the following information before starting the main workflow: * **Room resources** - if you want to do room lookup, you must fetch the room or space resources for the enterprise and store the corresponding resource identifiers (see [Choose how to search for the customer](#step-2-choose-how-to-search-for-the-customer)) * **Paymaster profile** - if using a Paymaster account, you must set this up and store the account identifier (see [Customer profile vs Paymaster profile](#customer-profile-vs-paymaster-profile)) * **Terminal IDs** - you must fetch the identifiers of the Mews Terminal devices you want to connect to (see [Obtaining the Terminal ID](#obtaining-the-terminal-id)) ### Step 1: How does the customer want to pay? If the customer wants to charge the payment to the room, then follow the standard "post to room" workflow - perform room lookup with [Search customers](/connector-api/operations/customers#search-customers) to find the customer profile, then post the order items to the customer profile using [Add order](/connector-api/operations/orders#add-order). If the customer wants to pay by means other than a card at the terminal, then take the payment by other means (outside Mews), then follow the standard "revenue push" workflow - post the order items to Mews using [Add outlet bills](/connector-api/operations/outletbills#add-outlet-bills). ![](/files/FCPitWF7nfgUDoVm2kTq) What follows applies to the main workflow where the customer wants to **pay by card** using the terminal. ### Step 2: Choose how to search for the customer When using a Mews Terminal to take a payment, you will need the account profile of the customer, identified with a unique identifier. This is what is referred to as a Customer ID or CustomerId. How you obtain the customer identifier depends on the search scenario - room lookup, name lookup, or "customer is external". #### Room lookup If doing a room lookup, search against your stored list of room resources or spaces and obtain the Resource identifier for that space, then use the Resource identifier in a lookup for the checked-in customer using [Search customers](/connector-api/operations/customers#search-customers). This will return the Customer identifier or CustomerId. #### Name lookup If doing a name lookup, make a search against the customer's name directly, using [Search customers](/connector-api/operations/customers#search-customers). This will return the Customer identifier or CustomerId. #### Customer is external If the customer is external, i.e. not staying in the property, then you have two choices. You could either create a customer profile for that customer and take the payment against that, or you could use a pre-configured Paymaster profile and take the payment against that. See [Customer profile vs Paymaster profile](#customer-profile-vs-paymaster-profile) for a discussion of the alternatives. To create a customer profile, use [Add customer](/connector-api/operations/customers#add-customer). ![](/files/YlUkAPAg2cAUlHZG69Sy) ### Step 3: Instruct the terminal to take the payment Now that you have the account identifier for the account profile, either customer account or Paymaster account, you can take the payment. Choose from available terminals and use the Terminal ID for that terminal. Call the [Add payment command](/connector-api/operations/commands#add-payment-command) operation and store the Command ID returned.
### Step 4: Add the order items and prepare the bill Wait for an incoming WebSocket DeviceCommand message that matches the stored Command ID. Look at the `State` field to determine the success or otherwise of the operation. You may also want to implement a timeout process in case you don't receive an event in a timely manner. Assuming the State is "Processed", your next steps will be as follows: 1. Add the order items to the account profile, using [Add order](/connector-api/operations/orders#add-order) \*1 2. Create a new, empty bill linked to the account, using [Add bill](/connector-api/operations/bills#add-bill) 3. Transfer both the payment item and the order items to the bill, so it balances to zero, using [Update accounting items](/connector-api/operations/accountingitems#update-accounting-items) 4. Close the bill to further changes, using [Close bill](/connector-api/operations/bills#close-bill); Mews will handle fiscalization of the bill, if applicable > \*1 Note that orders can't be canceled through the API once added, so it's important to do this once the payment is confirmed. Otherwise, if there was a problem with the payment and the customer switched to cash to pay, then the order item would be posted twice, once against the profile and once posted as an outlet bill. ![](/files/2NeFKXbdcRwHWdC8lNvJ) #### Payment unsuccessful If the payment is *not* successful, the value of `State` will give an indication of the cause. In any case, you must return to the start of the process and consider an alternative means of payment. ### Step 5: Print the bill for the customer You will want to present a copy of the bill to the customer. One way to do this is to fetch a bill from Mews as a PDF document and print it out through a Mews connected printer. 1. Optional: Get the bill PDF and store the Base64Data, using [Get bill PDF](/connector-api/operations/bills#get-bill-pdf) 2. Optional: The user selects the printer and the number of copies required 3. Optional: Print the bill, using [Add printer command](/connector-api/operations/commands#add-printer-command) (like terminals, a printer is another type of connected device)
Now you are finished! ### Customer profile vs Paymaster profile Where the customer is not known to the system, such as a non-resident guest, you have two options for how to proceed. #### Customer profile Ideally, you would create a real customer profile each time, with real details such as name and email address. When this customer returns, you can then look up their profile in the POS, just like for a resident guest. However, some care is needed with such an implementation. For example, if there is more than one customer in the system with the same name, you will have to store some other identifying information and then ask the customer for verification. This workflow would also require the POS to be able to create and manage customer profiles. #### Paymaster profile Alternatively, all payments could be made against a single, pre-defined Paymaster profile. This keeps things centralized, but it requires some workarounds as the Mews system is not designed to work in this way, specifically you need to make sure all the bills are closed to keep things clean and manageable. Potentially you would have a single account profile with lots of payment cards under the Payments tab. To clear down the payments in the account, you could do this manually at the end of each period, e.g. end-of-shift or end-of-day, or you could do it programmatically via the API. The API supports [Update accounting items](/connector-api/operations/accountingitems#update-accounting-items) for moving specific order items to a bill, and [Close bill](/connector-api/operations/bills#close-bill) for closing bills. This would of course require further development on the part of the POS partner. ## Kiosk workflow Most of the workflow is common to the POS workflow, for which see above. #### Displaying the list of open items To retrieve and display open items against a customer account, use [Get all payments](/connector-api/operations/payments#get-all-payments) and [Get all order items](/connector-api/operations/orderitems#get-all-order-items), filtering by the specific customer account (using `AccountIds` request parameter) and by date-time to pick out items relevant to the customer's stay. This helps to avoid any confusion in case the customer has a future reservation. ## Fiscal reporting Be aware that, depending on the country in which you operate, you may need workarounds for fiscal reporting. This is due to the fact that you will be posting payments as actual payments in Mews, rather than just as Outlet items. Payments in Mews will use Mews's fiscal reporting, so if you also use fiscal reporting in the POS system there is a danger of duplicated reporting. This will depend on the fiscal and accounting requirements in the legal environment in which you operate, e.g. in Belgium all POS tickets need to go to the Blackbox Fiscal Data Module, regardless of whether a payment is a room charge or a cash or credit card transaction. ## Operational procedures The impact on operational procedures centers around the fact that Mews Terminal payments have to be posted to a customer profile in Mews. You will have to either create and manage customer profiles, or work with a shared Paymaster account, but in the latter case you will then have to create a process to close all bills at the end of each operating period. Each approach has pros and cons. This is discussed in [Customer profile vs Paymaster profile](#customer-profile-vs-paymaster-profile) above. Please review all the requirements before deciding on your workflow implementation. ## Testing To test your workflow implementation with an actual Mews Terminal device, please [contact support](/connector-api/contact-support). They will supply you with the necessary details to connect to a test configuration: * **Mews Operations** * Mews Operations platform address, for the appropriate test server * Test account username and password * Test property or enterprise name * **Mews Connector API** * Mews API platform address, for the appropriate environment * WebSocket address * **Test integration** * Integration name * Client Token * Access Token * **Terminal device** * Device name * Device ID / Terminal ID When testing [Add payment command](/connector-api/operations/commands#add-payment-command) to communicate with a Mews Terminal, note that just like other device commands, the command will be added to the *Device Commands Queue* and can be viewed by logging in to **Mews Operations**. The queue also shows the state of the transaction, so you can see if the payment was processed successfully or not, or if it is still pending. Finally, when a payment is taken through a Mews Terminal, it will appear against that customer's profile in **Mews Operations** under the *Payments* tab, just the same as any other payment item. ## Help and support Within the Connector API documentation, the following sections may be helpful: * [Add payment command](/connector-api/operations/commands#add-payment-command) * [WebSockets](/connector-api/events/websockets) * [Use cases - Device integration](/connector-api/use-cases/device-integration) * [Use cases - Kiosk](/connector-api/use-cases/kiosk) * [Use cases - Point of sale](/connector-api/use-cases/point-of-sale) There are a number of articles on Mews Help that may also provide additional assistance: * [Mews Terminals (various)](https://help.mews.com/s/global-search/mews%20terminal?language=en_US) * [The Device Commands Queue](https://help.mews.com/s/article/device-commands-queue) * [Create a customer profile](https://help.mews.com/s/article/create-a-customer-profile?language=en_US) If you still require assistance, please [contact support](/connector-api/contact-support). # Payment automation This section describes how to automate payment collection across the guest journey using **Mews Payments Checkout**. ## How it works For full integration details, see [Mews Payments Checkout](https://docs.mews.com/mews-payments-checkout). # Point of sale Here we walk you through a Point-of-sale (POS) integration, from initial setup (synchronizing product and payment information with Mews) through to customer/guest search, posting charges and posting end-of-day balances or 'outlet bills'. We also cover split payments, rebates and gratuities, as well as providing some guidance on testing your integration; and finally, some links to further information. ## General principles When using the API, charge items are part of an `order` and are posted directly to a customer profile and not to a room or reservation. The target profile is either one that is active and attached to a reservation, i.e. a checked-in guest, or else is a profile classified as `Paymaster`. To post a charge to a customer profile, use the API operation [Add order](/connector-api/operations/orders#add-order). For more details, see [Charge posting](#charge-posting) below. The receipts that are finalized in the POS system can be sent to Mews to allow for end-of-day balancing (sometimes referred to as 'revenue push' or 'revenue sync'). In Mews, these are called `outlet bills`. For more details, see [Outlets bills](#outlets-bills) below. ## Initial setup There are two concepts in Mews that are used to represent the point-of-sale or revenue center that exists in a property: `services` and `outlets`. A user can configure the names of both to match the actual name of the restaurant/bar/spa/etc. for ease of recognition on Mews reports. Both already exist in the [Demo environment](/connector-api/guidelines/environments) for testing purposes. * A `service` is used to represent the point-of-sale under which `items` are recorded when posting `orders`. * An `outlet` is used to represent the point-of-sale under which `items` are recorded when posting `outlet bills`. ### Services Use [Get all services](/connector-api/operations/services#get-all-services) to retrieve services the property has created in Mews, which can then be mapped to corresponding services in the POS system. The services of interest to POS systems are those with [service data](/connector-api/operations/services#service-data) of type `Additional`, together with any products offered under those services. Use the service `Id` when identifying a service in subsequent API calls. | 'How to' use case | API Operations | | ---------------------------------- | ----------------------------------------------------------------------- | | How to get the configured services | [Get all services](/connector-api/operations/services#get-all-services) | ### Outlets Outlets are used by the POS to send a full revenue push to Mews, for end-of-day balancing. Use [Get all outlets](/connector-api/operations/outlets#get-all-outlets) to retrieve outlets that the property has configured. Outlets should be created by the property for each external location, as well as unique `accounting categories` that should be used to separate payments and revenue per outlet. | 'How to' use case | API Operations | | --------------------------------- | -------------------------------------------------------------------- | | How to get the configured outlets | [Get all outlets](/connector-api/operations/outlets#get-all-outlets) | ### Resources Use [Get all resources](/connector-api/operations/resources#get-all-resources) to retrieve the list of resources the property has set up in Mews. Resources includes bookable spaces such as guest rooms. This will then give you the information needed to make a customer look-up against a specific guest room or other type of resource. | 'How to' use case | API Operations | | ------------------------------------------ | -------------------------------------------------------------------------- | | How to get the configured rooms and spaces | [Get all resources](/connector-api/operations/resources#get-all-resources) | ### Accounting categories Accounting categories are linked to accounting items such as revenue items (e.g. entree, main, dessert, beverage, or alcohol) and payment items (e.g. credit card, cash, voucher, invoice). The POS system should be configured to map accounting items to the correct accounting categories in Mews to ensure accurate posting. Use [Get all account categories](/connector-api/operations/accountingcategories#get-all-accounting-categories) to retrieve a list of all `accounting categories` which the property has configured, then map these against the product offerings and accepted payment types that have been configured in the POS system. | 'How to' use case | API Operations | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | How to get the configured accounting categories | [Get all account categories](/connector-api/operations/accountingcategories#get-all-accounting-categories) | ### Example of POS revenue item and payment type mapping | POS Revenue/Payment | Mews Accounting Category | | ------------------- | ---------------------------- | | Champagne | Resto Beverage Alcoholic | | Orange juice | Resto Beverage Non-Alcoholic | | Salad | Restaurant Food | | Cash | Cash | | Credit card | Credit card | ## Customer search Searching for customers active within the property is done via the [Search customers](/connector-api/operations/customers#search-customers) operation. This will allow you to search all customers that are in-house or those with the `PaymasterAccount` [customer classification](/connector-api/operations/customers#customer-classification). Customers can be searched by `FirstName` and/or `LastName`, or by `ResourceId`, which then returns all customers matching the criteria. In-house customers are those who are listed as `companions` against a checked-in reservation - see the [Additional help](#additional-help) links below for more information. You can post charges to customer profiles with the classification of `PaymasterAccount` regardless of whether they are attached to checked-in reservations or not. The customer classification `Cashlist` is used by properties to indicate where charges should **not** be posted to the customer bill, this is also commonly known as "No Post". Note that having a `Cashlist` [customer classification](/connector-api/operations/customers#customer-classification) does not automatically prevent orders from being posted to the customer's bill, the POS system can decide whether to recognise this classification on a customer profile and prevent users from sending room charges from the POS system. | 'How to' use case | API Operations | | ------------------------------------ | ------------------------------------------------------------------------ | | How to search for a customer (guest) | [Search customers](/connector-api/operations/customers#search-customers) | > **Room numbers:** Note that hotel room numbers and other space descriptors may consist of numbers, letters and other characters. Don't assume they only contain numbers. ## Charge posting Once the customer profile to be charged is identified, the items can be posted onto their bill using the [Add order](/connector-api/operations/orders#add-order) operation. The order needs to be sent with its full name, e.g. "Caesar salad" or "Beer", and not just “Item". The `AccountingCategoryId` will need to be used per item to allow for correct reporting for accounting systems. You can make use of `Notes` to record the associated ticket number from the POS system. > #### Linking orders to reservations > > When using [Add order](/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 a charge to a customer profile | [Add order](/connector-api/operations/orders#add-order) | | How to link an order to a reservation | [Add order](/connector-api/operations/orders#add-order) (use `LinkedReservationId`) | ## Split payments If the POS supports split payments, e.g. one salad divided between two people, it must be sent to Mews as separate transactions with the product `Count` or item `UnitCount` rounded up to the nearest whole number. *Example: One salad of €10.00 divided between two people is sent as two separate orders, each with one salad at a price of €5.00.* ## Rebates Rebates or canceled items will need to be allowed by the property and can be applied to both orders and outlet bills. It is not permitted to directly cancel or modify the originally posted item, therefore the POS system should use the applicable API operation ([Add order](/connector-api/operations/orders#add-order) or [Add outlet bill](/connector-api/operations/outletbills#add-outlet-bills)) to post a rebate or canceled item. Such items should be sent through with **negative** values, in order to balance out the previously posted amount. *Example: One salad of €10.00 has been sent to Mews. To rebate this item, send through one salad of -€10.00. For a partial rebate of 50%, send through one salad of -€5.00.* ## Gratuities Gratuities should be sent as another item to Mews and can be posted under a different accounting category, depending on the property's accounting practices and configurations. In the full revenue push, both the tip revenue item and the payment used to cover the tip should be sent. ## Outlets bills Outlets are used in Mews to record any revenue and payments that have been taken outside of Mews. This allows for the centralization and reporting of data to an external accounting system. The POS system will need to use [Add outlet bill](/connector-api/operations/outletbills#add-outlet-bills) to post all end-of-day revenue and payments to the outlet(s) the property has configured in Mews. Any outlet items that are sent to Mews will need to have an `AccountingCategoryId` attached to the item. You can make use of `Number` to record the associated ticket or receipt number from the POS system. In an outlet bill, items of [outlet item type](/connector-api/operations/outletitems#outlet-item-type) `Payment` are customisable by `Name`, and should draw from the list of accepted types of payment configured in the POS system. Such items should also be sent with the corresponding accounting categories previously mapped in the POS system to ensure correct reporting. | 'How to' use case | API Operations | | --------------------------------------- | ------------------------------------------------------------------------- | | How to post end-of-day accounting items | [Add outlet bill](/connector-api/operations/outletbills#add-outlet-bills) | ## Testing your integration Ensure you follow our general [Usage guidelines](/connector-api/guidelines) for testing integrations. To make sure the integration supports the minimum expected functionality, please test the following operations. Ignore any items that are not supported by your solution or not required by the property. * Post a charge to the guest bill (in-house customer or Paymaster) * Post a split charge to separate guest bills * Post a % discount to the guest bill * Post an absolute discount to the guest bill * Post an item with the amount 0 to the guest bill * Post an outlet bill with revenue items and payment items * Post an outlet bill with the amount 0 * Confirm that a room posting cannot be made for a customer with the [customer classification](/connector-api/operations/customers#customer-classification) `Cashlist` To check that you have correctly posted an order, you can review the billing tab of the relevant guest profile. To confirm you are mapping any product that is not configured in Mews with the correct accounting category, you can review the [Mews Accounting Report](https://help.mews.com/s/article/accounting-report?language=en_US). If done correctly, the product you have posted will appear under the relevant accounting category. All correctly posted orders will be shown in the Revenue section of the report. All outlet bills (containing both revenue items and matching payments) will be shown in the Outlet section of the report. An incorrectly posted item (without an associated accounting category) will be displayed in the Accounting Report under the 'None' accounting category of either section. ## Connecting to Mews Terminals To connect to Mews Payment Terminals, see [Mews Payment Terminals](/connector-api/use-cases/mews-terminals). ## Additional help > **Help Guides**: > > * [Point-of-sale integrations for Mews Operations](https://help.mews.com/s/article/point-of-sale-integrations-for-mews-operations?language=en_US) > * [Mews Availability Block Report](https://help.mews.com/s/article/Availability-block-report?language=en_US) > * [Mews Glossary for Open API users](/getting-started/glossary) > * [Mews Accounting Report](https://help.mews.com/s/article/accounting-report?language=en_US) > * [Create a customer profile](https://help.mews.com/s/article/create-a-customer-profile?language=en_US) > * [How to add a customer to a reservation](https://help.mews.com/s/article/How-to-add-a-customer-to-a-reservation?language=en_US) > * [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) > * [Understanding services](https://help.mews.com/s/article/understanding-services?language=en_US) > * [Set up outlets](https://help.mews.com/s/article/set-up-outlets?language=en_US) > * [Create or delete a product](https://help.mews.com/s/article/create-or-delete-a-product?language=en_US) # Reputation management Reputation management systems typically require reservation information, customer profile information, and the ability to update customer profiles. ## 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](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) with [reservation state](/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](/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](/connector-api/events/websockets) (`Reservation` event). | 'How to' use case | API Operations | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | How to get checked-out reservations | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | | How to listen for changes to reservations | [General Webhooks](/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](/connector-api/events/websockets) (`Reservation` event) | ## Updating the customer profile When a Reputation management system links customer feedback to a customer, use [Update customer](/connector-api/operations/customers#update-customer) to update the customer profile in Mews. The [customer classification](/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](/connector-api/operations/customers#update-customer) | ## Testing your integration Please ensure you follow our general [Usage guidelines](/connector-api/guidelines) for testing integrations. # Revenue management A Revenue Management System (RMS) optimizes occupancy and rates to achieve maximum total revenue for a property. To do this, a Revenue management integration fetches information about reservations, revenue and pricing from Mews, and then based on this data may recommend new rates, or directly update the rates, and estimates future revenue and occupancy. In bigger properties, there may be more than 50,000 reservations in a year, so it is necessary to limit operations in terms of potential data size, in order to avoid timeouts, network errors, etc. A recommended approach for implementing a Revenue management integration is described below. Following these guidelines should ensure that both our servers and those of the RMS are not unnecessarily overburdened. ## Initial data pull > **Data export:** See also [Bulk data export](#bulk-data-export) below. An initial data pull is performed once when setting up the connection, because the RMS needs to obtain historical data on which to base its calculations. ### Fetching reservations The RMS should fetch the reservations in time-limited batches using [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06), with [`TimeFilter`](/connector-api/operations/reservations#reservation-time-filter) set to `Start`. That will give you all reservations with an arrival time colliding with the selected interval. The optimum size of the batches depends on the size of the property and its occupancy, but in general **weekly batches** are recommended and will work well even for big hotels of 1000+ units. For example, in order to get reservations for the past year, the RMS should call [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) sequentially 52 times, with one call for each week in the past year. That would give the RMS all reservations that have an arrival within the past year. | 'How to' use case | API Operations | | --------------------------------------- | -------------------------------------------------------------------------------------------------- | | How to get historical reservations data | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | You can take advantage of the fact that reservations are usually booked a few weeks or months in advance. The further in future, the lower the occupancy, so the reservation batch length may increase with the distance to future from the current date. For example, weekly batches can be used only for the first three months of the future year when there is higher occupancy. And for the remaining 9 months, monthly batches would be sufficient. This will reduce the operation count from 52 to 21 (12 weekly batches + 9 monthly batches). ### Fetching rates and other data The RMS can also pull business segments via [Get all business segments](/connector-api/operations/businesssegments#get-all-business-segments) and rates via [Get all rates](/connector-api/operations/rates#get-all-rates). To obtain revenue items associated with reservations, use [Get all order items](/connector-api/operations/orderitems#get-all-order-items). Information about resource blocks, e.g. rooms out of order, can be requested using [Get all resource blocks](/connector-api/operations/resourceblocks#get-all-resource-blocks). If you are managing availability blocks, see the [Events](/connector-api/use-cases/events#managing-group-reservations-with-availability-blocks) use case for information on relevant operations. | 'How to' use case | API Operations | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | How to get all configured business segments | [Get all business segments](/connector-api/operations/businesssegments#get-all-business-segments) | | How to get all configured rates and rate groups | [Get all rates](/connector-api/operations/rates#get-all-rates) | | How to get order items linked to a reservation | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | | How to get information about out-of-order blocks | [Get all resource blocks](/connector-api/operations/resourceblocks#get-all-resource-blocks) | > **Terminology:** For an explanation of terms such as *business segment*, see the [Mews Glossary for Open API users](/getting-started/glossary). ### Fetching data in the right order It is important to get the reservations and revenue first and the additional data afterwards. If done the other way around, there is a possibility that the RMS receives a reservation with a `RateId` which does not correspond to any rate that was pulled beforehand. Rates and business segments are dynamic and hotel employees could create a new one and assign it to a reservation just before the reservation gets pulled to the RMS. ## Bulk data export As an alternative to making conventional API requests using [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06), we provide a bulk [Data export](/connector-api/use-cases/data-export) feature. | 'How to' use case | API Operations | | ------------------------------------ | -------------------------------------------------------------------- | | How to create a bulk data export | [Add export](/connector-api/operations/exports#add-export) | | How to check on data export progress | [Get all exports](/connector-api/operations/exports#get-all-exports) | ## Periodic updates and syncing data To keep reservations up-to-date and synced across your systems in real time, first cache the reservation data retrieved from the initial reservation data pull, then use [General Webhooks](/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](https://github.com/MewsSystems/open-api-docs/blob/main/connector-api/websockets/README.md) (`Reservation` event) to listen for reservation events. When you receive a reservation event, use the reservation `Id` obtained from the event to fetch the details of the reservation with [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06). > **WebSocket disconnection:** In case of WebSocket disconnection, use [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) with `UpdatedUtc` to perform a full resync of reservations that have been updated within the time period since the last full reservation data pull. The suggested frequency for periodic reservation syncing is 30 minutes for business intelligence solutions. Adjust the frequency depending on your use case. For example, a mobile key integration would rely more on real-time accuracy of reservation data to provide correct door access to the guest, whereas a thirty-minute to one-hour (or longer) interval period might suffice for a business intelligence solution aimed at providing daily statistical insight to a property's business operations. | 'How to' use case | API Operations | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | How to listen for changes to reservations | [General Webhooks](/connector-api/events/wh-general) (`ServiceOrderUpdated` event) or [WebSockets](https://github.com/MewsSystems/open-api-docs/blob/main/connector-api/websockets/README.md) (`Reservation` event) | | How to get reservation details | [Get all reservations](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | ## Rate pricing To get rate information, there are three relevant operations. [Get all rates](/connector-api/operations/rates#get-all-rates) gives you information about the names and IDs of the rates in the property, and their status, and also restrictions. [Get all rate groups](/connector-api/operations/rategroups#get-all-rate-groups) gives you information rate groups. And [Get rate pricing](/connector-api/operations/rates#get-rate-pricing) gives you the pricing of a specific rate for a specific time period. In order to update rate prices, use [Update rate price](/connector-api/operations/rates#update-rate-price). Individual rate, resource category and time span can be selected. To avoid heavy consumption of API resources, while keeping rate price data up-to-date in real time, use [WebSockets](https://github.com/MewsSystems/open-api-docs/blob/main/connector-api/websockets/README.md) to listen for `PriceUpdate` events. Then retrieve information about the relevant rates using [Get rate pricing](/connector-api/operations/rates#get-rate-pricing), filtering by the relevant `RateId`. | 'How to' use case | API Operations | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | How to get all configured rates | [Get all rates](/connector-api/operations/rates#get-all-rates) | | How to get all configured rate groups | [Get all rate groups](/connector-api/operations/rates#get-all-rate-groups) | | How to get the price for a specific rate and time period | [Get rate pricing](/connector-api/operations/rates#get-rate-pricing) | | How to listen for changes to rate prices | [WebSockets](https://github.com/MewsSystems/open-api-docs/blob/main/connector-api/websockets/README.md) (`PriceUpdate` event) | ## Restrictions To retrieve information about restrictions, use [Get all restrictions](/connector-api/operations/restrictions#get-all-restrictions). To add and remove restrictions, use [Set restrictions](/connector-api/operations/restrictions#set-restrictions) and [Clear restrictions](/connector-api/operations/restrictions#clear-restrictions) respectively. | 'How to' use case | API Operations | | ---------------------------------- | ----------------------------------------------------------------------------------- | | How to get service restrictions | [Get all restrictions](/connector-api/operations/restrictions#get-all-restrictions) | | How to add service restrictions | [Set restrictions](/connector-api/operations/restrictions#set-restrictions) | | How to remove service restrictions | [Clear restrictions](/connector-api/operations/restrictions#clear-restrictions) | > **Important:** For more information about restrictions, including the algorithms used when setting and clearing restrictions, and the scope of restrictions affected by API operations, see [Concepts > Restrictions](/connector-api/concepts/restrictions). ## Occupancy When calculating occupancy, it is important to take the hierarchy of resources into account. For example, if there is a reservation against a dormitory (or dorm), then not only is the dormitory occupied but also the beds which are child resources of the dormitory. And vice versa, if a bed in a dorm is occupied, then the dorm is also occupied. ## Testing your integration Once your integration is completed, all operations should be tested prior to initiating the [Certification process](/connector-api/your-journey) with the **Mews Marketplace** team. Testing your solution is done directly in the Connector API Demo environment. You should use the credentials found in [Environments](/connector-api/guidelines/environments) to sign in as an end-user. This allows you to understand how both your system and the Mews system will be used by the property and gives you additional information to ensure you can provide a seamless on-boarding experience for our customers. For help on how to create new reservations, please follow the steps outlined in the [Create a reservation](https://help.mews.com/s/article/create-a-reservation?language=en_US) guide. If you'd like to double-check that you are correctly requesting all the reservations you want to retrieve, you can compare the API response to the Mews [Reservation Report](https://help.mews.com/s/article/reservation-report?language=en_US). This report can easily be exported in various formats following the steps in [Scheduling report exports](https://help.mews.com/s/article/schedule-report-exports?language=en_US). For testing Webhooks or WebSockets, set up your system to start listening for events, then manually trigger an event, e.g. update any element within a reservation. ## Additional help > **Help Guides**: > > * [Create a reservation](https://help.mews.com/s/article/create-a-reservation?language=en_US) > * [Reservation Report](https://help.mews.com/s/article/reservation-report?language=en_US) > * [Scheduling report exports](https://help.mews.com/s/article/schedule-report-exports?language=en_US) > * [Understanding restrictions](https://help.mews.com/s/article/Understanding-restrictions-in-Mews-Operations?language=en_US) # Upsell 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. ## 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](/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](/connector-api/operations/products#get-all-products). | 'How to' use case | API Operations | | -------------------------------------------------- | ----------------------------------------------------------------------- | | How to get the list of services offered | [Get all services](/connector-api/operations/services#get-all-services) | | How to get the list of products linked to services | [Get all products](/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](/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](/connector-api/operations/services#get-service-availability) | > **Help Guides**: > > * [Mews Glossary for Open API users](/getting-started/glossary) > * [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) ## 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. ### 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](/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](/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](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | | How to add a product order to a reservation | [Add reservation product](/connector-api/operations/reservations#add-reservation-product) | ### 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](/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](/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](/connector-api/operations/orders#add-order). If the product being posted already exists in Mews, then use [Product order parameters](/connector-api/operations/orders#product-order-parameters). If the product does not exist in Mews then use [Item parameters](/connector-api/operations/orders#item-parameters). > #### Linking orders to reservations > > When using [Add order](/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](/connector-api/operations/customers#get-all-customers) | | How to get only checked in guests | [Search customers](/connector-api/operations/customers#search-customers) | | How to add a product order to a guest profile | [Add order](/connector-api/operations/orders#add-order) | | How to link an order to a reservation | [Add order](/connector-api/operations/orders#add-order) (use `LinkedReservationId`) | ### 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](/connector-api/operations/orders#item-parameters) of the [Add order](/connector-api/operations/orders#add-order) request. Information about all the categories configured at each property can be obtained with [Get all accounting categories](/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](/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](/connector-api/operations/accountingcategories#get-all-accounting-categories) | | How to create staff reminders | [Add task](/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) ## Testing your Upsell integration Ensure you follow our general [Usage guidelines](/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. # API Operations This section describes all operations supported by the API, organised here by theme. ## Accounts | Operation | Description | | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | [Merge accounts](/connector-api/operations/accounts#merge-accounts) | Merges two or more accounts of the same account type together | | [Update accounts](/connector-api/operations/accounts#update-accounts) | Updates one or more existing accounts, i.e. customer, company | | [Upload and link file to account](/connector-api/operations/accounts#upload-and-link-file-to-account) | Uploads a file and links it to the specified account | | [Get all addresses](/connector-api/operations/addresses#get-all-addresses) | Returns all addresses associated with the specified accounts within the enterprise | | [Add addresses](/connector-api/operations/addresses#add-addresses) | Adds a new address to the system and assigns it to a specified account | | [Update addresses](/connector-api/operations/addresses#update-addresses) | Updates an existing address in the system assigned to a specified account | | [Delete addresses](/connector-api/operations/addresses#delete-addresses) | Deletes selected addresses | | [Get all account notes](/connector-api/operations/accountnotes#get-all-account-notes) | Returns all the account notes associated with the specified accounts within the chain | | [Add account notes](/connector-api/operations/accountnotes#add-account-notes) | Adds new account notes to the system and assigns it to specified accounts | | [Update account notes](/connector-api/operations/accountnotes#update-account-notes) | Updates existing account notes | | [Delete account notes](/connector-api/operations/accountnotes#delete-account-notes) | Deletes selected account notes | ## Billing Automations | Operation | Description | | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | [Get all billing automations](/connector-api/operations/billingautomations#get-all-billing-automations) | Returns all billing automations of the enterprise | | [Add billing automations](/connector-api/operations/billingautomations#add-billing-automations) | Adds new billing automations | | [Update billing automations](/connector-api/operations/billingautomations#update-billing-automations) | Updates selected billing automations | | [Update billing automation assignments](/connector-api/operations/billingautomations#update-billing-automation-assignments) | Updates assignments for selected billing automations | | [Delete billing automations](/connector-api/operations/billingautomations#delete-billing-automations) | Deletes selected billing automations | ## Configuration | Operation | Description | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [Get configuration](/connector-api/operations/configuration#get-configuration) | Returns configuration of the enterprise and the client | | [Get all countries](/connector-api/operations/countries#get-all-countries) | Returns all countries supported by the API | | [Get all currencies](/connector-api/operations/currencies#get-all-currencies) | Returns all currencies supported by the API | | [Get all tax environments](/connector-api/operations/taxenvironments#get-all-tax-environments) | Returns all tax environments supported by the API | | [Get all taxations](/connector-api/operations/taxations#get-all-taxations) | Returns all taxations supported in tax environments | | [Get all languages](/connector-api/operations/languages#get-all-languages) | Returns all languages supported by the API | | [Get language texts](/connector-api/operations/languages#get-language-texts) | Returns translations of texts in the specified languages | | [Get image URLs](/connector-api/operations/images#get-image-URLs) | Returns URLs of the specified images | ## Customers | Operation | Description | | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Get all customers](/connector-api/operations/customers#get-all-customers) | Returns all customers filtered by identifiers, emails, names and other filters | | [Search customers](/connector-api/operations/customers#search-customers) | Searches for customers that are active at the moment in the enterprise, e.g. companions of checked-in reservations or paymasters | | [Get customers relationships](/connector-api/operations/customers#get-customers-relationships) | **Restricted!** Returns relationships between customers | | [~~Get customers open items~~](/connector-api/operations/customers#get-customers-open-items) | **Deprecated!** Use [Get all payments](/connector-api/operations/payments#get-all-payments) and [Get all order items](/connector-api/operations/orderitems#get-all-order-items) instead. | | [Add customer](/connector-api/operations/customers#add-customer) | Adds a new customer to the system and returns details of the added customer | | [Update customer](/connector-api/operations/customers#update-customer) | Updates personal information of a customer | | [~~Merge customers~~](/connector-api/operations/customers#merge-customers) | **Deprecated!** Please use [Merge accounts](/connector-api/operations/accounts#merge-accounts) instead. | | [Add customer file](/connector-api/operations/customers#add-customer-file) | Attaches the specified file to the customer profile | | [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) | Returns all identity documents for the specified customers | | [Adds identity documents](/connector-api/operations/identitydocuments#add-identity-documents) | Adds new identity documents | | [Update identity documents](/connector-api/operations/identitydocuments#update-identity-documents) | Updates specified identity documents | | [Delete identity documents](/connector-api/operations/identitydocuments#delete-identity-documents) | Deletes specified identity documents | | [Clear identity documents](/connector-api/operations/identitydocuments#clear-identity-documents) | Deletes all identity documents for the specified customers | ## Device integration | Operation | Description | | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | [Get all devices](/connector-api/operations/devices#get-all-devices) | Returns all devices in the enterprise | | [Get all commands](/connector-api/operations/commands#get-all-commands) | Returns all commands the are still active from the client application point of view | | [Get all commands by ids](/connector-api/operations/commands#get-all-commands-by-ids) | Returns all commands by their identifiers | | [Get all fiscal machine commands](/connector-api/operations/commands#get-all-fiscal-machine-commands) | **Restricted!** Returns fiscal machine commands by their identifiers or state. | | [Add printer command](/connector-api/operations/commands#add-printer-command) | Adds a new printer command representing printing of the specified document on a printer | | [Add key cutter command](/connector-api/operations/commands#add-key-cutter-command) | Adds a new key cutter command representing cutting of a key for the specified reservation | | [Add payment command](/connector-api/operations/commands#add-payment-command) | **Restricted!** Adds a new Mews Payment Terminal command | | [Update command](/connector-api/operations/commands#update-command) | Updates state of a command | ## Enterprises | Operation | Description | | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | [Get all enterprises](/connector-api/operations/enterprises#get-all-enterprises) | Returns all enterprises accessible to a supplied access token | | [Get all companies](/connector-api/operations/companies#get-all-companies) | Returns all company profiles of the enterprise, possibly filtered by identifiers, names or other filters | | [Add company](/connector-api/operations/companies#add-company) | Adds a new company to the enterprise | | [Update company](/connector-api/operations/companies#update-company) | Updates information of the company | | [Delete companies](/connector-api/operations/companies#delete-companies) | Deletes selected companies | | [Get all company contracts](/connector-api/operations/companycontracts#get-all-company-contracts) | Returns all contracts between the enterprise and other companies | | [Add company contracts](/connector-api/operations/companycontracts#add-company-contracts) | Adds new company contracts to the enterprise | | [Update company contracts](/connector-api/operations/companycontracts#update-company-contracts) | Updates selected company contracts | | [Delete company contracts](/connector-api/operations/companycontracts#delete-company-contracts) | Deletes selected company contracts | | [Get all departments](/connector-api/operations/departments#get-all-departments) | Returns all departments of an enterprise associated with the connector integration | | [Get all counters](/connector-api/operations/counters#get-all-counters) | Returns all counters of an enterprise associated with the connector integration | | [Get all outlets](/connector-api/operations/outlets#get-all-outlets) | Returns all outlets of an enterprise associated with the connector integration | | [Get all resources](/connector-api/operations/resources#get-all-resources) | Returns all resources of an enterprise associated with the connector integration | | [Get resources' occupancy state](/connector-api/operations/resources#get-resources-occupancy-state) | Returns occupancy state of the specified resources in the given time interval | | [Update resources](/connector-api/operations/resources#update-resources) | Updates details of the resources | | [Get all resource blocks](/connector-api/operations/resourceblocks#get-all-resource-blocks) | Returns all resource blocks (out of order blocks or internal use blocks) | | [Add resource block](/connector-api/operations/resourceblocks#add-resource-block) | Adds a new resource block to the specified resource for a defined period of time | | [Delete resource blocks](/connector-api/operations/resourceblocks#delete-resource-blocks) | Removes specified resource blocks from the resources | | [Add task](/connector-api/operations/tasks#add-task) | Adds a new task to the enterprise, optionally to a specified department | | [Close task](/connector-api/operations/tasks#close-tasks) | Closes one or more tasks. | | [Get all tasks](/connector-api/operations/tasks#get-all-tasks) | Returns all tasks of the enterprise, filtered by identifiers or other filters | | [Get all resource categories](/connector-api/operations/resourcecategories#get-all-resource-categories) | Returns all resource categories of an enterprise associated with the connector integration | | [Get all resource category assignments](/connector-api/operations/resourcecategories#get-all-resource-category-assignments) | Returns all resource category assignments of an enterprise associated with the connector integration | | [Get all resource category image assignments](/connector-api/operations/resourcecategories#get-all-resource-category-image-assignments) | Returns all resource category image assignments of an enterprise associated with the connector integration | | [Get all resource features](/connector-api/operations/resourcefeatures#get-all-resource-features) | Returns all resource features of an enterprise associated with the connector integration | | [Get all resource feature assignments](/connector-api/operations/resourcefeatures#get-all-resource-feature-assignments) | Returns all resource feature assignments of an enterprise associated with the connector integration | ## Exports | Operation | Description | | -------------------------------------------------------------------- | ------------------------------------------------------------------------ | | [Get all exports](/connector-api/operations/exports#get-all-exports) | **Restricted!** Returns all exports filtered by their unique identifiers | | [Add export](/connector-api/operations/exports#add-export) | **Restricted!** Create a pending export | ## Finance | Operation | Description | | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Get all exchange rates](/connector-api/operations/exchangerates#get-all-exchange-rates) | Returns all available exchange rates among currencies of the enterprise | | [Get all cashiers](/connector-api/operations/cashiers#get-all-cashiers) | Returns all cashiers in the enterprise | | [Get all cashier transactions](/connector-api/operations/cashiertransactions#get-all-cashier-transactions) | Returns all cashier transactions created within the specified interval | | [Get all accounting categories](/connector-api/operations/accountingcategories#get-all-accounting-categories) | Returns all accounting categories of the enterprise associated with the connector integration | | [~~Get all accounting items~~](/connector-api/operations/accountingitems#get-all-accounting-items) | **Deprecated!** Please use [Get all payments](/connector-api/operations/payments#get-all-payments) and [Get all order items](/connector-api/operations/orderitems#get-all-order-items) instead. | | [Update accounting items](/connector-api/operations/accountingitems#update-accounting-items) | Updates specified accounting item | | [Get all bills](/connector-api/operations/bills#get-all-bills) | Returns all bills, possibly filtered by customers, identifiers and other filters | | [Add bill](/connector-api/operations/bills#add-bill) | Creates new empty bill assigned to specified account | | [Update bills](/connector-api/operations/bills#update-bills) | **Restricted!** Updates account assignments of one or more open bills | | [Delete bill](/connector-api/operations/bills#delete-bill) | Removes selected bills | | [Close bill](/connector-api/operations/bills#close-bill) | Closes a bill so no further modification to it is possibles | | [Get bill PDF](/connector-api/operations/bills#get-bill-PDF) | Creates a PDF version of the specified bill | | [Get all outlet items](/connector-api/operations/outletitems#get-all-outlet-items) | Returns all outlet items of the enterprise that were consumed (posted) or will be consumed within the specified interval | | [Get all credit cards](/connector-api/operations/creditcards#get-all-credit-cards) | Returns all credit cards, possibly filtered by identifiers, customers or other filters | | [Charge credit card](/connector-api/operations/creditcards#charge-credit-card) | Creates payment for specified customer credit card and charges the credit card via a gateway | | [Add tokenized credit card](/connector-api/operations/creditcards#add-tokenized-credit-card) | Adds a new tokenized credit card to the specified customer | | [Disable gateway credit card](/connector-api/operations/creditcards#disable-gateway-credit-card) | **Restricted!** Disables a credit card from being used for payments | |

Get all preauthorizations
by customers

| Returns all preauthorizations of specified customers | | [~~Add credit card payment~~](/connector-api/operations/payments#add-credit-card-payment) | **Deprecated!** Follow the [Payment automation use case](/connector-api/use-cases/payment-automation) to collect and charge payment methods. | | [Add external payment](/connector-api/operations/payments#add-external-payment) | Adds a new external payment to a bill of the specified customer | | [Add alternative payment](/connector-api/operations/payments#add-alternative-payment) | Adds a new alternative payment to a specified customer | | [Get all payments](/connector-api/operations/payments#get-all-payments) | Returns all payments, filtered by various parameters | | [Get all payment requests](/connector-api/operations/paymentrequests#get-all-payment-requests) | Returns all payment requests | | [Add payment requests](/connector-api/operations/paymentrequests#add-payment-requests) | Adds new payment requests for specified customers | | [Cancel payment requests](/connector-api/operations/paymentrequests#cancel-payment-requests) | Cancels specified pending payment requests | | [Add payment method request](/connector-api/operations/paymentmethodrequests#add-payment-method-request) | Adds a payment method request to prompt a customer or company to provide a payment method | | [Get all payment policies](/connector-api/operations/paymentpolicies#get-all-payment-policies) | **Restricted!** Returns all payment policies matching the specified filter parameters | | [Get all payment policy assignments](/connector-api/operations/paymentpolicyassignments#get-all-payment-policy-assignments) | **Restricted!** Returns all payment policy assignments linking payment policies to rate groups or rates | | [Add outlet bills](/connector-api/operations/outletbills#add-outlet-bills) | Adds new outlet bills with their items | | [Get all order items](/connector-api/operations/orderitems#get-all-order-items) | Returns all order items | | [Cancel order items](/connector-api/operations/orderitems#cancel-order-items) | **Restricted!** Cancels specified order items | | [Refund payment](/connector-api/operations/payments#refund-payment) | Refunds a specified payment | | [Add billing automation payment plan](/connector-api/operations/paymentplans#add-billing-automation-payment-plan) | Adds a payment plan connected to a billing automation | | [Get all ledger balances](/connector-api/operations/ledgerbalances#get-all-ledger-balances) | Returns balances of specified ledgers for each day | ## Loyalty | Operation | Description | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | [Get all loyalty programs](/connector-api/operations/loyaltyprograms#get-all-loyalty-programs) | Returns all loyalty programs of the enterprise | | [Add loyalty programs](/connector-api/operations/loyaltyprograms#add-loyalty-programs) | Adds new loyalty programs | | [Update loyalty programs](/connector-api/operations/loyaltyprograms#update-loyalty-programs) | Updates selected loyalty programs | | [Delete loyalty programs](/connector-api/operations/loyaltyprograms#delete-loyalty-programs) | Deletes selected loyalty programs | | [Get all loyalty memberships](/connector-api/operations/loyaltymemberships#get-all-loyalty-memberships) | Returns all loyalty memberships of the enterprise | | [Add loyalty memberships](/connector-api/operations/loyaltymemberships#add-loyalty-memberships) | Adds new loyalty memberships | | [Update loyalty memberships](/connector-api/operations/loyaltymemberships#update-loyalty-memberships) | Updates selected loyalty memberships | | [Delete loyalty memberships](/connector-api/operations/loyaltymemberships#delete-loyalty-memberships) | Deletes selected loyalty memberships | | [Get all loyalty tiers](/connector-api/operations/loyaltytiers#get-all-loyalty-tiers) | Returns all loyalty tiers of the enterprise | | [Add loyalty tiers](/connector-api/operations/loyaltytiers#add-loyalty-tiers) | Adds new loyalty tiers | | [Update loyalty tiers](/connector-api/operations/loyaltytiers#update-loyalty-tiers) | Updates selected loyalty tiers | | [Delete loyalty tiers](/connector-api/operations/loyaltytiers#delete-loyalty-tiers) | Deletes selected loyalty tiers | ## Customer messaging | Operation | Description | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | [Get all message threads](/connector-api/operations/messagethreads#get-all-message-threads) | Get all message threads that you have created | | [Add message thread](/connector-api/operations/messagethreads#add-message-thread) | Creates a new message thread on behalf of the specified customer | | [Get all messages](/connector-api/operations/messages#get-all-messages) | Get all messages belonging to the specified message threads | | [Add messages](/connector-api/operations/messages#add-messages) | Add the specified messages to the specified message threads | ## Reservations | Operation | Description | | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Get all reservations (ver 2023-06-06)](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) | Returns all reservations specified by filters | | [~~Get all reservations (ver 2017-04-12)~~](/connector-api/operations/reservations#get-all-reservations-ver-2017-04-12) | **Deprecated!** Please use [Get all reservations (ver 2023-06-06)](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) instead. | | [~~Get all reservation items~~](/connector-api/operations/reservations#get-all-reservation-items) | **Deprecated!** Please use [Get all order items](/connector-api/operations/orderitems#get-all-order-items) instead. | | [Price reservations](/connector-api/operations/reservations#price-reservations) | Returns prices of reservations with the specified parameters | | [Add reservations](/connector-api/operations/reservations#add-reservations) | Adds the specified reservations as a single group | | [Update reservations](/connector-api/operations/reservations#update-reservations) | Updates information about the specified reservations | | [Confirm reservations](/connector-api/operations/reservations#confirm-reservations) | Marks all specified reservations as `Confirmed` | | [Start reservation](/connector-api/operations/reservations#start-reservation) | Marks a reservation as `Started` (checked in) | | [Process reservation](/connector-api/operations/reservations#process-reservation) | Marks a reservation as `Processed` (checked out) | | [Cancel reservation](/connector-api/operations/reservations#cancel-reservation) | Cancels all reservation with specified identifiers | | [Update reservation customer](/connector-api/operations/reservations#update-reservation-customer) | Updates customer of a reservation | | [Update reservation interval](/connector-api/operations/reservations#update-reservation-interval) | Updates reservation interval (start, end or both) | | [Add reservation companion](/connector-api/operations/reservations#add-reservation-companion) | Adds a customer as a companion to the reservation | | [Delete reservation companion](/connector-api/operations/reservations#delete-reservation-companion) | Removes customer companionship from the reservation | | [Add reservation product](/connector-api/operations/reservations#add-reservation-product) | Adds a new product order of the specified product to the reservation | | [Get all source assignments (ver 2024-09-20)](/connector-api/operations/sourceassignments#get-all-source-assignments-ver-2024-09-20) | **Restricted!** Returns all sources associated with a reservation | | [Get all source assignments](/connector-api/operations/sourceassignments#get-all-source-assignments) | Returns all sources associated with a reservation group | | [Get all sources](/connector-api/operations/sources#get-all-sources) | Returns all possible reservation sources | | [Get all reservation groups](/connector-api/operations/reservationgroups#get-all-reservation-groups) | Returns all reservation groups, filtered by unique identifiers and other filters | | [Get reservations channel manager details](/connector-api/operations/reservations#get-reservations-channel-manager-details) | **Restricted!** Gets requested rate codes for the reservation | ## Routing rules | Operation | Description | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [~~Get all routing rules~~](/connector-api/operations/routingrules#get-all-routing-rules) | **Deprecated!** Use [Get all billing automations](/connector-api/operations/billingautomations#get-all-billing-automations) instead. | | [~~Add routing rules~~](/connector-api/operations/routingrules#add-routing-rules) | **Deprecated!** Use [Add billing automations](/connector-api/operations/billingautomations#add-billing-automations) instead. | | [~~Update routing rules~~](/connector-api/operations/routingrules#update-routing-rules) | **Deprecated!** Use [Update billing automations](/connector-api/operations/billingautomations#update-billing-automations) and [Update billing automation assignments](/connector-api/operations/billingautomations#update-billing-automation-assignments) instead. | | [~~Delete routing rules~~](/connector-api/operations/routingrules#delete-routing-rules) | **Deprecated!** Use [Delete billing automations](/connector-api/operations/billingautomations#delete-billing-automations) instead. | ## Service orders | Operation | Description | | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | [Get all product service orders](/connector-api/operations/productserviceorders#get-all-product-service-orders) | Returns all product service orders | | [Get all service order notes](/connector-api/operations/serviceordernotes#get-all-service-order-notes) | Returns all notes associated with the given service orders | | [Add service order notes](/connector-api/operations/serviceordernotes#add-service-order-notes) | Adds service order notes to a given service order | | [Update service order notes](/connector-api/operations/serviceordernotes#update-service-order-notes) | Updates content of given service order notes | | [Delete service order notes](/connector-api/operations/serviceordernotes#delete-service-order-notes) | Deletes given service order notes | ## Services | Operation | Description | | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | [Get all services](/connector-api/operations/services#get-all-services) | Returns all services offered by the enterprise | | [Get service availability (ver 2024-01-22)](/connector-api/operations/services#get-service-availability-ver-2024-01-22) | Returns selected availability and occupancy metrics of a bookable service in the specified time interval | | [Get service availability](/connector-api/operations/services#get-service-availability) | Returns availability of a bookable service in the specified interval | | [Update service availability](/connector-api/operations/services#update-service-availability) | Updates the number of available resources in the specified resource category by a certain amount | | [Get all availability blocks](/connector-api/operations/availabilityblocks#get-all-availability-blocks) | Returns all availability blocks filtered by services, unique identifiers and other filter | | [Add availability blocks](/connector-api/operations/availabilityblocks#add-availability-blocks) | Adds availability blocks which are used to group related availability updates | | [Update availability blocks](/connector-api/operations/availabilityblocks#update-availability-blocks) | Updates information about the specified availability block | | [Delete availability blocks](/connector-api/operations/availabilityblocks#delete-availability-blocks) | Delete availability blocks | | [Get all availability adjustments](/connector-api/operations/availabilityadjustments#get-all-availability-adjustments) | Get all availability adjustments | | [Get all rules](/connector-api/operations/rules#get-all-rules) | Returns all rules applied with the reservations | | [Get all business segments](/connector-api/operations/businesssegments#get-all-business-segments) | Returns all business segments of the default service provided by the enterprise | | [Get all rates](/connector-api/operations/rates#get-all-rates) | Returns all rates (pricing setups) of the default service provided by the enterprise | | [Add rates](/connector-api/operations/rates#add-rates) | Adds new rates to the enterprise | | [Set rates](/connector-api/operations/rates#set-rates) | **Restricted!** Adds new or updates existing rates | | [Delete rates](/connector-api/operations/rates#delete-rates) | Deletes specified rates | | [Update rate capacity offset pricing](/connector-api/operations/rates#update-rate-capacity-offset-pricing) | Updates capacity offset based pricing for specified rates | | [Get rate pricing](/connector-api/operations/rates#get-rate-pricing) | Returns prices of a rate in the specified interval | | [Update rate price](/connector-api/operations/rates#update-rate-price) | Updates price of a rate in the specified intervals | | [Get all rate groups](/connector-api/operations/rategroups#get-all-rate-groups) | Returns all rate groups filtered by rate groups or other filters | | [Get all restrictions](/connector-api/operations/restrictions#get-all-restrictions) | Returns all restrictions of the default service provided by the enterprise | | [Set restrictions](/connector-api/operations/restrictions#set-restrictions) | Adds new restrictions with the specified conditions | | [Clear restrictions](/connector-api/operations/restrictions#clear-restrictions) | Clears restrictions which meet specified conditions over a specified time interval | | [Add order](/connector-api/operations/orders#add-order) | Creates a new order with the specified products and items | | [Get all companionships](/connector-api/operations/companionships#get-all-companionships) | Returns all companionships based on customers, reservations or reservation groups | | [Get all resource access tokens](/connector-api/operations/resourceaccesstokens#get-all-resource-access-tokens) | Returns all resource access tokens based on resource access tokens, reservations or interval | | [Add resource access tokens](/connector-api/operations/resourceaccesstokens#add-resource-access-tokens) | Adds new resource access tokens with the specified data | | [Update resource access tokens](/connector-api/operations/resourceaccesstokens#update-resource-access-tokens) | Updates resource access token validity intervals and permissions | | [Delete resource access tokens](/connector-api/operations/resourceaccesstokens#delete-resource-access-tokens) | Delete specified resource access tokens | | [Get all vouchers](/connector-api/operations/vouchers#get-all-vouchers) | Returns all rate vouchers filtered by service, voucher code or voucher identifier | | [Add vouchers](/connector-api/operations/vouchers#add-vouchers) | Adds new vouchers with the specified data | | [Update vouchers](/connector-api/operations/vouchers#update-vouchers) | Updates information about the specified vouchers | | [Delete vouchers](/connector-api/operations/vouchers#delete-vouchers) | Delete vouchers | | [Get all voucher codes](/connector-api/operations/vouchercodes#get-all-voucher-codes) | Returns all voucher codes filtered by voucher or other filters | | [Add voucher codes](/connector-api/operations/vouchercodes#add-voucher-codes) | Adds new voucher codes to the voucher | | [Delete voucher codes](/connector-api/operations/vouchercodes#delete-voucher-codes) | Delete voucher codes | | [Get all age categories](/connector-api/operations/agecategories#get-all-age-categories) | Returns all age categories filtered by service | | [Get all cancellation policies](/connector-api/operations/cancellationpolicies#get-all-cancellation-policies) | **Restricted!** Returns all cancellation policies filtered by services, rate groups and other filters | | [Get cancellation policies by reservations](/connector-api/operations/cancellationpolicies#get-cancellation-policies-by-reservations) | **Restricted!** Returns cancellation policies for enterprise grouped by reservation | | [Get cancellation policies by rates](/connector-api/operations/cancellationpolicies#get-cancellation-policies-by-rates) | **Restricted!** Returns cancellation policies for enterprise grouped by rate | | [Get all products](/connector-api/operations/products#get-all-products) | Returns all products filtered by services or product identifier | | [Delete products](/connector-api/operations/products#delete-products) | Deletes specified products | | [Get product pricing](/connector-api/operations/products#get-product-pricing) | **Restricted!** Returns prices for a product for a specified time interval | | [Update product pricing](/connector-api/operations/products#update-product-pricing) | Updates product price for a given interval | | [Get all product categories](/connector-api/operations/productcategories#get-all-product-categories) | Returns all products filtered by services or product category identifier | | [Get all service overbooking limits](/connector-api/operations/serviceoverbookinglimits#get-all-service-overbooking-limits) | **Restricted!** Returns all service overbooking limits | | [Set service overbooking limits](/connector-api/operations/serviceoverbookinglimits#set-service-overbooking-limits) | **Restricted!** Adds new service overbooking limits with the specified conditions | | [Clear service overbooking limits](/connector-api/operations/serviceoverbookinglimits#clear-service-overbooking-limits) | **Restricted!** Clears service overbooking limits which meet specified conditions over a specified time interval | # Common objects These are JSON object definitions and other JSON entities shared by operations across the API. ### Time interval When a time interval is used for **filtering** (for example in parameters such as `CreatedUtc.StartUtc` / `CreatedUtc.EndUtc`), the following rules apply: * **Start equals End (equality mode)**\ If `StartUtc` and `EndUtc` are exactly the same timestamp, the filter is treated as an equality check for that precise moment in time: ``` CreatedUtc == StartUtc ``` This does not represent an interval; only records with `CreatedUtc` equal to that exact instant are returned. * **Start differs from End (interval mode)**\ If `StartUtc` and `EndUtc` are different, the filter is evaluated as a half-open interval: ``` StartUtc <= CreatedUtc < EndUtc ``` In other words, the start is inclusive and the end is exclusive. Make sure your integration takes inclusive Start / exclusive End behavior of time intervals into account so that no records at the boundaries are omitted. ```javascript { "StartUtc": "2020-01-05T00:00:00Z", "EndUtc": "2020-01-10T00:00:00Z" } ``` | Property | Type | Contract | Description | | ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `StartUtc` | string | required | Start of the interval in UTC timezone in ISO 8601 format (see [Datetimes](/connector-api/guidelines/serialization#datetimes)). | | `EndUtc` | string | required | End of the interval in UTC timezone in ISO 8601 format (see [Datetimes](/connector-api/guidelines/serialization#datetimes)). | #### Date interval ```javascript { "Start": "2025-09-01", "End": "2025-09-15" } ``` | Property | Type | Contract | Description | | -------- | ------ | -------- | ------------------------------------------------- | | `Start` | string | required | Starting date of the interval in ISO 8601 format. | | `End` | string | required | Ending date of the interval in ISO 8601 format. | ### String update value ```javascript { "Value": "182a56ee-037d-4da5-b6f8-ada8006e7d5c" } ``` | Property | Type | Contract | Description | | -------- | ------ | -------- | ----------------------------- | | `Value` | string | optional | Value which is to be updated. | ### Bool update value ```javascript { "Value": false } ``` | Property | Type | Contract | Description | | -------- | ------- | -------- | ----------------------------- | | `Value` | boolean | optional | Value which is to be updated. | ### Number update value ```javascript { "Value": 6 } ``` | Property | Type | Contract | Description | | -------- | ------ | -------- | ----------------------------- | | `Value` | number | optional | Value which is to be updated. | ### Integer update value ```javascript { "Value": 5 } ``` | Property | Type | Contract | Description | | -------- | ------- | -------- | ----------------------------- | | `Value` | integer | optional | Value which is to be updated. | ### Array of strings update value ```javascript { "Value": [ "182a56ee-037d-4da5-b6f8-ada8006e7d5c", "4a1a7f12-4024-41ba-9289-f90448682d3a" ] } ``` | Property | Type | Contract | Description | | -------- | ---------------- | -------- | ----------------------------- | | `Value` | array of strings | optional | Value which is to be updated. | ### Dictionary Dictionary is a collection of key-value pairs, where both keys and values are strings. ```javascript { "TaxIdentifier": "CZ8810310963", "CityOfRegistration": "Prague" } ``` | Property | Type | Contract | Description | | -------- | ------ | -------- | ------------------------------------------------------------------------ | | ?Key? | string | optional | Some value corresponding to the ?Key? unique identifier. Cannot be null. | ### Dictionary of numbers Dictionary of numbers is a collection of key-value pairs, where keys are strings and the values are numbers. ```javascript { "Amex": 0.05, "MasterCard": 9, } ``` ### Dictionary of integer arrays Dictionary of integer arrays is a collection of key-value pairs, where keys are strings and the values are arrays of integers. ```javascript { "OutOfOrderBlocks": [0, 1, 0, 0, 1], "PublicAvailabilityAdjustment": [7, 5, 4, 3, 4] } ``` | Property | Type | Contract | Description | | -------- | ---------------- | -------- | ------------------------------------------------------------------------------------- | | ?Key? | array of integer | optional | A set of integer values corresponding to the ?Key? unique identifier. Cannot be null. | ### Activity state * `Active` - indicates active record. * `Deleted`- indicates deleted record. ### Localized text A [Dictionary](#dictionary) object where the keys are [Language](/connector-api/operations/languages#language) codes and the corresponding values are versions of the text in the respective language. For example: ```javascript { "cs-CZ": "Děti", "da-DK": "Børn", "de-CH": "Kinder", "de-DE": "Kinder", "el-GR": "Παιδιά", "en-GB": "Children" } ``` ### Profile data | Property | Type | Contract | Description | | ------------------- | --------------------------------------------------------- | -------- | ------------------------- | | `Discriminator` | [Profile data discriminator](#profile-data-discriminator) | required | Type of the profile data. | | `EnterpriseProfile` | [Enterprise profile data](#enterprise-profile-data) | optional | Enterprise profile data. | #### Profile data discriminator * `Personal` * `Enterprise` * `Platform` * `Static` * `Integration` #### Enterprise profile data | Property | Type | Contract | Description | | ----------- | ------ | -------- | --------------------------------- | | `ProfileId` | string | required | Unique identifier of the profile. | ### Amount | Property | Type | Contract | Description | | ------------ | -------------------------------- | -------- | ------------------------------------------------------------------------------- | | `Currency` | string | required | ISO-4217 code of the [Currency](/connector-api/operations/currencies#currency). | | `NetValue` | number | required | Net value without taxes. | | `GrossValue` | number | required | Gross value including all taxes. | | `TaxValues` | array of [Tax value](#tax-value) | required | The tax values applied. | | `Breakdown` | [Tax breakdown](#tax-breakdown) | required | Information about individual tax amounts. | #### Tax value | Property | Type | Contract | Description | | -------- | ------ | -------- | ------------------------------- | | `Code` | string | optional | Code corresponding to tax type. | | `Value` | number | required | Amount of tax applied. | #### Tax breakdown | Property | Type | Contract | Description | | -------- | -------------------------------------------------- | -------- | ---------------------------------------------- | | `Items` | array of [Tax breakdown item](#tax-breakdown-item) | required | Tax breakdown items per each tax rate applied. | #### Tax breakdown item | Property | Type | Contract | Description | | ------------- | ------ | -------- | ------------------------------------------------------- | | `TaxRateCode` | string | optional | Tax rate code for the item. `null` for untaxed amounts. | | `NetValue` | number | required | The net value that the tax is calculated from. | | `TaxValue` | number | required | The value of the tax. | #### Amount parameters | Property | Type | Contract | Description | | ------------ | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GrossValue` | decimal | optional | Amount including tax. Required for Gross [Pricing](/connector-api/operations/configuration#pricing) environments. | | `NetValue` | decimal | optional | Amount excluding tax. Required for Net [Pricing](/connector-api/operations/configuration#pricing) environments. | | `Currency` | string | required | ISO-4217 code of the [Currency](/connector-api/operations/currencies#currency). | | `TaxCodes` | array of string | required | Codes of [Tax rates](/connector-api/operations/taxations#tax-rate) to be applied to the item. (Note, you can only define one tax when sending `GrossValue`. For multiple taxes, use `NetValue`) | ### Hybrid identifier A hybrid identifier is a string with a specific format that allows the use of alternative unique identifiers, in addition to the entity's unique identifier. When using these alternative identifiers, a corresponding prefix must be included as part of the value. | Identifier | Prefix | Value example | Description | | ------------------- | ----------- | -------------------------------------- | ------------------------------------------------------------------------------- | | Primary identifier | (no prefix) | `a01bc7c3-cfa2-4ad6-a360-5cb8b4004ab5` | Primary identifier of the entity e.g. `Id` field on `Service`. | | External identifier | `eid:` | `eid:COM-123` | External identifier of the entity e.g. `ExternalIdentifier` field on `Service`. | ### Currency value (ver 2018-06-07) Usage of this value is **deprecated**. Where possible, use the properties exposing the [Amount](#amount) instead. | Property | Type | Contract | Description | | ------------- | ---------- | ------------ | -------------------------------- | | `Currency` | string | required | ISO-4217 code of the `Currency`. | | `Value` | number | optional | Amount in the currency. | | ~~`Net`~~ | ~~number~~ | ~~optional~~ | **Deprecated!** | | ~~`Tax`~~ | ~~number~~ | ~~optional~~ | **Deprecated!** | | ~~`TaxRate`~~ | ~~number~~ | ~~optional~~ | **Deprecated!** | #### Currency value (ver 2023-02-02) | Property | Type | Contract | Description | | ---------- | ------ | -------- | ----------- | | `Currency` | string | required | | | `Value` | number | required | | #### Activity state * `Deleted` * `Active` # Accounting categories ## Get all accounting categories Returns all accounting categories of the enterprise associated with the connector integration. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/accountingCategories/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "AccountingCategoryIds": [ "0cf7aa90-736f-43e9-a7dc-787704548d86", "0b9560fb-055d-47d3-a6d4-e579c44ca558" ], "UpdatedUtc": { "StartUtc": "2023-10-01T00:00:00Z", "EndUtc": "2023-10-31T00:00:00Z" }, "ActivityStates": [ "Active" ], "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. | | `AccountingCategoryIds` | array of string | optional, max 1000 items | Unique identifiers of the requested [Accounting categories](#accounting-category). | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Last update date and time of the accounting category in UTC timezone in ISO 8601 format. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted or both records. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "AccountingCategories": [ { "Classification": "Accommodation", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Code": "345", "CostCenterCode": "2589", "ExternalCode": "3010", "Id": "0cf7aa90-736f-43e9-a7dc-787704548d86", "IsActive": true, "LedgerAccountCode": "311100", "Name": "Accommodation", "PostingAccountCode": "602020", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z" }, { "Classification": null, "EnterpriseId": "4d0201db-36f5-428b-8d11-4f0a65e960cc", "Code": "100", "CostCenterCode": "2589", "ExternalCode": "ABVG", "Id": "0b9560fb-055d-47d3-a6d4-e579c44ca558", "IsActive": true, "LedgerAccountCode": "311100", "Name": "Alcoholic Beverage", "PostingAccountCode": "602020", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z" } ], "Cursor": "0b9560fb-055d-47d3-a6d4-e579c44ca558" } ``` | Property | Type | Contract | Description | | ---------------------- | ---------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AccountingCategories` | array of [Accounting category](#accounting-category) | required | Accounting categories of 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. | #### Accounting category | Property | Type | Contract | Description | | -------------------- | ------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the category. | | `EnterpriseId` | string | required | Unique identifier of the [Enterprise](/connector-api/operations/enterprises#enterprise). | | `IsActive` | boolean | required | Whether the accounting category is still active. | | `Name` | string | required | Name of the category. | | `Code` | string | optional | Code of the category within Mews. | | `ExternalCode` | string | optional | Code of the category in external systems. | | `LedgerAccountCode` | string | optional | Code of the ledger account (double entry accounting). | | `PostingAccountCode` | string | optional | Code of the posting account (double entry accounting). | | `CostCenterCode` | string | optional | Code of cost center. | | `Classification` | [Accounting category classification](#accounting-category-classification) | optional | Classification of the accounting category allowing cross-enterprise reporting. | | `CreatedUtc` | string | required | Creation date and time of the accounting category in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the accounting category in UTC timezone in ISO 8601 format. | #### Accounting category classification * `Accommodation` * `FoodAndBeverage` * `Taxes` * `Payments` * `ExternalRevenue` * `SundryIncome` * `Wellness` * `Sport` * `Technology` * `Facilities` * `Events` * `Tourism` # Accounting items ## ~~Get all accounting items~~ > #### Deprecated! > > This operation is [deprecated](/connector-api/deprecations). Use [Get all payments](/connector-api/operations/payments#get-all-payments) and [Get all order items](/connector-api/operations/orderitems#get-all-order-items) instead. ### Request `[PlatformAddress]/api/connector/v1/accountingItems/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ConsumedUtc": { "StartUtc": "2020-01-05T00:00:00Z", "EndUtc": "2020-01-10T00:00:00Z" }, "ClosedUtc": { "StartUtc": "2020-01-05T00:00:00Z", "EndUtc": "2020-01-10T00:00:00Z" }, "UpdatedUtc": { "StartUtc": "2020-01-05T00:00:00Z", "EndUtc": "2020-01-10T00:00:00Z" }, "ItemIds": [ "cb643cb7-8b6e-48a6-b67e-ad4c0041f550", "44ca12b8-f009-455e-be91-ad4c013fcbc5" ], "Extent": { "OrderItems": true, "PaymentItems": true, "CreditCardTransactions": false }, "States": [ "Open" ] } ``` | 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. | | `Extent` | [Accounting item extent](#accounting-item-extent) | required | Extent of data to be returned. E.g. it is possible to specify that together with the accounting items, credit card transactions should be also returned. | | `ItemIds` | array of string | optional, max 1000 items | Unique identifiers of the Accounting items. Required if no other filter is provided. | | `RebatedItemIds` | array of string | optional, max 1000 items | Unique identifiers of the Accounting items we are finding rebates for. Required if no other filter is provided. | | `ClosedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the accounting item was closed. Required if no other filter is provided. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the accounting item was updated. Required if no other filter is provided. | | `ConsumedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the accounting item was consumed. Required if no other filter is provided. | | `Currency` | string | optional | ISO-4217 code of the `Currency` the item costs should be converted to. | | `States` | array of [Order item accounting state](#order-item-accounting-state) | optional | States the accounting items should be in. If not specified, accounting items in `Open` or `Closed` states are returned. | #### Accounting item extent | Property | Type | Contract | Description | | ------------------------ | ------- | -------- | --------------------------------------------------------------------------------------------------- | | `OrderItems` | boolean | required | Whether the response should contain order items (consumed items such as nights or products). | | `PaymentItems` | boolean | required | Whether the response should contain payment items (such as cash, credit card payments or invoices). | | `CreditCardTransactions` | boolean | required | Whether the response should contain credit card transactions of the payment items. | #### Order item accounting state * `Open` - Order items which carry a non-zero value, are open, and have not been closed on a bill or invoice. * `Closed` - Order items which carry a non-zero value and have been closed on a bill or invoice. * `Inactive` - Order items which are either of zero value and have not been canceled, if the state of the payment item is Pending or Failed, or items of optional reservations. Until the reservation is confirmed, all its accounting items are Inactive. * `Canceled` - Order items which have been canceled, regardless of whether the item is of zero value. ### Response ```javascript { "OrderItems": [ { "Id": "cb643cb7-8b6e-48a6-b67e-ad4c0041f550", "AccountId": "77673c9d-0e31-4e90-9228-ad4b00a9fcdc", "OrderId": "1103b431-998a-4b78-84de-ad4b00a9fd99", "BillId": null, "AccountingCategoryId": "d250149e-a29d-4c70-b607-a1759faf7320", "UnitCount": 15, "UnitAmount": { "Currency": "EUR", "NetValue": 8.4, "GrossValue": 10, "TaxValues": [ { "Code": "DE-2020-1-I", "Value": 1.6 } ], "Breakdown": { "Items": [ { "TaxRateCode": "DE-2020-1-I", "NetValue": 8.4, "TaxValue": 1.6 } ] } }, "Amount": { "Value": 150, "Net": 126.05, "Tax": 23.95, "TaxRate": 19, "Currency": "EUR", "NetValue": 126.05, "GrossValue": 150, "TaxValues": [ { "Code": "DE-2020-1-I", "Value": 23.95 } ], "Breakdown": { "Items": [ { "TaxRateCode": "DE-2020-1-I", "NetValue": 126.05, "TaxValue": 23.95 } ] } }, "OriginalAmount": { "Value": 150, "Net": 126.05, "Tax": 23.95, "TaxRate": 19, "Currency": "EUR", "NetValue": 126.05, "GrossValue": 150, "TaxValues": [ { "Code": "DE-2020-1-I", "Value": 23.95 } ], "Breakdown": { "Items": [ { "TaxRateCode": "DE-2020-1-I", "NetValue": 126.05, "TaxValue": 23.95 } ] } }, "RevenueType": "Additional", "CreatorProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf", "UpdaterProfileId": "122fc063-ec6e-4198-b8db-6b168a59ffae", "CreatedUtc": "2021-06-19T00:00:00Z", "UpdatedUtc": "2021-06-19T00:00:00Z", "ConsumedUtc": "2021-06-19T04:00:08Z", "CanceledUtc": null, "ClosedUtc": null, "StartUtc": null, "AccountingState": "Open", "Data": { "Discriminator": "CancellationFee", "Value": null } } ], "PaymentItems": [ { "Id": "44ca12b8-f009-455e-be91-ad4c013fcbc5", "AccountId": "5da55e5c-18e5-48d8-9a0e-ac0600704c5c", "BillId": null, "AccountingCategoryId": "b89345c1-2814-4750-808d-aa7900ee464a", "Amount": { "Value": 850, "Net": 850, "Tax": 0, "TaxRate": 0, "Currency": "GBP", "NetValue": 850, "GrossValue": 850, "TaxValues": [], "Breakdown": { "Items": [ { "TaxRateCode": null, "NetValue": 850, "TaxValue": 0 } ] } }, "OriginalAmount": { "Value": 850, "Net": 850, "Tax": 0, "TaxRate": 0, "Currency": "GBP", "NetValue": 850, "GrossValue": 850, "TaxValues": [], "Breakdown": { "Items": [ { "TaxRateCode": null, "NetValue": 850, "TaxValue": 0 } ] } }, "AmountDefault": null, "Notes": "NORMAL0140", "SettlementId": "po_1Lun9w4JpyDC38oQJQz7hAcx", "ConsumedUtc": "2021-06-19T19:24:20Z", "ClosedUtc": null, "AccountingState": "Open", "State": "Charged", "Identifier": null, "Data": { "Discriminator": "Invoice", "Value": { "InvoiceId": "3c818013-d9de-47e9-bb2c-ad4c013f9ad3" } } } ], "CreditCardTransactions": null } ``` | Property | Type | Contract | Description | | ------------------------ | ---------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------- | | `OrderItems` | array of [Order item](#order-item) | optional | The order items (consumed items such as nights or products). | | `PaymentItems` | array of [Payment item](#payment-item) | optional | The payment items (such as cash, credit card payments or invoices). | | `CreditCardTransactions` | array of [Credit card transaction](/connector-api/operations/payments#credit-card-transaction) | optional | The credit card payment transactions. | ## Update accounting items Updates specified accounting items. You can use this operation to assign an accounting item to a different account or bill. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). > **State Restrictions**: Only accounting items in specific states can be moved: > > * **Order items**: Must be in `Open` state > * **Payments**: Must be in `Pending` state > > Attempting to move items in other states (e.g., `Closed`, `Inactive`, `Charged`, `Failed`, `Canceled`) will result in an `Invalid AccountingItemId` error. ### Request `[PlatformAddress]/api/connector/v1/accountingItems/update` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "AccountingItemUpdates": [ { "AccountingItemId": "6c2897de-620a-4f48-af1e-ada8004202bd", "AccountId": { "Value": "182a56ee-037d-4da5-b6f8-ada8006e7d5c" }, "BillId": { "Value": "9e3791dc-95c7-439a-aa8a-ada8007de0ca" } } ] } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `AccountingItemUpdates` | array of [Accounting item update](#accounting-item-update) | required | List of requested updates. | #### Accounting item update | Property | Type | Contract | Description | | ------------------ | ----------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AccountingItemId` | string | required | Unique identifier of the `AccountingItem`. | | `AccountId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique identifier of the account (for example `Customer`) the item is assigned to (or `null` if the assigned account should not be updated). If defined, valid account identifier must be provided. | | `BillId` | [String update value](/connector-api/operations/_objects#string-update-value) | required | Unique identifier of the `Bill` the items is assigned to. It's possible to assign item to bill belonging to another account, in that case both `AccountId` and `BillId` must be provided. | ### Response ```javascript { "OrderItems": [ { "Id": "6c2897de-620a-4f48-af1e-ada8004202bd", "AccountId": "182a56ee-037d-4da5-b6f8-ada8006e7d5c", "OrderId": "f9090129-fb49-46d2-9dc5-ad9d015d43b9", "BillId": "9e3791dc-95c7-439a-aa8a-ada8007de0ca", "AccountingCategoryId": "d250149e-a29d-4c70-b607-a1759faf7320", "Amount": { "Currency": "GBP", "NetValue": 95.24, "GrossValue": 100, "TaxValues": [ { "Code": "UK-2020-R", "Value": 4.76 } ], "Breakdown": { "Items": [ { "TaxRateCode": "UK-2020-R", "NetValue": 95.24, "TaxValue": 4.76 } ] } }, "RevenueType": "Additional", "ConsumedUtc": "2021-09-19T04:00:20Z", "ClosedUtc": null, "AccountingState": "Open", "Data": { "Discriminator": "CancellationFee", "Value": null } } ], "PaymentItems": [] } ``` | Property | Type | Contract | Description | | -------------- | -------------------------------------- | -------- | ---------------------- | | `OrderItems` | array of [Order item](#order-item) | optional | Updated order items. | | `PaymentItems` | array of [Payment item](#payment-item) | optional | Updated payment items. | #### Order item | Property | Type | Contract | Description | | ---------------------- | ------------------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the item. | | `AccountId` | string | required | Unique identifier of the account (for example `Customer`) the item belongs to. | | `OrderId` | string | required | Unique identifier of the order (or `Reservation` which is a special type of order) the item belongs to. | | `BillId` | string | optional | Unique identifier of the `Bill` the item is assigned to. | | `AccountingCategoryId` | string | optional | Unique identifier of the `AccountingCategory` the item belongs to. | | `UnitCount` | integer | required | Unit count of item, i.e. the number of sub-items or units, if applicable. | | `UnitAmount` | [Amount](/connector-api/operations/_objects#amount) | required | Unit amount of item, i.e. the amount of each individual sub-item or unit, if applicable. | | `Amount` | [Extended amount](/connector-api/operations/_objects#amount) | required | Amount of item; note a negative amount represents a rebate or payment. | | `OriginalAmount` | [Extended amount](/connector-api/operations/_objects#amount) | required | Amount of item; note a negative amount represents a rebate or payment. Contains the earliest known value in conversion chain. | | `RevenueType` | string | required | Revenue type of the item. | | `CreatorProfileId` | string | required | Unique identifier of the user who created the item. | | `UpdaterProfileId` | string | required | Unique identifier of the user who updated the item. | | `CreatedUtc` | string | required | Creation date and time of the item in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the item in UTC timezone in ISO 8601 format. | | `ConsumedUtc` | string | optional | Date and time of the item consumption in UTC timezone in ISO 8601 format. | | `CanceledUtc` | string | optional | Cancellation date and time of the item in UTC timezone in ISO 8601 format. | | `ClosedUtc` | string | optional | Date and time of the item bill closure in UTC timezone in ISO 8601 format. | | `StartUtc` | string | optional | Start date and time of the item in UTC timezone in ISO 8601 format. | | `AccountingState` | string | required | Accounting state of the item. | | `Data` | [Order item data](#order-item-data) | required | Additional data specific to particular order item. | #### Order item data | Property | Type | Contract | Description | | --------------- | --------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------- | | `Discriminator` | [Order item data discriminator](#order-item-data-discriminator) | required | Determines type of value. | | `Value` | object | optional | Based on order item discriminator or `null` for types without any additional data. | #### Order item data discriminator * `CancellationFee` - No additional data. * `Rebate` - [Rebate order item data](#rebate-order-item-data) * `Deposit` - No additional data. * `ExchangeRateDifference` - No additional data. * `CustomItem` - No additional data. * `Surcharge` - No additional data. * `SurchargeDiscount` - No additional data. * `SpaceOrder` - No additional data. * `ProductOrder` - [Product order item data](#product-order-item-data) * `Other` - No additional data. * `TaxCorrection` - No additional data. * `ResourceUpgradeFee` - No additional data. * `InvoiceFee` - No additional data. #### Rebate order item data | Property | Type | Contract | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------ | | `RebatedItemId` | string | required | Unique identifier of `OrderItem` which has been rebated by current item. | #### Payment item | Property | Type | Contract | Description | | ---------------------- | ---------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the item. | | `AccountId` | string | required | Unique identifier of the account (for example `Customer`) the item belongs to. | | `BillId` | string | optional | Unique identifier of the `Bill` the item is assigned to. | | `AccountingCategoryId` | string | optional | Unique identifier of the `AccountingCategory` the item belongs to. | | `Amount` | [Extended amount](/connector-api/operations/_objects#amount) | required | Item's amount, negative amount represents either rebate or a payment. | | `OriginalAmount` | [Extended amount](/connector-api/operations/_objects#amount) | required | Amount of item; note a negative amount represents a rebate or payment. Contains the earliest known value in conversion chain. | | `Notes` | string | optional | Additional notes. | | `SettlementId` | string | optional | Identifier of the settled payment from the external system (ApplePay/GooglePay). | | `ConsumedUtc` | string | required | Date and time of the item consumption in UTC timezone in ISO 8601 format. | | `ClosedUtc` | string | optional | Date and time of the item bill closure in UTC timezone in ISO 8601 format. | | `AccountingState` | string | required | Accounting state of the item. | | `State` | string | required | Payment state of the item. | | `Identifier` | string | optional | External payment identifier. | | `Data` | [Payment item data](#payment-item-data) | required | Additional data specific to particular payment item. | | ~~`AmountDefault`~~ | [~~Extended amount~~](/connector-api/operations/_objects#amount) | ~~optional~~ | ~~Item's amount in property's default currency, negative amount represents either rebate or a payment.~~ **Deprecated!** | #### Payment item data | Property | Type | Contract | Description | | --------------- | ------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- | | `Discriminator` | [Payment item data discriminator](#payment-item-data-discriminator) | required | Determines type of value. | | `Value` | object | optional | Based on payment item data discriminator or `null` for types without any additional data. | #### Payment item data discriminator * `CreditCard` - [Credit card payment item data](#credit-card-payment-item-data) * `Invoice` - [Invoice payment item data](#invoice-payment-item-data) * `Cash` - No additional data. * `Unspecified` - No additional data. * `BadDebts` - No additional data. * `WireTransfer` - No additional data. * `ExchangeRateDifference` - No additional data. * `ExchangeRoundingDifference` - No additional data. * `BankCharges` - No additional data. * `Cheque` - No additional data. * `Other` - No additional data. #### Credit card payment item data | Property | Type | Contract | Description | | --------------- | ------ | -------- | -------------------------------------- | | `PaymentCardId` | string | optional | Unique identifier of the `CreditCard`. | # Accounts ## Update accounts Updates one or more existing accounts in the system. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/accounts/update` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "AccountUpdates": [ { "Id": "3ff104e6-3ba8-4dfc-8d35-b0ec00c5fd4c", "Discriminator": "Company", "Customer": null, "Company": { "Email": { "Value": "example@example.com" }, "TaxIdentifier": { "Value": "CZ8810310963" }, "BillingCode": { "Value": null }, "AccountingCode": { "Value": null }, "Notes": { "Value": "Example notes" }, "Name": { "Value": "Example company" }, "MotherCompanyId": { "Value": "839e9d92-aa8b-48bf-8384-b0ec0081bb34" }, "WebsiteUrl": { "Value": "https://www.example.com" }, "InvoiceDueInterval": { "Value": null }, "CreditRatingBasic": { "Value": "CreditOk" }, "Department": { "Value": "Accounting" }, "DunsNumber": { "Value": "987654321" }, "ReferenceId": { "Value": null }, "ExternalIdentifier": { "Value": "COM-123" }, "AdditionalTaxIdentifier": { "Value": "XY00112233445" }, "Contact": { "Value": "Sample contact" }, "ContactPerson": { "Value": "Sample person" }, "FiscalIdentifier": { "Value": "FiscalIdentifier" }, "Iata": { "Value": "PAO" }, "Telephone": { "Value": "111-222-333" }, "SourceId": { "Value": "F42098A0-8507-4963-ACC9-B0EC00821949" }, "Classifications": { "Corporate": { "Value": true }, "Internal": { "Value": true }, "Private": { "Value": true }, "OnlineTravelAgency": { "Value": true }, "GlobalDistributionSystem": { "Value": true }, "Marketing": { "Value": true }, "Inactive": { "Value": true } }, "Options": { "Invoiceable": { "Value": "true" }, "AddFeesToInvoices": { "Value": "true" } } } }, { "Id": "71db411f-c1d6-4e1c-9cd7-44e8bf45f936", "Discriminator": "Customer", "Company": null, "Customer": { "Email": { "Value": "example@example.com" }, "TaxIdentifier": { "Value": "CZ8810310963" }, "BillingCode": { "Value": null }, "AccountingCode": { "Value": null }, "Notes": { "Value": "Example notes" }, "LastName": { "Value": "Sample" }, "FirstName": { "Value": "Sample" }, "SecondLastName": { "Value": null }, "BirthPlace": { "Value": "Sample place" }, "Telephone": { "Value": "111-222-333" }, "Occupation": { "Value": null }, "CarRegistrationNumber": { "Value": null }, "LoyaltyCode": { "Value": null }, "NationalityCode": { "Value": "US" }, "CompanyId": { "Value": "839e9d92-aa8b-48bf-8384-b0ec0081bb34" }, "BirthDate": { "Value": "2000-01-01" }, "Sex": { "Value": "Male" }, "Title": { "Value": "Mister" }, "PreferredLanguageCode": { "Value": null }, "Options": { "SendMarketingEmails": { "Value": true }, "Invoiceable": { "Value": true }, "BillAddressObjection": { "Value": true } }, "Classifications": { "PaymasterAccount": { "Value": true }, "Blacklist": { "Value": true }, "Media": { "Value": true }, "LoyaltyProgram": { "Value": true }, "PreviousComplaint": { "Value": true }, "Returning": { "Value": true }, "Staff": { "Value": true }, "FriendOrFamily": { "Value": true }, "TopManagement": { "Value": true }, "Important": { "Value": true }, "VeryImportant": { "Value": true }, "Problematic": { "Value": true }, "Cashlist": { "Value": true }, "DisabledPerson": { "Value": true }, "Military": { "Value": true }, "Airline": { "Value": true }, "HealthCompliant": { "Value": true }, "InRoom": { "Value": true }, "WaitingForRoom": { "Value": true }, "Student": { "Value": true } }, "LegalEntityIdentifiers": { "ItDestinationCode": { "Value": null }, "ItFiscalCode": { "Value": 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `AccountUpdates` | array of [Account update parameters](#account-update-parameters) | required, max 1000 items | Accounts to be updated. | #### Account update parameters | Property | Type | Contract | Description | | --------------- | --------------------------------------------------------- | -------- | ------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the account. | | `Discriminator` | [Account type discriminator](#account-type-discriminator) | required | Type of the account. | | `Customer` | [Customer update parameters](#customer-update-parameters) | optional | Customer data to be updated. Required when `Discriminator` is `Customer`. | | `Company` | [Company update parameters](#company-update-parameters) | optional | Company data to be updated. Required when `Discriminator` is `Company`. | #### Account type discriminator * `Customer` * `Company` #### Customer update parameters | Property | Type | Contract | Description | | ------------------------ | ------------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------- | | `Email` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Email address (or `null` if the email should not be updated). | | `TaxIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Tax identification number (or `null` if the tax identification number should not be updated). | | `BillingCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Billing code (or `null` if the billing code should not be updated). | | `AccountingCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Accounting code (or `null` if the accounting code should not be updated). | | `Notes` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Notes (or `null` if the notes should not be updated). | | `LastName` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Last name (or `null` if the last name should not be updated). | | `FirstName` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | First name (or `null` if the first name should not be updated). | | `SecondLastName` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Second last name (or `null` if the second last name should not be updated). | | `BirthPlace` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Birth place (or `null` if the birth place should not be updated). | | `Telephone` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Telephone number (or `null` if the telephone should not be updated). | | `Occupation` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Occupation (or `null` if the occupation should not be updated). | | `CarRegistrationNumber` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 255 characters | Car registration number (or `null` if the car registration number should not be updated). | | `DietaryRequirements` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 255 characters | Dietary requirements (or `null` if the dietary requirements should not be updated). | | `LoyaltyCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Loyalty code (or `null` if the loyalty code should not be updated). | | `NationalityCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Nationality code (or `null` if the nationality code should not be updated). | | `CompanyId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique identifier of the company (or `null` if the company should not be updated). | | `BirthDate` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Birth date (or `null` if the birth date should not be updated). | | `Sex` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Sex (or `null` if the sex should not be updated). | | `Title` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Title (or `null` if the title should not be updated). | | `PreferredLanguageCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Preferred language code (or `null` if the preferred language code should not be updated). | | `Options` | [Customer update options](#customer-update-options) | optional | Options of the customer. | | `Classifications` | [Customer update classifications](#customer-update-classifications) | optional | Classifications of the customer. | | `LegalEntityIdentifiers` | [Customer update legal entity identifiers](#customer-update-legal-entity-identifiers) | optional | Legal entity identifiers of the customer. | #### Customer update options | Property | Type | Contract | Description | | ---------------------- | ------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------- | | `SendMarketingEmails` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Send marketing email (or `null` if the value should not be updated). | | `Invoiceable` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Invoiceable (or `null` if the value should not be updated). | | `BillAddressObjection` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Bill address objection (or `null` if the value should not be updated). | #### Customer update classifications | Property | Type | Contract | Description | | ------------------- | ----------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `PaymasterAccount` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Paymaster account (or `null` if the value should not be updated). | | `Blocklist` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Blocklist (or `null` if the value should not be updated). | | `Media` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Media (or `null` if the value should not be updated). | | `LoyaltyProgram` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Loyalty program (or `null` if the value should not be updated). | | `PreviousComplaint` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Previous complaint (or `null` if the value should not be updated). | | `Returning` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Returning (or `null` if the value should not be updated). | | `Staff` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Staff (or `null` if the value should not be updated). | | `FriendOrFamily` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Friend or family (or `null` if the value should not be updated). | | `TopManagement` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Top management (or `null` if the value should not be updated). | | `Important` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Important (or `null` if the value should not be updated). | | `VeryImportant` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Very important (or `null` if the value should not be updated). | | `Problematic` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Problematic (or `null` if the value should not be updated). | | `Cashlist` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Cashlist (or `null` if the value should not be updated). | | `DisabledPerson` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Disabled person (or `null` if the value should not be updated). | | `Military` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Military (or `null` if the value should not be updated). | | `Airline` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Airline (or `null` if the value should not be updated). | | `HealthCompliant` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Health compliant (or `null` if the value should not be updated). | | `InRoom` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | In room (or `null` if the value should not be updated). | | `WaitingForRoom` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Waiting for room (or `null` if the value should not be updated). | | `Student` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Student (or `null` if the value should not be updated). | | ~~`Blacklist`~~ | [~~Bool update value~~](/connector-api/operations/_objects#bool-update-value) | ~~optional~~ | ~~Synonym of Blocklist, left for backward compatibility (`null` if the value should not be updated).~~ **Deprecated!** Use Blocklist instead. | #### Customer update legal entity identifiers | Property | Type | Contract | Description | | ------------------- | ----------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------- | | `ItDestinationCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Italian destination code (or `null` if the Italian destination code should not be updated). | | `ItFiscalCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Italian fiscal code (or `null` if the Italian fiscal code should not be updated). | | `ItLotteryCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 15 characters | Italian lottery code (or `null` if the Italian lottery code should not be updated). | #### Company update parameters | Property | Type | Contract | Description | | ------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------- | | `Email` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Email address (or `null` if the email should not be updated). | | `TaxIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Tax identification number (or `null` if the tax identification number should not be updated). | | `BillingCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Billing code (or `null` if the billing code should not be updated). | | `AccountingCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Accounting code (or `null` if the accounting code should not be updated). | | `Notes` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Notes (or `null` if the notes should not be updated). | | `Name` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Name (or `null` if the name should not be updated). | | `MotherCompanyId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Mother company identifier (or `null` if the mother company identifier should not be updated). | | `WebsiteUrl` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Website url (or `null` if the website url should not be updated). | | `InvoiceDueInterval` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Invoice due interval (or `null` if the invoice due interval should not be updated). | | `Classifications` | [Company update classifications](#company-update-classifications) | optional | Classifications of the company. | | `Options` | [Company update options](/connector-api/operations/companies#company-update-options) | optional | Options of the company. | | `CreditRatingBasic` | [Credit rating basic](#credit-rating-basic) | optional | Basic credit rating (or `null` if the basic credit rating should not be updated). | | `Department` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Department (or `null` if the department should not be updated). | | `DunsNumber` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Duns number (or `null` if the duns number should not be updated). | | `ReferenceId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Reference identifier (or `null` if the reference identifier should not be updated). | | `ExternalIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 255 characters | External identifier (or `null` if the external identifier should not be updated). | | `AdditionalTaxIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Additional tax identifier (or `null` if the additional tax identifier should not be updated). | | `Contact` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Contact (or `null` if the contact should not be updated). | | `ContactPerson` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Contact person (or `null` if the contact person should not be updated). | | `FiscalIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Fiscal identifier (or `null` if the fiscal identifier should not be updated). | | `Iata` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | IATA of the company (or `null` if the iata should not be updated). | | `Telephone` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Telephone number (or `null` if the telephone number should not be updated). | | `SourceId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Source identifier (or `null` if the source identifier should not be updated). | #### Company update classifications | Property | Type | Contract | Description | | -------------------------- | ------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------- | | `Corporate` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Corporate (or `null` if the value should not be updated). | | `Internal` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Internal (or `null` if the value should not be updated). | | `Private` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Private (or `null` if the value should not be updated). | | `OnlineTravelAgency` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Online travel agency (or `null` if the value should not be updated). | | `GlobalDistributionSystem` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Global distribution system (or `null` if the value should not be updated). | | `Marketing` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Marketing (or `null` if the value should not be updated). | | `Inactive` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Inactive (or `null` if the value should not be updated). | | `GovernmentEntity` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Government Entity (or `null` if the value should not be updated). | #### Credit rating basic * `CreditOk` - Company can book services. * `PaymentRequiredUpfront` - Company must pay upfront. * `LocalDecisionRequired` - Requires local approval. ### Response ```javascript { "Accounts": [ { "Id": "3ff104e6-3ba8-4dfc-8d35-b0ec00c5fd4c", "Discriminator": "Company", "Customer": null, "Company": { "ChainId": "79fa3c17-bec6-454f-b3be-b0ec00818acd", "CreatedUtc": "2024-01-03T07:52:20Z", "UpdatedUtc": "2024-01-18T10:20:31Z", "UpdaterProfileId": "93f03906-ed13-4a26-b8dc-b0ec0082194f", "Email": "example@example.com", "TaxIdentifier": "CZ8810310963", "BillingCode": null, "AccountingCode": null, "Notes": "Example notes", "Name": "Example company", "MotherCompanyId": "839e9d92-aa8b-48bf-8384-b0ec0081bb34", "WebsiteUrl": "https://www.example.com", "InvoiceDueInterval": null, "CreditRatingBasic": "CreditOk", "Department": "Accounting", "DunsNumber": "987654321", "ReferenceId": null, "ExternalIdentifier": "COM-123", "AdditionalTaxIdentifier": "XY00112233445", "Contact": "Sample contact", "ContactPerson": "Sample person", "FiscalIdentifier": "FiscalIdentifier", "Iata": "PAO", "Telephone": "111-222-333", "SourceId": "F42098A0-8507-4963-ACC9-B0EC00821949", "Classifications": { "Corporate": true, "Internal": true, "Private": true, "OnlineTravelAgency": true, "GlobalDistributionSystem": true, "Marketing": true, "Inactive": true }, "Options": { "Invoiceable": true, "AddFeesToInvoices": true } } }, { "Id": "71db411f-c1d6-4e1c-9cd7-44e8bf45f936", "Discriminator": "Customer", "Customer": { "ChainId": "79fa3c17-bec6-454f-b3be-b0ec00818acd", "CreatedUtc": "2024-01-03T07:52:19Z", "UpdatedUtc": "2024-01-18T10:25:41Z", "UpdaterProfileId": "93f03906-ed13-4a26-b8dc-b0ec0082194f", "Email": "example@example.com", "TaxIdentifier": "CZ8810310963", "BillingCode": null, "AccountingCode": null, "Notes": "Example notes", "LastName": "Sample", "FirstName": "Sample", "SecondLastName": null, "BirthPlace": "Sample place", "Telephone": "111-222-333", "Occupation": null, "CarRegistrationNumber": null, "LoyaltyCode": null, "NationalityCode": "US", "CompanyId": "839e9d92-aa8b-48bf-8384-b0ec0081bb34", "BirthDate": "2000-01-01T00:00:00Z", "Sex": "Male", "Title": "Mister", "PreferredLanguageCode": null, "Options": { "SendMarketingEmails": true, "Invoiceable": true, "BillAddressObjection": true }, "Classifications": { "PaymasterAccount": true, "Blacklist": true, "Media": true, "LoyaltyProgram": true, "PreviousComplaint": true, "Returning": true, "Staff": true, "FriendOrFamily": true, "TopManagement": true, "Important": true, "VeryImportant": true, "Problematic": true, "Cashlist": true, "DisabledPerson": true, "Military": true, "Airline": true, "HealthCompliant": true, "InRoom": true, "WaitingForRoom": true, "Student": true }, "LegalEntityIdentifiers": { "ItDestinationCode": null, "ItFiscalCode": null } }, "Company": null } ] } ``` | Property | Type | Contract | Description | | ---------- | ---------------------------- | ------------------------ | ----------------- | | `Accounts` | array of [Account](#account) | required, max 1000 items | Updated accounts. | #### Account | Property | Type | Contract | Description | | --------------- | ----------------------------- | -------- | --------------------------------- | | `Id` | string | required | Unique identifier of the account. | | `Discriminator` | [Account type](#account-type) | required | Type of the account. | | `Customer` | [Customer](#customer) | optional | Updated customer data. | | `Company` | [Company](#company) | optional | Updated company data. | #### Account type * `Company` * `Customer` #### Customer Updated customer data. | Property | Type | Contract | Description | | ------------------------ | --------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ChainId` | string | required | Unique identifier of the chain. | | `CreatedUtc` | string | required | Creation date and time of the customer in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the customer in UTC timezone in ISO 8601 format. | | `UpdaterProfileId` | string | required | Unique identifier of the user who updated the customer. | | `Email` | string | optional | Email address of the customer. | | `TaxIdentifier` | string | optional | Tax identification number of the customer. | | `BillingCode` | string | optional | Billing code of the customer. | | `AccountingCode` | string | optional | Accounting code of the customer. | | `Notes` | string | optional | Internal notes about the customer. | | `LastName` | string | required | Last name of the customer. | | `FirstName` | string | optional | First name of the customer. | | `SecondLastName` | string | optional | Second last name of the customer. | | `BirthPlace` | string | optional | Place of birth. | | `Telephone` | string | optional | Telephone number of the customer (possibly mobile). | | `Occupation` | string | optional | Occupation of the customer. | | `CarRegistrationNumber` | string | optional, max length 255 characters | Registration number of the customer's car. | | `DietaryRequirements` | string | optional, max length 255 characters | Dietary requirements of the customer. | | `LoyaltyCode` | string | optional | Loyalty code of the customer. | | `NationalityCode` | string | optional | ISO 3166-1 code of the `Country`. | | `CompanyId` | string | optional | Unique identifier of `Company` the customer is associated with. | | `BirthDate` | string | optional | Date of birth in ISO 8601 format. | | `Sex` | string | optional | Sex of the customer. | | `Title` | [Title](/connector-api/operations/customers#title) | optional | Title prefix of the customer. Mutually exclusive with `CustomTitleName`. | | `CustomTitleName` | string | optional | Name of the customer's custom title, as configured in the chain's guest titles. Mutually exclusive with `Title` – a customer has either a standard title or a custom title. Unlike `Title`, the value is not localized; display it as returned. | | `PreferredLanguageCode` | string | optional | Language and culture code of the customer's preferred language. E.g. `en-US` or `fr-FR`. | | `Options` | [Customer options](#customer-options) | required | Options of the customer. | | `Classifications` | [Customer classifications](#customer-classifications) | required | Classifications of the customer. | | `LegalEntityIdentifiers` | [Customer legal identifiers](#customer-legal-identifiers) | required | Legal entity identifiers of the customer. | #### Customer options | Property | Type | Contract | Description | | ---------------------- | ------- | -------- | ----------------------- | | `SendMarketingEmails` | boolean | required | Send marketing emails. | | `Invoiceable` | boolean | required | Invoiceable. | | `BillAddressObjection` | boolean | required | Bill address objection. | #### Customer classifications | Property | Type | Contract | Description | | ------------------- | ----------- | ------------ | ------------------------------------------------------------------------------------------------- | | `PaymasterAccount` | boolean | required | Paymaster account. | | `Blocklist` | boolean | required | Blocklist. | | `Media` | boolean | required | Media. | | `LoyaltyProgram` | boolean | required | Loyalty program. | | `PreviousComplaint` | boolean | required | Previous complaint. | | `Returning` | boolean | required | Returning. | | `Staff` | boolean | required | Staff. | | `FriendOrFamily` | boolean | required | Friend or family. | | `TopManagement` | boolean | required | Top management. | | `Important` | boolean | required | Important. | | `VeryImportant` | boolean | required | Very important. | | `Problematic` | boolean | required | Problematic. | | `Cashlist` | boolean | required | Cash list. | | `DisabledPerson` | boolean | required | Disabled person. | | `Military` | boolean | required | Military. | | `Airline` | boolean | required | Airline. | | `HealthCompliant` | boolean | required | Health compliant. | | `InRoom` | boolean | required | In room. | | `WaitingForRoom` | boolean | required | Waiting for room. | | `Student` | boolean | required | Student. | | ~~`Blacklist`~~ | ~~boolean~~ | ~~required~~ | ~~Synonym of Blocklist, left for backward compatibility.~~ **Deprecated!** Use Blocklist instead. | #### Customer legal identifiers | Property | Type | Contract | Description | | ------------------- | ------ | ---------------------------------- | ------------------------- | | `ItDestinationCode` | string | optional | Italian destination code. | | `ItFiscalCode` | string | optional | Italian fiscal code. | | `ItLotteryCode` | string | optional, max length 15 characters | Italian lottery code. | #### Company | Property | Type | Contract | Description | | ------------------------- | ------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------- | | `ChainId` | string | required | Unique identifier of the chain. | | `CreatedUtc` | string | required | Creation date and time of the `Company` in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the `Company` in UTC timezone in ISO 8601 format. | | `UpdaterProfileId` | string | required | Unique identifier of the user who updated the company. | | `Email` | string | optional | Email address of the company. | | `TaxIdentifier` | string | optional | Tax identification number of the company. | | `BillingCode` | string | optional | Billing code of the company. | | `AccountingCode` | string | optional | Accounting code of the company. | | `Notes` | string | optional | Additional notes. | | `Name` | string | required | Name of the company. | | `MotherCompanyId` | string | optional | Unique identifier of mother company. | | `WebsiteUrl` | string | optional | The website url of the company. | | `InvoiceDueInterval` | string | optional | The maximum time (in ISO 8601 duration format), when the invoice has to be be paid. | | `CreditRatingBasic` | [Credit rating basic](/connector-api/operations/companies#credit-rating-basic) | optional | Credit rating to define credit worthiness of the company. | | `Department` | string | optional | The internal segmentation of a company, e.g. sales department. | | `DunsNumber` | string | optional | The Dun & Bradstreet unique 9-digit DUNS number. | | `ReferenceId` | string | optional | External system identifier - custom identifier used by an external system such as an external database. | | `ExternalIdentifier` | string | optional | Identifier of company from external system. | | `AdditionalTaxIdentifier` | string | optional | Additional tax identifier of the company. | | `Contact` | string | optional | Other contact details, such as telephone, email or similar. | | `ContactPerson` | string | optional | Contact person of the company. | | `FiscalIdentifier` | string | optional | Fiscal identifier of the company. | | `Iata` | string | optional | Iata of the company. | | `Telephone` | string | optional | Contact telephone number. | | `SourceId` | string | optional | Unique identifier of the `Source`. | | `Classifications` | [Company classifications](#company-classifications) | required | Classifications of the company. | | `Options` | [Company options](#company-options) | required | Options of the company. | #### Company classifications | Property | Type | Contract | Description | | -------------------------- | ------- | -------- | --------------------------- | | `Corporate` | boolean | required | Corporate. | | `Internal` | boolean | required | Internal. | | `Private` | boolean | required | Private. | | `OnlineTravelAgency` | boolean | required | Online travel agency. | | `GlobalDistributionSystem` | boolean | required | Global distribution system. | | `Marketing` | boolean | required | Marketing. | | `Inactive` | boolean | required | Inactive. | | `GovernmentEntity` | boolean | required | Government Entity | #### Company options | Property | Type | Contract | Description | | --------------------------------- | ------- | -------- | ------------------------------------------------------------------------ | | `Invoiceable` | boolean | required | Whether the company is invoiceable or not. | | `AddFeesToInvoices` | boolean | required | Whether the company has an additional fee applied for invoicing or not. | | `AddTaxDeductedPaymentToInvoices` | boolean | required | Whether tax-deducted payments should be automatically added to invoices. | ## Upload and link file to account Attaches the specified file to the account. Allowed MIME types: `application/pdf`, `image/bmp`, `image/gif`, `image/jpeg`, `image/png`, `image/tiff`. Note this operation supports [Portfolio Access Tokens](https://github.com/MewsSystems/open-api-docs/tree/main/connector-api/guidelines/multi-property.md). ### Request `[PlatformAddress]/api/connector/v1/accounts/addFile` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "AccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "document.pdf", "Type": "application/pdf", "ChainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `AccountId` | string | required | Unique identifier of the account to which the file will be uploaded to. | | `Name` | string | required, max length 1000 characters | Uploaded file name. | | `Type` | string | required, max length 1000 characters | Content type of the uploaded file following defined by its MIME type. | | `Data` | string | required | Uploaded file data serialized in base64 format. | ### Response ```javascript { "FileId": "f039f5b4-ff18-4510-9086-92b14a68ed78" } ``` | Property | Type | Contract | Description | | -------- | ------ | -------- | --------------------------------------- | | `FileId` | string | required | Unique identifier of the uploaded file. | ## Merge accounts Merges two or more accounts of the same account type together. The given source accounts will be merged into the given target account and the merged account will keep the target account ID. ### Request `[PlatformAddress]/api/connector/v1/accounts/merge` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "AccountMergeParameters": [ { "AccountType": "Company", "SourceAccountIds": [ "b0c10ced-34eb-44b4-92e8-af5b008f3fb4", "5176d000-bf17-40be-b140-9041d2b70eee" ], "TargetAccountId": "51262225-8130-4320-8210-af5b008f64e5" }, { "AccountType": "Customer", "SourceAccountIds": [ "7799f19a-c9c9-42bf-968f-a759e3ea1ea6", "bb926ffe-5310-48bc-8202-6165fa3bdcad" ], "TargetAccountId": "49b2abd4-df58-4f1d-bead-0fa6342f8a78" } ] } ``` | 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. | | `AccountMergeParameters` | array of [Account merge parameters](#account-merge-parameters) | required, max 10 items | Accounts to be merged. | #### Account merge parameters | Property | Type | Contract | Description | | ------------------ | ----------------------------------------- | ------------------------ | -------------------------------------------------------------------- | | `SourceAccountIds` | array of string | required, max 1000 items | Unique identifiers of the source accounts (`Customer` or `Company`). | | `TargetAccountId` | string | required | Unique identifier of the target account (`Customer` or `Company`). | | `AccountType` | [Account merge type](#account-merge-type) | required | Specifying types of the accounts provided (`Customer` or `Company`). | #### Account merge type * `Customer` * `Company` ### Response ```javascript {} ``` # Account notes ## Get all account notes Returns all account notes of an account, optionally filtered by activity state, account identifiers, specific account note identifiers or other filter parameters. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/accountNotes/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ChainIds": [ "1df21f06-0cfc-4960-9c58-a3bf1261663e", "5fcd1933-22f2-40b9-84da-7db04cbecec2" ], "AccountNoteIds": [ "3ed9e2f3-4bba-4df6-8d41-ab1b009b6425", "8a98965a-7c03-48a1-a28c-ab1b009b53c8" ], "AccountIds": [ "a6738390-c241-45b7-8e46-14f47207abe5", "435d4d5f-d14f-48dc-a47e-0481fc28ead0" ], "UpdatedUtc": { "StartUtc": "2022-10-10T00:00:00Z", "EndUtc": "2022-10-17T00:00:00Z" }, "ActivityStates": [ "Active" ], "Limitation": { "Cursor": "e7f26210-10e7-462e-9da8-ae8300be8ab7", "Count": 100 } } ``` | 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. | | `ChainIds` | array of string | optional, max 1000 items | Unique identifiers of `Chain`. If not specified, the operation returns data for all chains within scope of the Access Token. | | `AccountNoteIds` | array of string | optional, max 1000 items | Unique identifiers of [Account note](#account-note). | | `AccountIds` | array of string | optional, max 1000 items | Unique identifiers of the accounts ([Customer](/connector-api/operations/customers#customer) or [Company](/connector-api/operations/companies#company)). | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval of Account note's last update date and time. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted or both records. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "AccountNotes": [ { "Id": "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "AccountId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "Content": "Customer receives a free bottle of champagne during stay", "AccountType": "Customer", "Classifications": [ "Gifts" ], "IsActive": true, "CreatorProfile": { "Discriminator": "Enterprise", "EnterpriseProfile": { "ProfileId": "52d19c34-b0aa-4635-905d-1326fa8b8e13" } }, "UpdaterProfile": { "Discriminator": "Integration", "EnterpriseProfile": null } }, { "Id": "da34b396-41f7-47f6-8847-aecf00a3f19e", "AccountId": "5fcd1933-22f2-40b9-84da-7db04cbecec2", "Content": "Lactose intolerant", "AccountType": "Customer", "Classifications": [ "FoodAndBeverage" ], "IsActive": true, "CreatorProfile": { "Discriminator": "Enterprise", "EnterpriseProfile": { "ProfileId": "52d19c34-b0aa-4635-905d-1326fa8b8e13" } }, "UpdaterProfile": { "Discriminator": "Integration", "EnterpriseProfile": null } } ], "Cursor": "da34b396-41f7-47f6-8847-aecf00a3f19e" } ``` | Property | Type | Contract | Description | | -------------- | -------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AccountNotes` | array of [Account note](#account-note) | required | The set of requested account notes. | | `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. | #### Account note | Property | Type | Contract | Description | | ----------------- | -------------------------------------------------------------------- | -------- | ----------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the account note. | | `AccountId` | string | required | Unique identifier of the account. | | `Content` | string | required | The content of the account note. | | `AccountType` | [Account type](/connector-api/operations/accounts#account-type) | required | Specifying type of associated account. | | `Classifications` | array of [Account note classification](#account-note-classification) | required | Specifying the classifications of the note based on account type. | | `IsActive` | boolean | required | Whether the account note is still active. | | `CreatorProfile` | [Profile data](/connector-api/operations/_objects#profile-data) | required | The profile data of the user who created the account note. | | `UpdaterProfile` | [Profile data](/connector-api/operations/_objects#profile-data) | required | The profile data of the user who updated the account note. | #### Account note classification {% hint style="info" icon="circle-ellipsis" %} **Note** the list of values is not exhaustive. The API may return additional values that are not listed here. {% endhint %} * `General` - For Company and Customer * `FoodAndBeverage` - Only Customer * `FrontOffice` - Only Customer * `Reservations` - Only Customer * `Housekeeping` - Only Customer * `Maintenance` - Only Customer * `PreviousStay` - Only Customer * `FamilyRelations` - Only Customer * `Gifts` - Only Customer * `Accounting` - Only Customer * `Complaints` - Only Customer * `Other` - Only Customer * … ## Add account notes Adds account notes to an account of the enterprise chain. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/accountNotes/add` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ChainId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "AccountNotes": [ { "AccountId": "8ddea57b-6a5c-4eec-8c4c-24467dce118e", "Content": "Brother of the CEO", "Classifications": [ "FamilyRelations" ] } ] } ``` | 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `AccountNotes` | array of [Account note parameters](#account-note-parameters) | required, max 1000 items | Account notes to be added. | #### Account note parameters | Property | Type | Contract | Description | | ----------------- | -------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------- | | `AccountId` | string | required | | | `Content` | string | required, max length 1000 characters | The content of the account note. | | `Classifications` | array of [Account note classification](#account-note-classification) | required, max 1 item | Specifying the classifications of the note based on account type. | ### Response ```javascript { "AccountNotes": [ { "Id": "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "AccountId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "Content": "Brother of the CEO", "AccountType": "Customer", "Classifications": [ "FamilyRelations" ], "IsActive": true, "CreatorProfile": { "Discriminator": "Enterprise", "EnterpriseProfile": { "ProfileId": "52d19c34-b0aa-4635-905d-1326fa8b8e13" } }, "UpdaterProfile": { "Discriminator": "Integration", "EnterpriseProfile": null } } ] } ``` | Property | Type | Contract | Description | | -------------- | -------------------------------------- | -------- | -------------------- | | `AccountNotes` | array of [Account note](#account-note) | required | Added account notes. | ## Update account notes Updates information about the specified account notes. ### Request `[PlatformAddress]/api/connector/v1/accountNotes/update` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "AccountNoteUpdates": [ { "AccountNoteId": "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "Content": { "Value": "The AC in the room doesn't work anymore" }, "Classifications": { "Maintenance": { "Value": true }, "Housekeeping": { "Value": false } } } ] } ``` | 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `AccountNoteUpdates` | array of [Account note update parameters](#account-note-update-parameters) | required, max 1000 items | Account notes to be updated. | #### Account note update parameters | Property | Type | Contract | Description | | ----------------- | ----------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------- | | `AccountNoteId` | string | required | Unique identifier of the account note. | | `Content` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 1000 characters | Content of the account note (or `null` if the content should not be updated). | | `Classifications` | [Account note update classifications](#account-note-update-classifications) | required | Classification of the account note. | #### Account note update classifications | Property | Type | Contract | Description | | ----------------- | ------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `General` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Company and Customer: Boolean value defining the general classification for the account note (or `null` if the value should not be updated). | | `FoodAndBeverage` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Customer only: Boolean value defining the food and beverage classification for the account note (or `null` if the value should not be updated). | | `FrontOffice` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Customer only: Boolean value defining the front office classification for the account note (or `null` if the value should not be updated). | | `Reservations` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Customer only: Boolean value defining the reservations classification for the account note (or `null` if the value should not be updated). | | `Housekeeping` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Customer only: Boolean value defining the housekeeping classification for the account note (or `null` if the value should not be updated). | | `Maintenance` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Customer only: Boolean value defining the maintenance classification for the account note (or `null` if the value should not be updated). | | `PreviousStay` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Customer only: Boolean value defining the previous stay classification for the account note (or `null` if the value should not be updated). | | `FamilyRelations` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Customer only: Boolean value defining the family relations classification for the account note (or `null` if the value should not be updated). | | `Gifts` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Customer only: Boolean value defining the gifts classification for the account note (or `null` if the value should not be updated). | | `Accounting` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Customer only: Boolean value defining the accounting classification for the account note (or `null` if the value should not be updated). | | `Complaints` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Customer only: Boolean value defining the complaints classification for the account note (or `null` if the value should not be updated). | | `Other` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Customer only: Boolean value defining the other classification for the account note (or `null` if the value should not be updated). | ### Response ```javascript { "AccountNotes": [ { "Id": "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "AccountId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "Content": "The AC in the room doesn't work anymore", "AccountType": "Customer", "Classifications": [ "Maintenance" ], "IsActive": true, "CreatorProfile": { "Discriminator": "Enterprise", "EnterpriseProfile": { "ProfileId": "52d19c34-b0aa-4635-905d-1326fa8b8e13" } }, "UpdaterProfile": { "Discriminator": "Integration", "EnterpriseProfile": null } } ] } ``` | Property | Type | Contract | Description | | -------------- | -------------------------------------- | -------- | ---------------------- | | `AccountNotes` | array of [Account note](#account-note) | required | Updated account notes. | ## Delete account notes Deletes specified account notes. ### Request `[PlatformAddress]/api/connector/v1/accountNotes/delete` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "AccountNoteIds": [ "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "da34b396-41f7-47f6-8847-aecf00a3f19e" ] } ``` | 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `AccountNoteIds` | array of string | required, max 1000 items | Unique identifiers of the account notes to be deleted. | ### Response ```javascript {} ``` # Addresses ## Get all addresses Returns all addresses associated with the specified accounts within the enterprise. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/addresses/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ChainIds": [ "1df21f06-0cfc-4960-9c58-a3bf1261663e", "5fcd1933-22f2-40b9-84da-7db04cbecec2" ], "AccountIds": [ "3db2c989-7d95-42b4-a502-a9f246db1634" ], "AddressIds": [ "fc7b2df3-de66-48a6-907d-af4600ecd892" ], "UpdatedUtc": { "StartUtc": "2022-12-10T00:00:00Z", "EndUtc": "2022-12-17T00:00:00Z" }, "ActivityStates": [ "Active" ], "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. | | `ChainIds` | array of string | optional, max 1000 items | Unique identifiers of `Chain`. If not specified, the operation returns data for all chains within scope of the Access Token. | | `AccountIds` | array of string | optional, max 1000 items | Unique identifiers of [Companies](/connector-api/operations/companies#company) or [Customers](/connector-api/operations/customers#customer) within the enterprise. Required if no other filter is provided. | | `AddressIds` | array of string | optional, max 1000 items | Unique identifiers of [Addresses](#account-address) within the enterprise. Use this property if you want to fetch specific addresses. Required if no other filter is provided. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval of Address last update date and time. Required if no other filter is provided. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted or both records. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "Addresses": [ { "Id": "fc7b2df3-de66-48a6-907d-af4600ecd892", "AccountId": "3db2c989-7d95-42b4-a502-a9f246db1634", "AccountType": "Customer", "Line1": "I.P. Pavlova 5", "Line2": null, "City": "Prague", "PostalCode": "12000", "CountryCode": "CZ", "CountrySubdivisionCode": null, "Latitude": null, "Longitude": null, "UpdatedUtc": "2023-11-29T14:49:29.982Z", "IsActive": true } ] } ``` | Property | Type | Contract | Description | | ----------- | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Addresses` | array of [Account address](#account-address) | required | The collection of Account addresses, containing address and account information. | | `Cursor` | string | optional | Unique identifier of the last and hence oldest address item returned. This can be used in Limitation in a subsequent request to fetch the next batch of older Account address. | #### Account address | Property | Type | Contract | Description | | ------------------------ | --------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Id` | string | required | Unique identifier of the address. | | `AccountId` | string | required | Unique identifier of a [Company](/connector-api/operations/companies#company) or a [Customer](/connector-api/operations/customers#customer) within the enterprise. | | `ChainId` | string | optional | Unique identifier of the chain. | | `AccountType` | [Account type](/connector-api/operations/accounts#account-type) | required | A discriminator specifying the account type, e.g. `Customer` or `Company` | | `Line1` | string | optional, max length 1023 characters | First line of the address. | | `Line2` | string | optional, max length 255 characters | Second line of the address. | | `City` | string | optional, max length 255 characters | The city. | | `PostalCode` | string | optional, max length 255 characters | Postal code. | | `CountryCode` | string | optional | ISO 3166-1 alpha-2 code of the Country. | | `CountrySubdivisionCode` | string | optional | ISO 3166-2 code of the administrative division, e.g. DE-BW. | | `Latitude` | number | optional | The latitude. | | `Longitude` | number | optional | The longitude. | | `UpdatedUtc` | string | optional | Last update date and time of the address in UTC timezone in ISO 8601 format. | | `IsActive` | boolean | required | Whether the address is still active. | ## Add addresses Adds one or more new addresses to the system and assigns them to specified accounts. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/addresses/add` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ChainId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "Addresses": [ { "AccountId": "3db2c989-7d95-42b4-a502-a9f246db1634", "Line1": "Rheinlanddamm 207-209", "Line2": null, "City": "Dortmund", "PostalCode": "44137", "CountryCode": "DE", "CountrySubdivisionCode": null, "Latitude": null, "Longitude": 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `Addresses` | array of [Account address parameters](#account-address-parameters) | required, max 1000 items | Collection of addresses to be created. | #### Account address parameters | Property | Type | Contract | Description | | ------------------------ | ------ | ----------------------------------- | ------------------------------------------------------------------- | | `AccountId` | string | required | Unique identifier of a Company or a Customer within the enterprise. | | `Line1` | string | optional, max length 255 characters | First line of the address. | | `Line2` | string | optional, max length 255 characters | Second line of the address. | | `City` | string | optional, max length 255 characters | The city. | | `PostalCode` | string | optional, max length 255 characters | Postal code. | | `CountryCode` | string | optional | ISO 3166-1 alpha-2 code of the Country. | | `CountrySubdivisionCode` | string | optional | ISO 3166-2 code of the administrative division, e.g. `DE-BW`. | | `Latitude` | number | optional | The latitude in range of -90 to 90. | | `Longitude` | number | optional | The longitude in range of -180 to 180. | ### Response ```javascript { "Addresses": [ { "Id": "fc7b2df3-de66-48a6-907d-af4600ecd892", "AccountId": "3db2c989-7d95-42b4-a502-a9f246db1634", "AccountType": "Customer", "Line1": "I.P. Pavlova 5", "Line2": null, "City": "Prague", "PostalCode": "12000", "CountryCode": "CZ", "CountrySubdivisionCode": null, "Latitude": null, "Longitude": null, "UpdatedUtc": "2023-11-29T14:49:29.982Z", "IsActive": true } ] } ``` | Property | Type | Contract | Description | | ----------- | -------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- | | `Addresses` | array of [Account address](#account-address) | required | The collection of added or modified Account addresses, containing address and account information. | ## Update addresses Updates one or more existing addresses in the system, assigned to specified accounts. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/addresses/update` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ChainId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "AddressUpdates": [ { "AddressId": "fc7b2df3-de66-48a6-907d-af4600ecd892", "AccountId": "3db2c989-7d95-42b4-a502-a9f246db1634", "Line1": { "Value": "I.P. Pavlova 5" }, "Line2": { "Value": null }, "City": { "Value": "Prague" }, "PostalCode": { "Value": "12000" }, "CountryCode": { "Value": "CZ" }, "CountrySubdivisionCode": { "Value": 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `AddressUpdates` | array of [Account address update parameters](#account-address-update-parameters) | required, max 1000 items | Collection of addresses to be updated. | #### Account address update parameters | Property | Type | Contract | Description | | ------------------------ | ----------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------- | | `AddressId` | string | required | Unique identifier of the address. | | `Line1` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 255 characters | First line of the address. | | `Line2` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 255 characters | Second line of the address. | | `City` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 255 characters | The city. | | `PostalCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 255 characters | Postal code. | | `CountryCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | ISO 3166-1 alpha-2 code of the Country. | | `CountrySubdivisionCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | ISO 3166-2 code of the administrative division, e.g. `DE-BW`. | ### Response ```javascript { "Addresses": [ { "Id": "fc7b2df3-de66-48a6-907d-af4600ecd892", "AccountId": "3db2c989-7d95-42b4-a502-a9f246db1634", "AccountType": "Customer", "Line1": "I.P. Pavlova 5", "Line2": null, "City": "Prague", "PostalCode": "12000", "CountryCode": "CZ", "CountrySubdivisionCode": null, "Latitude": null, "Longitude": null, "UpdatedUtc": "2023-11-29T14:49:29.982Z", "IsActive": true } ] } ``` | Property | Type | Contract | Description | | ----------- | -------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- | | `Addresses` | array of [Account address](#account-address) | required | The collection of added or modified Account addresses, containing address and account information. | ## Delete addresses Deletes one or more addresses in the system. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/addresses/delete` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ChainId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "AddressIds": [ "cefa640f-43fa-4a02-8d20-f97f68e19ed5", "44108366-8e9b-4007-844b-8ebcca4ac009" ] } ``` | 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `AddressIds` | array of string | required, max 1000 items | Unique identifiers of [Addresses](#account-address) within the enterprise to be deleted. | ### Response ```javascript {} ``` # Age categories ## Get all age categories Returns all age categories filtered by [Service](/connector-api/operations/services#service). Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/ageCategories/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "ServiceIds": [ "bd26d8db-86da-4f96-9efc-e5a4654a4a94" ], "AgeCategoryIds": [ "fe568bbd-1ecb-4bb2-bf77-96c3698de20d", "ab58c939-be30-4a60-8f75-ae1600c60c9f" ], "UpdatedUtc": { "StartUtc": "2023-10-01T00:00:00Z", "EndUtc": "2023-10-31T00:00:00Z" }, "ActivityStates": [ "Active" ], "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. | | `AgeCategoryIds` | array of string | optional, max 1000 items | Unique identifiers of [Age categories](#age-category). | | `ServiceIds` | array of string | optional, max 1000 items | Unique identifiers of `Service` associated with the age categories. If not provided, defaults to all bookable services. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the age category was updated. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted or both records. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "AgeCategories": [ { "Id": "ab58c939-be30-4a60-8f75-ae1600c60c9f", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "MinimalAge": null, "MaximalAge": null, "Names": { "cs-CZ": "Dospělí", "da-DK": "Voksne", "de-CH": "Erwachsene", "de-DE": "Erwachsene", "el-GR": "Ενήλικοι", "en-GB": "Adults" }, "ShortNames": null, "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z", "Classification": "Adult", "IsActive": false, "ExternalIdentifier": "Adult" }, { "Id": "fe568bbd-1ecb-4bb2-bf77-96c3698de20d", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "MinimalAge": 0, "MaximalAge": 18, "Names": { "cs-CZ": "Děti", "da-DK": "Børn", "de-CH": "Kinder", "de-DE": "Kinder", "el-GR": "Παιδιά", "en-GB": "Children" }, "ShortNames": null, "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z", "Classification": "Child", "IsActive": false, "ExternalIdentifier": null } ], "Cursor": "0b9560fb-055d-47d3-a6d4-e579c44ca558" } ``` | Property | Type | Contract | Description | | --------------- | -------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AgeCategories` | array of [Age category](#age-category) | required | Age category of 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. | #### Age category | Property | Type | Contract | Description | | -------------------- | ------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of age category. | | `ServiceId` | string | required | Unique identifier of [Service](/connector-api/operations/services#service) the age category belongs to. | | `MinimalAge` | integer | optional | Minimal age for the age category. | | `MaximalAge` | integer | optional | Maximal age for the age category. | | `Names` | [Localized text](/connector-api/operations/_objects#localized-text) | required | All translations of the name of the age category. | | `ShortNames` | [Localized text](/connector-api/operations/_objects#localized-text) | optional | All translations of the short name of the age category. | | `CreatedUtc` | string | required | Creation date and time of the age category in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the age category in UTC timezone in ISO 8601 format. | | `Classification` | [Age category classification](#age-category-classification) | required | The classification of the age category. | | `IsActive` | boolean | required | Whether the age category is still active. | | `ExternalIdentifier` | string | optional, max length 255 characters | Identifier of the age category from external system. | #### Age category classification * `Adult` * `Child` # Availability adjustments ## Get all availability adjustments Returns all availability adjustments. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/availabilityAdjustments/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "AvailabilityAdjustmentIds": [ "e19297af-373e-4701-b4ea-afae0129bded", "7413724a-6c48-46d4-ab3a-afae01280999" ], "UpdatedUtc": { "StartUtc": "2023-02-18T18:00:10.155Z", "EndUtc": "2023-02-20T18:00:10.155Z" }, "ActivityStates": [ "Active", "Deleted" ], "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "Limitation": { "Count": 100 } } ``` | 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. | | `AvailabilityAdjustmentIds` | array of string | optional, max 1000 items | Unique identifiers of the requested [Availability adjustments](#availability-adjustment). | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the availability adjustments were updated. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted, or both types of record. If not specified, only active records will be returned. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "AvailabilityAdjustments": [ { "Id": "e19297af-373e-4701-b4ea-afae0129bded", "AvailabilityBlockId": "5ee074b1-6c86-48e8-915f-c7aa4702086f", "ResourceCategoryId": "773d5e42-de1e-43a0-9ce6-f940faf2303f", "StartUtc": null, "EndUtc": null, "FirstTimeUnitStartUtc": "2021-10-14T00:00:00Z", "LastTimeUnitStartUtc": "2021-10-17T00:00:00Z", "UnitCount": 6, "ActivityState": "Active", "ReleaseOverrideUtc": "2021-10-13T00:00:00Z", "UpdatedUtc": "2021-10-21T13:32:32Z", "IsActive": false, "PaxCounts": null, "FirstTimeUnitReleaseUtc": "2021-10-13T00:00:00Z" }, { "Id": "7413724a-6c48-46d4-ab3a-afae01280999", "AvailabilityBlockId": null, "ResourceCategoryId": "773d5e42-de1e-43a0-9ce6-f940faf2303f", "StartUtc": null, "EndUtc": null, "FirstTimeUnitStartUtc": "2023-02-19T23:00:00Z", "LastTimeUnitStartUtc": "2023-02-23T23:00:00Z", "UnitCount": 5, "ActivityState": "Deleted", "ReleaseOverrideUtc": null, "UpdatedUtc": "2023-02-28T23:00:00Z", "IsActive": false, "PaxCounts": null, "FirstTimeUnitReleaseUtc": null } ], "Cursor": "7413724a-6c48-46d4-ab3a-afae01280999" } ``` | Property | Type | Contract | Description | | ------------------------- | ------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AvailabilityAdjustments` | array of [Availability adjustment](#availability-adjustment) | required | Availability adjustments. | | `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. | #### Availability adjustment | Property | Type | Contract | Description | | ------------------------- | ----------------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the [Availability adjustment](#availability-adjustment). | | `AvailabilityBlockId` | string | optional | Unique identifier of the [Availability block](/connector-api/operations/availabilityblocks#availability-block) which the availability adjustment belongs to. | | `ResourceCategoryId` | string | required | Unique identifier of the [Resource category](/connector-api/operations/resources#resource-category) whose availability is updated. | | `FirstTimeUnitStartUtc` | string | required | Start of the time interval, expressed as the timestamp for the start of the first [time unit](/connector-api/operations/services#time-unit), in UTC timezone ISO 8601 format. | | `LastTimeUnitStartUtc` | string | required | End of the time interval, expressed as the timestamp for the start of the last [time unit](/connector-api/operations/services#time-unit), in UTC timezone ISO 8601 format. | | `UnitCount` | integer | required | Adjustment value applied on the interval. | | `ReleaseOverrideUtc` | string | optional | Exact moment the availability adjustment is released if set; overrides the release strategy of the associated availability block. | | `UpdatedUtc` | string | required | Last update date and time of the adjustment in UTC timezone in ISO 8601 format. | | `IsActive` | boolean | required | Whether the availability adjustment is still active. | | `PaxCounts` | array of [Pax count](/connector-api/operations/services#pax-count) | optional, max 5 items | Collection of predicted occupancy of availability adjustments. Relates to how many adjustments are assigned to each count of guests. | | `FirstTimeUnitReleaseUtc` | string | optional | Exact moment the first time unit of the availability adjustment is released based on `ReleaseOverrideUtc` or the `ReleaseStrategy` of the associated availability block, or the `OperationalEditableHistoryInterval` of the associated enterprise if not set, or `null` if `AvailabilityBlockId` is `null`. | | ~~`StartUtc`~~ | ~~string~~ | ~~optional~~ | ~~Start of the interval in UTC timezone in ISO 8601 format.~~ **Deprecated!** | | ~~`EndUtc`~~ | ~~string~~ | ~~optional~~ | ~~End of the interval in UTC timezone in ISO 8601 format.~~ **Deprecated!** | | ~~`ActivityState`~~ | [~~Activity state~~](/connector-api/operations/_objects#activity-state) | ~~required~~ | ~~Shows whether the availability adjustment is active or deleted.~~ **Deprecated!** Use `IsActive` instead. | # Availability blocks ## Get all availability blocks Returns all availability blocks filtered by services, unique identifiers and other filters. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/availabilityBlocks/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "Extent": { "AvailabilityBlocks": true, "Adjustments": true, "ServiceOrders": false, "Rates": false }, "ServiceIds": [ "bd26d8db-86da-4f96-9efc-e5a4654a4a94" ], "AvailabilityBlockIds": [ "5ee074b1-6c86-48e8-915f-c7aa4702086f" ], "CreatedUtc": { "StartUtc": "2020-11-04T00:00:00Z", "EndUtc": "2020-11-05T00:00:00Z" }, "UpdatedUtc": { "StartUtc": "2020-11-04T00:00:00Z", "EndUtc": "2020-11-05T00:00:00Z" }, "CollidingUtc": { "StartUtc": "2020-11-04T00:00:00Z", "EndUtc": "2020-11-05T00:00:00Z" }, "ReleasedUtc": { "StartUtc": "2020-11-04T00:00:00Z", "EndUtc": "2020-11-05T00:00:00Z" }, "ExternalIdentifiers": [ "Block-0001" ], "States": [ "Confirmed" ], "ActivityStates": [ "Active" ], "Limitation": { "Count": 100 } } ``` | 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. | | `Extent` | [Availability block extent](#availability-block-extent) | required | Extent of data to be returned, e.g. it is possible to specify that related service orders (for example reservations) are returned. | | `ServiceIds` | array of string | optional, max 1000 items | Unique identifiers of the `Services` to which `Availability blocks` are assigned. | | `AvailabilityBlockIds` | array of string | optional, max 1000 items | Unique identifiers of the requested `Availability blocks`. | | `CreatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the availability blocks were created. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the `Availability blocks` were updated. | | `CollidingUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the `Availability blocks` are active. | | `ReleasedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the `Availability blocks`are released. | | `ExternalIdentifiers` | array of string | optional, max 1000 items | Identifiers of `Availability blocks` from external systems. | | `States` | array of [Availability block state](#availability-block-state) | optional | States the availability blocks should be in. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted or both records. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | #### Availability block extent | Property | Type | Contract | Description | | -------------------- | ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AvailabilityBlocks` | boolean | optional | Whether the response should contain the general availability blocks. | | `Adjustments` | boolean | optional | Whether the response should contain individual availability adjustments related to availability blocks. | | ~~`ServiceOrders`~~ | ~~boolean~~ | ~~optional~~ | ~~Whether the response should contain reservations related to availability blocks.~~ **Deprecated!** Use [Get all reservations (ver 2023-06-06)](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) instead. | | ~~`Rates`~~ | ~~boolean~~ | ~~optional~~ | ~~Whether the response should contain rates related to availability blocks.~~ **Deprecated!** Use [Get all rates](/connector-api/operations/rates#get-all-rates) instead. | ### Response ```javascript { "AvailabilityBlocks": [ { "Id": "5ee074b1-6c86-48e8-915f-c7aa4702086f", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RateId": "ed4b660b-19d0-434b-9360-a4de2ea42eda", "VoucherId": null, "BookerId": "ebd507c5-6bfd-4ca9-96aa-ffed6fa94f72", "CompanyId": null, "TravelAgencyId": null, "Budget": { "Currency": "USD", "Value": 48, "Net": null, "Tax": null, "TaxRate": null }, "State": "Confirmed", "ReservationPurpose": "Leisure", "CreatedUtc": "2020-11-04T13:00:00Z", "UpdatedUtc": "2020-11-04T13:00:00Z", "FirstTimeUnitStartUtc": "2020-11-04T13:00:00Z", "LastTimeUnitStartUtc": "2020-11-04T13:00:00Z", "ReleasedUtc": "2020-11-04T13:00:00Z", "RollingReleaseOffset": null, "ExternalIdentifier": "Block-0001", "Name": "Wedding group", "Notes": "Have a nice stay", "PickupDistribution": "AllInOneGroup", "IsActive": false, "QuoteId": null, "AvailabilityBlockNumber": "478", "ReleaseStrategy": "FixedRelease", "PurchaseOrderNumber": "XX-123", "BusinessSegmentId": "dc9188f6-fb61-412c-b3fd-af32dab082ed", "CanceledUtc": null, "CancellationReason": null, "CancellationReasonDetail": null }, { "Id": "c32386aa-1cd2-414a-a823-489325842fbe", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RateId": "ed4b660b-19d0-434b-9360-a4de2ea42eda", "VoucherId": null, "BookerId": "ebd507c5-6bfd-4ca9-96aa-ffed6fa94f72", "CompanyId": null, "TravelAgencyId": null, "Budget": { "Currency": "USD", "Value": 48, "Net": null, "Tax": null, "TaxRate": null }, "State": "Confirmed", "ReservationPurpose": "Leisure", "CreatedUtc": "2022-10-11T13:32:32Z", "UpdatedUtc": "2022-10-11T13:32:32Z", "FirstTimeUnitStartUtc": "2022-10-14T00:00:00Z", "LastTimeUnitStartUtc": "2022-11-17T00:00:00Z", "ReleasedUtc": null, "RollingReleaseOffset": "P3DT4H", "ExternalIdentifier": "Block-0002", "Name": "Rolling release", "Notes": null, "PickupDistribution": "AllInOneGroup", "IsActive": false, "QuoteId": "67eaf3c8-81e0-4ffb-b5f2-2b61803feb9c", "AvailabilityBlockNumber": "479", "ReleaseStrategy": "RollingRelease", "PurchaseOrderNumber": null, "BusinessSegmentId": "dc9188f6-fb61-412c-b3fd-af32dab082ed", "CanceledUtc": null, "CancellationReason": null, "CancellationReasonDetail": null } ], "ServiceOrders": null, "Adjustments": [ { "Id": "e19297af-373e-4701-b4ea-afae0129bded", "AvailabilityBlockId": "5ee074b1-6c86-48e8-915f-c7aa4702086f", "ResourceCategoryId": "773d5e42-de1e-43a0-9ce6-f940faf2303f", "StartUtc": null, "EndUtc": null, "FirstTimeUnitStartUtc": "2021-10-14T00:00:00Z", "LastTimeUnitStartUtc": "2021-10-17T00:00:00Z", "UnitCount": 6, "ActivityState": "Active", "ReleaseOverrideUtc": "2021-10-13T00:00:00Z", "UpdatedUtc": "2021-10-21T13:32:32Z", "IsActive": false, "PaxCounts": null, "FirstTimeUnitReleaseUtc": "2021-10-13T00:00:00Z" } ], "Rates": null, "Cursor": "c32386aa-1cd2-414a-a823-489325842fbe" } ``` | Property | Type | Contract | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AvailabilityBlocks` | array of [Availability block](#availability-block) | optional | Availability blocks. | | `Adjustments` | array of [Availability adjustment](/connector-api/operations/availabilityadjustments#availability-adjustment) | optional | Availability adjustments of availability blocks. | | `Cursor` | string | optional | Unique identifier of the last returned availability block. This can be used in Limitation in a subsequent request to fetch the next batch of availability block. | | ~~`ServiceOrders`~~ | ~~array of~~ [~~Reservation (ver 2017-04-12)~~](/connector-api/operations/reservations#reservation-ver-2017-04-12) | ~~optional~~ | ~~Service orders (for example reservations) linked to availability blocks.~~ **Deprecated!** Use [Get all reservations (ver 2023-06-06)](/connector-api/operations/reservations#get-all-reservations-ver-2023-06-06) instead. | | ~~`Rates`~~ | ~~array of~~ [~~Rate for extent~~](/connector-api/operations/reservations#rate-for-extent) | ~~optional~~ | ~~`Rates` assigned to the block.~~ **Deprecated!** Use [Get all rates](/connector-api/operations/rates#get-all-rates) instead. | #### Availability block | Property | Type | Contract | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the availability block. | | `EnterpriseId` | string | required | Unique identifier of the [enterprise](/connector-api/operations/enterprises#enterprise). | | `ServiceId` | string | required | Unique identifier of the `Service` the block is assigned to. | | `RateId` | string | required | Unique identifier of the `Rate` assigned to the block. Availability block is always created with a new dedicated rate so this value differs from `TemplateRateId` or `RateId` provided in the request. | | `VoucherId` | string | optional | Unique identifier of the `Voucher` used to access specified private `Rate`. | | `BookerId` | string | optional | Unique identifier of the `Customer` on whose behalf the block was made. | | `CompanyId` | string | optional | Unique identifier of the `Company` linked to the block. | | `TravelAgencyId` | string | optional | Unique identifier of `Company`with `Travel agency contract` the Availability Block is related to. | | `Budget` | [Currency value (ver 2018-06-07)](/connector-api/operations/_objects#currency-value-ver-2018-06-07) | optional | The tentative budget for the total price of reservations in the block. | | `State` | [Availability block state](#availability-block-state) | required | State of the availability block. | | `ReservationPurpose` | [Reservation purpose](/connector-api/operations/reservations#reservation-purpose) | optional | The purpose of the block. | | `CreatedUtc` | string | required | Creation date and time of the block in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the block in UTC timezone in ISO 8601 format. | | `FirstTimeUnitStartUtc` | string | required | Start of the time interval, expressed as the timestamp for the start of the first time unit, in UTC timezone ISO 8601 format. See [Time units](/connector-api/concepts/time-units). | | `LastTimeUnitStartUtc` | string | required | End of the time interval, expressed as the timestamp for the start of the last time unit, in UTC timezone ISO 8601 format. See [Time units](/connector-api/concepts/time-units). | | `ReleasedUtc` | string | optional | The moment when the block and its availability is released in UTC timezone in ISO 8601 format. Mutually exclusive with `RollingReleaseOffset`; the block will not be automatically released if neither `ReleasedUtc` nor `RollingReleaseOffset` is specified. | | `RollingReleaseOffset` | string | optional | Exact offset from the start of availability adjustments to the moment the individual days in the adjustment should be released, in ISO 8601 duration format. A positive offset means the release happens before the start of the availability adjustment, a negative offset means it happens after the start. Mutually exclusive with `ReleasedUtc`; the block will not be automatically released if neither `ReleasedUtc` nor `RollingReleaseOffset` is specified. | | `ExternalIdentifier` | string | optional, max length 255 characters | Identifier of the block from external system. | | `Name` | string | optional | The name of the block in Mews. | | `Notes` | string | optional | Additional notes of the block. | | `PickupDistribution` | [Pickup distribution](#pickup-distribution) | required | Whether assigning spaces to reservations within an availability block is done as a single group or divided into individual groups. | | `IsActive` | boolean | required | Whether the `Availability Block` is still active. | | `QuoteId` | string | optional | Unique identifier of the Mews Events quote associated with the availability block. | | `AvailabilityBlockNumber` | string | required | Unique number for a specific availability block within the Mews system. | | `ReleaseStrategy` | [Release strategy](#release-strategy) | required | The strategy for automatic release of the availability block. | | `PurchaseOrderNumber` | string | optional | Unique number of the purchase order. This number is propagated to any newly picked up `Reservation` within the block. | | `BusinessSegmentId` | string | optional | Unique identifier of the associated `Business segment`. | | `CanceledUtc` | string | optional | Date and time of the block cancellation in UTC timezone in ISO 8601 format. | | `CancellationReason` | [Reservation cancellation reason](/connector-api/operations/reservations#reservation-cancellation-reason) | optional | Cancellation reason of the availability block. | | `CancellationReasonDetail` | string | optional | Additional details of availability block cancellation. | #### Availability block state * `Confirmed` - The block deducts availability and can have reservations assigned. * `Optional` - The block deducts availability and cannot have reservations assigned. * `Inquired` - The block does not deduct availability and cannot have reservations assigned (waitlist). * `Canceled` - The block does not deduct availability and cannot have reservations assigned (waitlist). #### Pickup distribution * `AllInOneGroup` - All created reservations in the block are added to the same reservation group. * `IndividualGroups` - Reservations can be picked up in multiple groups, with up to 750 reservations per group. #### Release strategy * `FixedRelease` - The availability block is released at a fixed time. * `RollingRelease` - Each availability adjustment is released at a fixed offset from its start. * `None` - The availability block is not automatically released. ## Add availability blocks Adds availability blocks which are used to group related `Availability updates`. This makes limiting public availability easier and more organized. Each block specifies a `TemplateRateId` - the `Rate` used as a template for the block. When the block is created, a new dedicated `Rate` is created based on this template, so the `RateId` returned in the response will differ from the `TemplateRateId` provided in the request. Reservations picked up from the block inherit pricing from the newly created rate. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/availabilityBlocks/add` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "AvailabilityBlocks": [ { "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RateId": "ed4b660b-19d0-434b-9360-a4de2ea42eda", "FirstTimeUnitStartUtc": "2020-11-05T00:00:00Z", "LastTimeUnitStartUtc": "2020-11-06T00:00:00Z", "ReleasedUtc": "2020-11-04T00:00:00Z", "Name": "Mr. Smith's block", "Budget": { "Currency": "USD", "Value": 48 }, "ExternalIdentifier": "Block-0001", "State": "Confirmed" }, { "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RateId": "ed4b660b-19d0-434b-9360-a4de2ea42eda", "FirstTimeUnitStartUtc": "2021-11-05T00:00:00Z", "LastTimeUnitStartUtc": "2021-11-06T00:00:00Z", "Name": "Rolling release block", "Budget": { "Currency": "USD", "Value": 48 }, "ExternalIdentifier": "Block-0002", "State": "Confirmed" } ], "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `AvailabilityBlocks` | array of [Availability block parameters](#availability-block-parameters) | required, max 1000 items | Availability blocks to be added. | #### Availability block parameters | Property | Type | Contract | Description | | ----------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ServiceId` | string | required | Unique identifier of the [Service](/connector-api/operations/services#service) to assign block to. | | `TemplateRateId` | string | required | Unique identifier of the [Rate](/connector-api/operations/rates#rate) used as a template for the availability block's newly created rate. | | `FirstTimeUnitStartUtc` | string | required | Start of the time interval, expressed as the timestamp for the start of the first time unit, in UTC timezone ISO 8601 format. | | `LastTimeUnitStartUtc` | string | required | End of the time interval, expressed as the timestamp for the start of the first time unit, in UTC timezone ISO 8601 format. | | `ReleasedUtc` | string | optional | The moment when the block and its availability is released, in UTC timezone ISO 8601 format. Takes precedence over `RollingReleaseOffset`. | | `RollingReleaseOffset` | string | optional | Exact offset from the start of availability adjustments to the moment the availability adjustment should be released, in ISO 8601 duration format. A positive offset means the release happens before the start of the availability adjustment, a negative offset means it happens after the start. Ignored if `ReleasedUtc` is specified. | | `Name` | string | optional | The name of the block. | | `VoucherCode` | string | optional | Voucher code providing access to specified private [Rate](/connector-api/operations/rates#rate). | | `BookerId` | string | optional | Unique identifier of the Booker as a creator of an availability block. | | `CompanyId` | string | optional | Unique identifier of [Company](/connector-api/operations/companies#company). | | `TravelAgencyId` | string | optional | Unique identifier of travel agency (`Company` with a `TravelAgencyContract`). | | `Budget` | [Currency value (ver 2018-06-07)](/connector-api/operations/_objects#currency-value-ver-2018-06-07) | optional | The tentative budget for the total price of reservations. | | `ReservationPurpose` | [Reservation purpose](/connector-api/operations/reservations#reservation-purpose) | optional | The purpose of the block. | | `ExternalIdentifier` | string | optional, max length 255 characters | Identifier of the block from external system. | | `Notes` | string | optional | Additional notes of the block. | | `State` | [Availability block state](#availability-block-state) | required | State of the availability block. | | `QuoteId` | string | optional | Unique identifier of the Mews Events quote associated with the availability block. | | `PurchaseOrderNumber` | string | optional | Unique number of the purchase order. This number is propagated to any newly picked up `Reservation` within the block. | | `BusinessSegmentId` | string | optional | Unique identifier of the business segment. | | `PickupDistribution` | [Pickup distribution](#pickup-distribution) | optional | Specifies how reservations within the block are distributed for pickup. Defaults to `AllInOneGroup` if not provided. This value cannot be updated after creation. | | ~~`RateId`~~ | ~~string~~ | ~~optional~~ | ~~Synonym of `TemplateRateId`, left for backward compatibility. Ignored when `TemplateRateId` is provided.~~ **Deprecated!** Use `TemplateRateId` instead. | ### Response ```javascript { "AvailabilityBlocks": [ { "Id": "5ee074b1-6c86-48e8-915f-c7aa4702086f", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RateId": "ed4b660b-19d0-434b-9360-a4de2ea42eda", "VoucherId": null, "BookerId": "ebd507c5-6bfd-4ca9-96aa-ffed6fa94f72", "CompanyId": null, "TravelAgencyId": null, "Budget": { "Currency": "USD", "Value": 48, "Net": null, "Tax": null, "TaxRate": null }, "State": "Confirmed", "ReservationPurpose": "Leisure", "CreatedUtc": "2020-11-04T13:00:00Z", "UpdatedUtc": "2020-11-04T13:00:00Z", "FirstTimeUnitStartUtc": "2020-11-04T13:00:00Z", "LastTimeUnitStartUtc": "2020-11-04T13:00:00Z", "ReleasedUtc": "2020-11-04T13:00:00Z", "RollingReleaseOffset": null, "ExternalIdentifier": "Block-0001", "Name": "Wedding group", "Notes": "Have a nice stay", "PickupDistribution": "AllInOneGroup", "IsActive": false, "QuoteId": null, "AvailabilityBlockNumber": "478", "ReleaseStrategy": "FixedRelease", "PurchaseOrderNumber": "XX-123", "BusinessSegmentId": "dc9188f6-fb61-412c-b3fd-af32dab082ed", "CanceledUtc": null, "CancellationReason": null, "CancellationReasonDetail": null }, { "Id": "c32386aa-1cd2-414a-a823-489325842fbe", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RateId": "ed4b660b-19d0-434b-9360-a4de2ea42eda", "VoucherId": null, "BookerId": "ebd507c5-6bfd-4ca9-96aa-ffed6fa94f72", "CompanyId": null, "TravelAgencyId": null, "Budget": { "Currency": "USD", "Value": 48, "Net": null, "Tax": null, "TaxRate": null }, "State": "Confirmed", "ReservationPurpose": "Leisure", "CreatedUtc": "2022-10-11T13:32:32Z", "UpdatedUtc": "2022-10-11T13:32:32Z", "FirstTimeUnitStartUtc": "2022-10-14T00:00:00Z", "LastTimeUnitStartUtc": "2022-11-17T00:00:00Z", "ReleasedUtc": null, "RollingReleaseOffset": "P3DT4H", "ExternalIdentifier": "Block-0002", "Name": "Rolling release", "Notes": null, "PickupDistribution": "AllInOneGroup", "IsActive": false, "QuoteId": "67eaf3c8-81e0-4ffb-b5f2-2b61803feb9c", "AvailabilityBlockNumber": "479", "ReleaseStrategy": "RollingRelease", "PurchaseOrderNumber": null, "BusinessSegmentId": "dc9188f6-fb61-412c-b3fd-af32dab082ed", "CanceledUtc": null, "CancellationReason": null, "CancellationReasonDetail": null } ], "ServiceOrders": null, "Adjustments": [ { "Id": "e19297af-373e-4701-b4ea-afae0129bded", "AvailabilityBlockId": "5ee074b1-6c86-48e8-915f-c7aa4702086f", "ResourceCategoryId": "773d5e42-de1e-43a0-9ce6-f940faf2303f", "StartUtc": null, "EndUtc": null, "FirstTimeUnitStartUtc": "2021-10-14T00:00:00Z", "LastTimeUnitStartUtc": "2021-10-17T00:00:00Z", "UnitCount": 6, "ActivityState": "Active", "ReleaseOverrideUtc": "2021-10-13T00:00:00Z", "UpdatedUtc": "2021-10-21T13:32:32Z", "IsActive": false, "PaxCounts": null, "FirstTimeUnitReleaseUtc": "2021-10-13T00:00:00Z" } ], "Rates": null, "Cursor": "c32386aa-1cd2-414a-a823-489325842fbe" } ``` | Property | Type | Contract | Description | | -------------------- | -------------------------------------------------- | -------- | -------------------- | | `AvailabilityBlocks` | array of [Availability block](#availability-block) | required | Availability blocks. | ## Update availability blocks Updates information about the specified `Availability block`. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/availabilityBlocks/update` ```javascript { "AvailabilityBlocks": [ { "AvailabilityBlockId": "5ee074b1-6c86-48e8-915f-c7aa4702086f", "Name": { "Value": "Mr. Smith's block" }, "FirstTimeUnitStartUtc": { "Value": "2021-07-05T00:00:00Z" }, "LastTimeUnitStartUtc": { "Value": "2021-07-15T00:00:00Z" }, "ExternalIdentifier": { "Value": "Block-1002" }, "State": { "Value": "Confirmed" }, "ReservationPurpose": { "Value": "Business" }, "BookerId": { "Value": "ebd507c5-6bfd-4ca9-96aa-ffed6fa94f72" }, "Notes": { "Value": "Welcome to Washington" }, "Budget": { "Value": { "Currency": "USD", "Value": 48 } }, "ReleasedUtc": { "Value": "2021-07-04T00:00:00Z" }, "QuoteId": {}, "BusinessSegmentId": { "Value": "dc9188f6-fb61-412c-b3fd-af32dab082ed" } }, { "AvailabilityBlockId": "c32386aa-1cd2-414a-a823-489325842fbe", "State": { "Value": "Canceled" }, "CancellationReason": { "Value": "ForceMajeure" }, "CancellationReasonDetail": { "Value": "Event was canceled due to rain." } } ] } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `AvailabilityBlocks` | array of [Availability block update parameters](#availability-block-update-parameters) | required, max 1000 items | Availability blocks to be updated. | #### Availability block update parameters | Property | Type | Contract | Description | | -------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AvailabilityBlockId` | string | required | Unique identifier of the [Availability block](#availability-block). | | `Name` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | The name of the block (or `null` if the name should not be updated). | | `FirstTimeUnitStartUtc` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Start of the time interval, expressed as the timestamp for the start of the first time unit, in UTC timezone ISO 8601 format (or `null` if the start time should not be updated). | | `LastTimeUnitStartUtc` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | End of the time interval, expressed as the timestamp for the start of the last time unit, in UTC timezone ISO 8601 format (or `null` if the end time should not be updated). | | `ExternalIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 255 characters | Identifier of the block from external system (or `null` if the identifier should not be updated). | | `State` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | State of the availability block (or `null` if not updated). | | `ReservationPurpose` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | The purpose of the block (or `null` if not updated). | | `CompanyId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique identifier of the [Company](/connector-api/operations/companies#company) (or `null` if not updated). | | `TravelAgencyId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique identifier of the travel agency (i.e. `Company`; or `null` if not updated). | | `BookerId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique identifier of the Booker as a creator of an availability block (or `null` if not updated). | | `Notes` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Additional notes of the block (or `null` if not updated). | | `Budget` | [Currency value (ver 2018-06-07) update value](#currency-value-ver-2018-06-07-update-value) | optional | The tentative budget for the total price of reservations (or `null` if not updated). | | `CancellationReason` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Cancellation reason of the availability block (or `null` if not updated). | | `CancellationReasonDetail` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Cancellation reason detail of the availability block (or `null` if not updated). | | `RollingReleaseOffset` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Exact offset from the start of availability adjustments to the moment the availability adjustment should be released, in ISO 8601 duration format. A positive offset means the release happens before the start of the availability adjustment, a negative offset means it happens after the start. Required if `ReleaseStrategy` is set to `RollingRelease`, ignored otherwise. | | `ReleasedUtc` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | The moment when the block and its availability is released, in UTC timezone ISO 8601 format. Required if `ReleaseStrategy` is set to `FixedRelease`, or used when `ReleaseStrategy` update is unspecified. | | `ReleaseStrategy` | [Release strategy update value](#release-strategy-update-value) | optional | The strategy for automatic release of the availability block (or `null` if not updated). | | `QuoteId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique identifier of the Mews Events quote associated with the availability block (or `null` if not updated). | | `PurchaseOrderNumber` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique number of the purchase order. This number is propagated to any newly picked up `Reservation` within the block. | | `BusinessSegmentId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique identifier of the Business segment. | #### Currency value (ver 2018-06-07) update value | Property | Type | Contract | Description | | -------- | --------------------------------------------------------------------------------------------------- | -------- | -------------------------------- | | `Value` | [Currency value (ver 2018-06-07)](/connector-api/operations/_objects#currency-value-ver-2018-06-07) | optional | Value in the specified currency. | #### Release strategy update value | Property | Type | Contract | Description | | -------- | ------------------------------------- | -------- | ------------------------------------------------------------- | | `Value` | [Release strategy](#release-strategy) | required | The strategy for automatic release of the availability block. | ### Response ```javascript { "AvailabilityBlocks": [ { "Id": "5ee074b1-6c86-48e8-915f-c7aa4702086f", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RateId": "ed4b660b-19d0-434b-9360-a4de2ea42eda", "VoucherId": null, "BookerId": "ebd507c5-6bfd-4ca9-96aa-ffed6fa94f72", "CompanyId": null, "TravelAgencyId": null, "Budget": { "Currency": "USD", "Value": 48, "Net": null, "Tax": null, "TaxRate": null }, "State": "Confirmed", "ReservationPurpose": "Business", "CreatedUtc": "2020-11-04T13:00:00Z", "UpdatedUtc": "2020-11-05T16:11:38Z", "FirstTimeUnitStartUtc": "2021-07-05T00:00:00Z", "LastTimeUnitStartUtc": "2021-07-15T00:00:00Z", "ReleasedUtc": "2021-07-04T00:00:00Z", "RollingReleaseOffset": null, "ExternalIdentifier": "Block-1002", "Name": "Mr. Smith's block", "Notes": "Welcome to Washington", "PickupDistribution": "AllInOneGroup", "IsActive": false, "QuoteId": null, "AvailabilityBlockNumber": "478", "ReleaseStrategy": "FixedRelease", "PurchaseOrderNumber": "XX-123", "BusinessSegmentId": "dc9188f6-fb61-412c-b3fd-af32dab082ed", "CanceledUtc": null, "CancellationReason": null, "CancellationReasonDetail": null }, { "Id": "c32386aa-1cd2-414a-a823-489325842fbe", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RateId": "ed4b660b-19d0-434b-9360-a4de2ea42eda", "VoucherId": null, "BookerId": "ebd507c5-6bfd-4ca9-96aa-ffed6fa94f72", "CompanyId": null, "TravelAgencyId": null, "Budget": { "Currency": "USD", "Value": 48, "Net": null, "Tax": null, "TaxRate": null }, "State": "Canceled", "ReservationPurpose": "Leisure", "CreatedUtc": "2022-10-11T13:32:32Z", "UpdatedUtc": "2022-10-11T13:32:32Z", "FirstTimeUnitStartUtc": "2022-10-14T00:00:00Z", "LastTimeUnitStartUtc": "2022-11-17T00:00:00Z", "ReleasedUtc": null, "RollingReleaseOffset": "P3DT4H", "ExternalIdentifier": "Block-0002", "Name": "Rolling release", "Notes": null, "PickupDistribution": "AllInOneGroup", "IsActive": false, "QuoteId": "67eaf3c8-81e0-4ffb-b5f2-2b61803feb9c", "AvailabilityBlockNumber": "479", "ReleaseStrategy": "RollingRelease", "PurchaseOrderNumber": null, "BusinessSegmentId": "dc9188f6-fb61-412c-b3fd-af32dab082ed", "CanceledUtc": "2022-10-12T15:12:49Z", "CancellationReason": "ForceMajeure", "CancellationReasonDetail": "Event was canceled due to rain." } ], "ServiceOrders": null, "Adjustments": [ { "Id": "e19297af-373e-4701-b4ea-afae0129bded", "AvailabilityBlockId": "5ee074b1-6c86-48e8-915f-c7aa4702086f", "ResourceCategoryId": "773d5e42-de1e-43a0-9ce6-f940faf2303f", "StartUtc": null, "EndUtc": null, "FirstTimeUnitStartUtc": "2021-10-14T00:00:00Z", "LastTimeUnitStartUtc": "2021-10-17T00:00:00Z", "UnitCount": 6, "ActivityState": "Active", "ReleaseOverrideUtc": "2021-10-13T00:00:00Z", "UpdatedUtc": "2021-10-21T13:32:32Z", "IsActive": false, "PaxCounts": null, "FirstTimeUnitReleaseUtc": "2021-10-13T00:00:00Z" } ], "Rates": null, "Cursor": "c32386aa-1cd2-414a-a823-489325842fbe" } ``` | Property | Type | Contract | Description | | -------------------- | -------------------------------------------------- | -------- | -------------------- | | `AvailabilityBlocks` | array of [Availability block](#availability-block) | required | Availability blocks. | ## Delete availability blocks Delete availability blocks. Note that an availability block containing active reservations (reservations which are not Canceled) cannot be deleted. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/availabilityBlocks/delete` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "AvailabilityBlockIds": [ "5ee074b1-6c86-48e8-915f-c7aa4702086f", "c32386aa-1cd2-414a-a823-489325842fbe" ], "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `AvailabilityBlockIds` | array of string | required, max 1000 items | Unique identifier of the Availability block to delete. | ### Response ```javascript {} ``` # Billing automations ## Get all billing automations Returns all billing automations. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/billingAutomations/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CompanyIds": [ "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f", "956aa0f0-a090-42c8-bee2-991972d32f80" ], "BillingAutomationIds": [ "ecd64eec-4423-4c65-b844-814b9199856d", "13e6b16e-39bc-4cb1-8610-70ecdb4f91cc" ], "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ] } ``` | 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. | | `CompanyIds` | array of string | optional, max 100 items | Unique identifiers of `Company` associated with the billing automations. | | `BillingAutomationIds` | array of string | optional, max 100 items | Unique identifiers of specific `Billing automation` items. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "BillingAutomations": [ { "Id": "ecd64eec-4423-4c65-b844-814b9199856d", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "Continuous billing automation for company XYZ", "Description": "Billing Automation for company XYZ with prepayment all, company as owner.", "CompaniesWithRelations": [ { "CompanyId": "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f", "CompanyRelations": { "PartnerCompany": true, "TravelAgency": false } } ], "Prepayment": "All", "AssignmentTargetType": "CompanyAsOwner", "TriggerType": "Continuous", "BillAggregationType": "AggregateAll", "CreatedUtc": "2017-01-31T10:58:06Z", "UpdatedUtc": "2023-10-28T14:23:00Z", "CreatorProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf", "UpdaterProfileId": "122fc063-ec6e-4198-b8db-6b168a59ffae", "ProcessingStartOffset": null, "OrderItemConsumptionPeriod": null, "Assignments": [ { "Id": "d6b550e9-9c4b-42dd-9daa-555312b030e6", "BillingAutomationId": "ecd64eec-4423-4c65-b844-814b9199856d", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RoutedItemTypes": { "SpaceOrder": true, "CityTax": true, "AllProducts": true, "Deposits": true, "AdditionalExpenses": false, "AllCustomItems": false }, "RateIds": [ "ab3682ba-4493-4eb0-bcdc-8d000f5bad65" ], "ProductCategoryIds": [ "599c477e-b826-4444-8ded-4fa7276ef0c1" ], "ProductIds": [ "f0184ec2-9f02-4026-9b70-0b2bed2adde7" ], "AccountingCategoryAssignments": [ { "AccountingCategoryId": "2e0f5930-605e-4a23-9994-a7701a56b576", "ItemTypes": { "Products": true, "CustomItems": false } } ] } ] } ], "Cursor": "54ec08b6-e6fc-48e9-b8ae-02943e0ac693" } ``` | Property | Type | Contract | Description | | -------------------- | -------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BillingAutomations` | array of [Billing automation](#billing-automation) | optional, max 1000 items | The list of filtered billing automations. | | `Cursor` | string | optional | Unique identifier of the last returned billing automation. This can be used in Limitation in a subsequent request to fetch the next batch of billing automations. | #### Billing automation | Property | Type | Contract | Description | | ---------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the billing automation. | | `EnterpriseId` | string | required | Unique identifier of the enterprise. | | `Name` | string | required | Name of the billing automation. | | `Description` | string | optional | Description of the billing automation. | | `CompaniesWithRelations` | array of [Company with billing automation relation](#company-with-billing-automation-relation) | required, max 1000 items | List of companies with relations to the billing automation. | | `Prepayment` | [Billing automation prepayment type](#billing-automation-prepayment-type) | required | Type of prepayment. | | `AssignmentTargetType` | [Billing automation assignment target type](#billing-automation-assignment-target-type) | required | Type of target company and customer assignment behavior. | | `TriggerType` | [Billing automation trigger type](#billing-automation-trigger-type) | required | Trigger type of billing automation. | | `BillAggregationType` | [Billing automation bill aggregation type](#billing-automation-bill-aggregation-type) | required | Type of bill aggregation. | | `CreatedUtc` | string | required | Creation date and time of the billing automation in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the billing automation in UTC timezone in ISO 8601 format. | | `CreatorProfileId` | string | required | Unique identifier of the user who created the billing automation. | | `UpdaterProfileId` | string | required | Unique identifier of the user who last updated the billing automation. | | `ProcessingStartOffset` | string | optional | Processing start offset. Applicable only if the billing automation `TriggerType` is set to `Reccuring`. | | `OrderItemConsumptionPeriod` | [Billing automation order item consumption period type](#billing-automation-order-item-consumption-period-type) | optional | Specifies the type of order item consumption period for the billing automation. This value is applicable only when the `TriggerType` is set to `Reccuring`. | | `Assignments` | array of [Billing automation assignment](#billing-automation-assignment) | optional, max 20 items | List of billing automation assignments. | #### Company with billing automation relation | Property | Type | Contract | Description | | ------------------ | ----------------------------------------------------------------------- | -------- | --------------------------------- | | `CompanyId` | string | required | Unique identifier of the company. | | `CompanyRelations` | [Company with relations parameters](#company-with-relations-parameters) | required | Company relations. | #### Company with relations parameters | Property | Type | Contract | Description | | ---------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `PartnerCompany` | boolean | required | Indicates whether the billing automation will apply if the company added to a reservation is a partner company. | | `TravelAgency` | boolean | required | Indicates whether the billing automation will apply if the company added to a reservation is a travel agency. | #### Billing automation prepayment type * `All` - Applies to reservations regardless of prepayment. * `Prepaid` - Applies only to reservations the OTA flagged as prepaid. * `PrepaidOrVcc` - Applies to reservations the OTA flagged as prepaid, and to reservations with a virtual credit card attached. #### Billing automation assignment target type * `CompanyAsDetails` - The company will be the associated account in the resulting routed bill, and the customer is the owner. * `CompanyAsOwner` - The company will be the owner in the resulting routed bill, and the customer might be the associated account. * `NoCompany` - The customer will be owner of the bill. #### Billing automation trigger type * `Continuous` - Billing automation is continuously triggered by reservation actions, such as creation, updates, and rebates. * `Recurring` - Billing automation is executed monthly. * `Legacy` - Billing automation is executed on reservation creation only. Items added later are not transfered to any bill. #### Billing automation bill aggregation type * `OnePerReservation` - Create a separate bill for each reservation. * `AggregateByCustomer` - Create a separate bill for each reservation owner. * `AggregateAll` - Group all moved items on one bill. * `AggregatePerReservationGroup` - Create a separate bill for each reservation group. #### Billing automation order item consumption period type * `MonthBefore` - Only items with a consumption date within the previous month will be routed. * `SameMonthAndMonthBefore` - Only items with a consumption date within this and the previous month will be routed. * `SameMonth` - Only items with a consumption date within this month will be routed. * `SameMonthAndMonthAfter` - Only items with a consumption date within this and the next month will be routed. * `MonthAfter` - Only items with a consumption date within the next month will be routed. #### Billing automation assignment | Property | Type | Contract | Description | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the billing automation assignment. | | `BillingAutomationId` | string | required | Unique identifier of the billing automation. | | `ServiceId` | string | required | Unique identifier of the related service. | | `RoutedItemTypes` | [Billing automation item types parameters](#billing-automation-item-types-parameters) | required | Type of items that are going to be routed. | | `RateIds` | array of string | optional, max 100 items | Unique identifiers of `Rates` used in billing automation conditions. | | `ProductCategoryIds` | array of string | optional, max 100 items | Unique identifiers of `Product Categories` used in billing automation conditions. | | `ProductIds` | array of string | optional, max 100 items | Unique identifiers of `Products` used in billing automation conditions. | | `AccountingCategoryAssignments` | array of [Billing automation accounting category assignment](#billing-automation-accounting-category-assignment) | optional, max 100 items | List of accounting category assignments used in billing automation conditions. | #### Billing automation item types parameters | Property | Type | Contract | Description | | -------------------- | ------- | -------- | ------------------- | | `SpaceOrder` | boolean | required | Space order | | `CityTax` | boolean | required | City tax | | `AllProducts` | boolean | required | All products | | `Deposits` | boolean | required | Deposits | | `AdditionalExpenses` | boolean | required | Additional expenses | | `AllCustomItems` | boolean | required | All custom items | #### Billing automation accounting category assignment | Property | Type | Contract | Description | | ---------------------- | ------------------------------------------------------------------------------- | -------- | --------------------------------------------- | | `AccountingCategoryId` | string | required | Unique identifier of the accounting category. | | `ItemTypes` | [Accounting category routed item types](#accounting-category-routed-item-types) | required | Type of the accounting category routed item. | #### Accounting category routed item types | Property | Type | Contract | Description | | ------------- | ------- | -------- | ------------------------------------------------------------------------------ | | `Products` | boolean | required | Specifies whether products under the given accounting category are routed. | | `CustomItems` | boolean | required | Specifies whether custom items under the given accounting category are routed. | ## Add billing automations Adds billing automations. ### Request `[PlatformAddress]/api/connector/v1/billingAutomations/add` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "BillingAutomations": [ { "Name": "Company A billing automation", "Description": "Billing automation routing reservations made for Company A to bills where company is an owner, aggregating all reservations onto one bill.", "CompaniesWithRelations": [ { "CompanyId": "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f", "CompanyRelations": { "PartnerCompany": true, "TravelAgency": false } } ], "Prepayment": "All", "AssignmentTargetType": "CompanyAsOwner", "TriggerType": "Continuous", "BillAggregationType": "AggregateAll", "Assignments": [ { "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RoutedItemTypes": { "SpaceOrder": true, "CityTax": true, "AllProducts": false, "Deposits": true, "AdditionalExpenses": true, "AllCustomItems": false }, "ProductIds": [ "507d93e6-9fb5-4734-a6d1-977afc4dfdff" ] } ] } ] } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `BillingAutomations` | array of [Billing automation add parameters](#billing-automation-add-parameters) | required, max 100 items | Parameters of the new billing automations to be created. | #### Billing automation add parameters | Property | Type | Contract | Description | | ---------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Name` | string | required, max length 255 characters | Name of the billing automation. | | `Description` | string | optional, max length 1000 characters | Description of the billing automation. | | `CompaniesWithRelations` | array of [Company with billing automation relation](#company-with-billing-automation-relation) | optional, max 1000 items | List of companies with relations indicating whether the company is considered a travel agency or a company in the reservation. Can only be empty if `AssignmentTargetType` is `CompanyAsDetails` or `NoCompany`. | | `Prepayment` | [Billing automation prepayment type](#billing-automation-prepayment-type) | required | Type of prepayment. | | `AssignmentTargetType` | [Billing automation assignment target type](#billing-automation-assignment-target-type) | required | Specifies the type of company assignment to the bill. If set to `NoCompany`, the `BillAggregationType` must be `AggregateByCustomer`. | | `TriggerType` | [Billing automation trigger type](#billing-automation-trigger-type) | required | Trigger type of billing automation. | | `BillAggregationType` | [Billing automation bill aggregation type](#billing-automation-bill-aggregation-type) | required | Specifies the type of bill aggregation. If the value is not `AggregateByCustomer`, the `AssignmentTargetType` must be `CompanyAsOwner`. | | `OrderItemConsumptionPeriod` | [Billing automation order item consumption period type](#billing-automation-order-item-consumption-period-type) | optional | Specifies the order item consumption period type for the billing automation. This is required if the `TriggerType` is set to `Reccuring`. | | `ProcessingStartOffset` | string | optional, max length 20 characters | Specifies the processing start offset. This is required if the billing automation `TriggerType` is set to `Reccuring`. | | `Assignments` | array of [Billing automation assignment add parameters](#billing-automation-assignment-add-parameters) | required, max 20 items | List of billing automation assignments. | #### Billing automation assignment add parameters | Property | Type | Contract | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ | | `ServiceId` | string | required | Unique identifier of the related service. | | `RoutedItemTypes` | [Billing automation item types parameters](#billing-automation-item-types-parameters) | required | Type of items that are going to be routed. | | `RateIds` | array of string | optional, max 100 items | Unique identifiers of `Rates` that will be applied as billing automation condition. | | `ProductCategoryIds` | array of string | optional, max 100 items | Unique identifiers of `Product Categories` that will be applied as billing automation condition. | | `ProductIds` | array of string | optional, max 100 items | Unique identifiers of `Products` that will be applied as billing automation condition. | | `AccountingCategories` | array of [Billing automation accounting category assignment](#billing-automation-accounting-category-assignment) | optional, max 100 items | List of accounting categories that will be applied as billing automation condition. | ### Response ```javascript { "BillingAutomations": [ { "Id": "ecd64eec-4423-4c65-b844-814b9199856d", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "Continuous billing automation for company XYZ", "Description": "Billing Automation for company XYZ with prepayment all, company as owner.", "CompaniesWithRelations": [ { "CompanyId": "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f", "CompanyRelations": { "PartnerCompany": true, "TravelAgency": false } } ], "Prepayment": "All", "AssignmentTargetType": "CompanyAsOwner", "TriggerType": "Continuous", "BillAggregationType": "AggregateAll", "CreatedUtc": "2017-01-31T10:58:06Z", "UpdatedUtc": "2023-10-28T14:23:00Z", "CreatorProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf", "UpdaterProfileId": "122fc063-ec6e-4198-b8db-6b168a59ffae", "ProcessingStartOffset": null, "OrderItemConsumptionPeriod": null, "Assignments": [ { "Id": "d6b550e9-9c4b-42dd-9daa-555312b030e6", "BillingAutomationId": "ecd64eec-4423-4c65-b844-814b9199856d", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RoutedItemTypes": { "SpaceOrder": true, "CityTax": true, "AllProducts": true, "Deposits": true, "AdditionalExpenses": false, "AllCustomItems": false }, "RateIds": [ "ab3682ba-4493-4eb0-bcdc-8d000f5bad65" ], "ProductCategoryIds": [ "599c477e-b826-4444-8ded-4fa7276ef0c1" ], "ProductIds": [ "f0184ec2-9f02-4026-9b70-0b2bed2adde7" ], "AccountingCategoryAssignments": [ { "AccountingCategoryId": "2e0f5930-605e-4a23-9994-a7701a56b576", "ItemTypes": { "Products": true, "CustomItems": false } } ] } ] } ] } ``` | Property | Type | Contract | Description | | -------------------- | -------------------------------------------------- | -------- | ---------------------------------------------- | | `BillingAutomations` | array of [Billing automation](#billing-automation) | optional | Billing automations affected by the operation. | ## Update billing automations Updates one or more existing billing automations. ### Request `[PlatformAddress]/api/connector/v1/billingAutomations/update` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "BillingAutomationUpdates": [ { "BillingAutomationId": "ecd64eec-4423-4c65-b844-814b9199856d", "Name": { "Value": "New name." }, "Description": { "Value": "Billing Automation that has prepayment changed to All, Assignment target to Company as owner and Bill aggregation to aggregate all items into one bill." }, "Prepayment": { "Value": "All" }, "AssignmentTargetType": { "Value": "CompanyAsOwner" }, "BillAggregationType": { "Value": "AggregateAll" } } ] } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `BillingAutomationUpdates` | array of [Billing automation update parameters](#billing-automation-update-parameters) | required, max 100 items | Details of the billing automations to be updated. | #### Billing automation update parameters | Property | Type | Contract | Description | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BillingAutomationId` | string | required | Unique identifier of the billing automation. | | `Name` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 255 characters | Name of the billing automation (or null should it not be updated). | | `Description` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 1000 characters | Description of the billing automation (or null should it not be updated). | | `Companies` | [Company with billing automation relation array update value](#company-with-billing-automation-relation-array-update-value) | optional, max length 1000 characters | List of companies with relations indicating whether the company should be considered as a travel agency or a company in the reservation. This list can only be empty if the `AssignmentTargetType` is `CompanyAsDetails` or `NoCompany`. Set to null if the value is not updated. | | `Prepayment` | [Billing automation prepayment update value](/connector-api/operations/_objects#string-update-value) | optional | Type of prepayment (or null should it not be updated). | | `AssignmentTargetType` | [Billing automation assignment target type update value](/connector-api/operations/_objects#string-update-value) | optional | Specifies the type of company assignment to the bill. If set to `NoCompany`, the `BillAggregationType` must be `AggregateByCustomer`. Set to null if the value is not updated. | | `BillAggregationType` | [Billing automation bill aggregation type update value](/connector-api/operations/_objects#string-update-value) | optional | Defines the aggregation target type for billing automation. If not `AggregateByCustomer`, the `AssignmentTargetType` must be `CompanyAsOwner`. Set to null if the value is not updated. | | `OrderItemConsumptionPeriod` | [Billing automation order item consumption period type update value](/connector-api/operations/_objects#string-update-value) | optional | Specifies the order item consumption period type for the billing automation. Required if the `TriggerType` is recurring. Can be null if the value is not updated. | | `ProcessingStartOffset` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 20 characters | Processing start offset. Required if the billing automation `TriggerType` is recurring (or null should it not be updated). | #### Company with billing automation relation array update value | Property | Type | Contract | Description | | -------- | ---------------------------------------------------------------------------------------------- | -------- | ----------------------------- | | `Value` | array of [Company with billing automation relation](#company-with-billing-automation-relation) | optional | Value which is to be updated. | ### Response ```javascript { "BillingAutomations": [ { "Id": "ecd64eec-4423-4c65-b844-814b9199856d", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "Continuous billing automation for company XYZ", "Description": "Billing Automation for company XYZ with prepayment all, company as owner.", "CompaniesWithRelations": [ { "CompanyId": "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f", "CompanyRelations": { "PartnerCompany": true, "TravelAgency": false } } ], "Prepayment": "All", "AssignmentTargetType": "CompanyAsOwner", "TriggerType": "Continuous", "BillAggregationType": "AggregateAll", "CreatedUtc": "2017-01-31T10:58:06Z", "UpdatedUtc": "2023-10-28T14:23:00Z", "CreatorProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf", "UpdaterProfileId": "122fc063-ec6e-4198-b8db-6b168a59ffae", "ProcessingStartOffset": null, "OrderItemConsumptionPeriod": null, "Assignments": [ { "Id": "d6b550e9-9c4b-42dd-9daa-555312b030e6", "BillingAutomationId": "ecd64eec-4423-4c65-b844-814b9199856d", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RoutedItemTypes": { "SpaceOrder": true, "CityTax": true, "AllProducts": true, "Deposits": true, "AdditionalExpenses": false, "AllCustomItems": false }, "RateIds": [ "ab3682ba-4493-4eb0-bcdc-8d000f5bad65" ], "ProductCategoryIds": [ "599c477e-b826-4444-8ded-4fa7276ef0c1" ], "ProductIds": [ "f0184ec2-9f02-4026-9b70-0b2bed2adde7" ], "AccountingCategoryAssignments": [ { "AccountingCategoryId": "2e0f5930-605e-4a23-9994-a7701a56b576", "ItemTypes": { "Products": true, "CustomItems": false } } ] } ] } ] } ``` | Property | Type | Contract | Description | | -------------------- | -------------------------------------------------- | -------- | ---------------------------------------------- | | `BillingAutomations` | array of [Billing automation](#billing-automation) | optional | Billing automations affected by the operation. | ## Update billing automations assignments Add, update or remove billing automation assignments of a specific billing automation. ### Request `[PlatformAddress]/api/connector/v1/billingAutomations/updateAssignments` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "BillingAutomationId": "ecd64eec-4423-4c65-b844-814b9199856d", "AssignmentsToUpdate": [ { "BillingAutomationAssignmentId": "00000000-0000-0000-0000-000000000000", "RoutedItemTypes": { "SpaceOrder": { "Value": true }, "CityTax": { "Value": true }, "AllProducts": { "Value": false }, "Deposits": { "Value": true }, "AdditionalExpenses": { "Value": true }, "AllCustomItems": { "Value": false } }, "ProductIds": { "Value": [ "507d93e6-9fb5-4734-a6d1-977afc4dfdff" ] } } ] } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `BillingAutomationId` | string | required | Unique identifier of the billing automation. | | `AssignmentsToAdd` | array of [Billing automation assignment add parameters](#billing-automation-assignment-add-parameters) | optional, max 20 items | Parameters for adding new assignments (or null if not being updated). | | `AssignmentsToUpdate` | array of [Billing automation assignment update parameters](#billing-automation-assignment-update-parameters) | optional, max 20 items | List of parameters for updating existing assignments (or null if not being updated). | | `AssignmentIdsToRemove` | array of string | optional, max 100 items | List of unique identifiers for assignments to be removed (or null if not being updated). | ### Response ```javascript { "BillingAutomations": [ { "Id": "ecd64eec-4423-4c65-b844-814b9199856d", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "Continuous billing automation for company XYZ", "Description": "Billing Automation for company XYZ with prepayment all, company as owner.", "CompaniesWithRelations": [ { "CompanyId": "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f", "CompanyRelations": { "PartnerCompany": true, "TravelAgency": false } } ], "Prepayment": "All", "AssignmentTargetType": "CompanyAsOwner", "TriggerType": "Continuous", "BillAggregationType": "AggregateAll", "CreatedUtc": "2017-01-31T10:58:06Z", "UpdatedUtc": "2023-10-28T14:23:00Z", "CreatorProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf", "UpdaterProfileId": "122fc063-ec6e-4198-b8db-6b168a59ffae", "ProcessingStartOffset": null, "OrderItemConsumptionPeriod": null, "Assignments": [ { "Id": "d6b550e9-9c4b-42dd-9daa-555312b030e6", "BillingAutomationId": "ecd64eec-4423-4c65-b844-814b9199856d", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "RoutedItemTypes": { "SpaceOrder": true, "CityTax": true, "AllProducts": true, "Deposits": true, "AdditionalExpenses": false, "AllCustomItems": false }, "RateIds": [ "ab3682ba-4493-4eb0-bcdc-8d000f5bad65" ], "ProductCategoryIds": [ "599c477e-b826-4444-8ded-4fa7276ef0c1" ], "ProductIds": [ "f0184ec2-9f02-4026-9b70-0b2bed2adde7" ], "AccountingCategoryAssignments": [ { "AccountingCategoryId": "2e0f5930-605e-4a23-9994-a7701a56b576", "ItemTypes": { "Products": true, "CustomItems": false } } ] } ] } ] } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `BillingAutomationId` | string | required | Unique identifier of the billing automation. | | `AssignmentsToAdd` | array of [Billing automation assignment add parameters](#billing-automation-assignment-add-parameters) | optional, max 20 items | Parameters for adding new assignments (or null if not being updated). | | `AssignmentsToUpdate` | array of [Billing automation assignment update parameters](#billing-automation-assignment-update-parameters) | optional, max 20 items | List of parameters for updating existing assignments (or null if not being updated). | | `AssignmentIdsToRemove` | array of string | optional, max 100 items | List of unique identifiers for assignments to be removed (or null if not being updated). | #### Billing automation assignment update parameters | Property | Type | Contract | Description | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `BillingAutomationAssignmentId` | string | required | Unique identifier of the billing automation assignment. | | `RoutedItemTypes` | [Billing automation item types update parameters](#billing-automation-item-types-update-parameters) | optional | Type of items that are going to be routed (or `null` should it not be updated). | | `RateIds` | [Guid array update value](https://github.com/MewsSystems/open-api-docs/tree/main/connector-api/operations/_object.md#array-of-strings-update-value) | optional, max length 100 characters | Unique identifiers of `Rates` that will be applied as billing automation condition (or `null` should it not be updated). | | `ProductCategoryIds` | [Guid array update value](https://github.com/MewsSystems/open-api-docs/tree/main/connector-api/operations/_object.md#array-of-strings-update-value) | optional, max length 100 characters | Unique identifiers of `Product Categories` that will be applied as billing automation condition (or `null` should it not be updated). | | `ProductIds` | [Guid array update value](https://github.com/MewsSystems/open-api-docs/tree/main/connector-api/operations/_object.md#array-of-strings-update-value) | optional, max length 100 characters | Unique identifiers of `Products` that will be applied as billing automation condition (or `null` should it not be updated). | | `AccountingCategories` | [Billing automation accounting category assignment array update value](#billing-automation-accounting-category-assignment-array-update-value) | optional, max length 100 characters | List of `Accounting Categories` with their `ItemTypes` that will be applied as billing automation condition (or `null` should it not be updated). | #### Billing automation item types update parameters | Property | Type | Contract | Description | | -------------------- | ------------------------------------------------------------------------- | -------- | --------------------------------------------------------- | | `SpaceOrder` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Space order (or `null` should it not be updated). | | `CityTax` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | City tax (or `null` should it not be updated). | | `AllProducts` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Products (or `null` should it not be updated). | | `Deposits` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Deposits(or `null` should it not be updated). | | `AdditionalExpenses` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Additional expenses (or `null` should it not be updated). | | `AllCustomItems` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Custom items (or `null` should it not be updated). | #### Billing automation accounting category assignment array update value | Property | Type | Contract | Description | | -------- | ---------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------- | | `Value` | array of [Billing automation accounting category assignment](#billing-automation-accounting-category-assignment) | optional | Value which is to be updated. | ## Delete billing automations Deletes specified billing automations. ### Request `[PlatformAddress]/api/connector/v1/billingAutomations/delete` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "BillingAutomationIds": [ "ecd64eec-4423-4c65-b844-814b9199856d", "13e6b16e-39bc-4cb1-8610-70ecdb4f91cc" ] } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `BillingAutomationIds` | array of string | required, max 100 items | Unique identifier of the billing automations to be deleted. | ### Response ```javascript {} ``` # Bills ## Get all bills Returns all bills, optionally filtered by customers, identifiers and other filters. Note this operation uses [Pagination](/connector-api/guidelines/pagination). ### Request `[PlatformAddress]/api/connector/v1/bills/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "Extent": { "Items": false }, "ClosedUtc": { "StartUtc": "2020-02-05T00:00:00Z", "EndUtc": "2020-02-10T00:00:00Z" }, "CreatedUtc": { "StartUtc": "2020-02-05T00:00:00Z", "EndUtc": "2020-02-10T00:00:00Z" }, "UpdatedUtc": { "StartUtc": "2020-02-05T00:00:00Z", "EndUtc": "2020-02-10T00:00:00Z" }, "BillIds": [ "e654f217-d1b5-46be-a820-e93ba568dfac" ], "CustomerIds": [ "fe795f96-0b64-445b-89ed-c032563f2bac" ], "State": "Closed", "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "Limitation": { "Count": 100, "Cursor": "e7f26210-10e7-462e-9da8-ae8300be8ab7" } } ``` | 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. | | `IssuedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the `Bill` was issued. | | `PaidUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the `Bill` was paid. | | `DueUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the `Bill` is due to be paid. | | `CreatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the `Bill` was created. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the `Bill` was updated. | | `BillIds` | array of string | optional, max 1000 items | Unique identifiers of the `Bills`. Required if no other filter is provided. | | `CustomerIds` | array of string | optional, max 1000 items | Unique identifiers of the `Customers`. | | `State` | [Bill state](#bill-state) | optional | State the bills should be in. If not specified, `Open` and `Closed` bills are returned. | | `Type` | [Bill type](#bill-type) | optional | Type of the bills. If not specified, all types are returned. | | `CorrectionState` | array of [Bill correction state](#bill-correction-state) | optional | Whether to return regular bills, corrective bills, or both. If `BillIds` are specified, defaults to both, otherwise defaults to `Bill`. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | | ~~`Extent`~~ | [~~Bill extent~~](#bill-extent) | ~~optional~~ | ~~Extent of data to be returned. E.g. it is possible to specify that together with the bills, payments and revenue items should be also returned.~~ **Deprecated!** Use `orderItems/getAll` and `payments/getAll` with `BillIds` filter instead. | | ~~`ClosedUtc`~~ | [~~Time interval~~](/connector-api/operations/_objects#time-interval) | ~~optional, max length 3 months~~ | ~~Interval in which the `Bill` was closed.~~ **Deprecated!** Use `IssuedUtc` instead. | #### Bill extent Extent of data to be returned. E.g. it is possible to specify that together with the bills, payments and revenue items should be also returned. **Deprecated!** | Property | Type | Contract | Description | | ----------- | ----------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ~~`Items`~~ | ~~boolean~~ | ~~required~~ | ~~Whether the response should contain payments and revenue items.~~ **Deprecated!** Use `orderItems/getAll` and `payments/getAll` with `BillIds` filter instead. | #### Bill state * `Open` * `Closed` #### Bill type * `Receipt` - Default; the bill has been paid in full; only applicable after the bill is closed. * `Invoice` - Bill has not been paid in full but an invoice has been issued to request payment. ### Response ```javascript { "Bills": [ { "Id": "ea087d64-3901-4eee-b0b7-9fce4c58a005", "Name": "Accommodation Charges", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "AccountId": "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f", "AccountType": "Company", "CustomerId": null, "CompanyId": null, "AssociatedAccountIds": [ "fadd5bb6-b428-45d5-94f8-fd0d89fece6d" ], "CounterId": null, "State": "Closed", "Type": "Invoice", "Number": "29", "VariableSymbol": null, "CreatedUtc": "2017-01-31T10:48:06Z", "IssuedUtc": "2017-01-31T10:58:06Z", "TaxedUtc": null, "PaidUtc": null, "DueUtc": null, "LastReminderDateUtc": null, "UpdatedUtc": "2017-01-31T10:58:06Z", "PurchaseOrderNumber": "XX-123", "Notes": "", "Options": { "DisplayCustomer": true, "DisplayTaxation": true, "TrackReceivable": true, "DisplayCid": false, "Rebated": false }, "Revenue": [], "Payments": [], "OrderItems": [], "PaymentItems": [], "AssigneeData": null, "OwnerData": { "Discriminator": "BillCompanyData", "Value": { "Id": "26afba60-06c3-455b-92db-0e3983be0b1d", "Address": { "Line1": "I.P. Pavlova 5", "Line2": null, "City": "Prague", "PostalCode": "12000", "SubdivisionCode": "CZ-PR", "CountryCode": "CZ" }, "LegalIdentifiers": { "TaxIdentifier": "CZ24227781", "CityOfRegistration": "Prague" }, "BillingCode": "Billing code value", "Name": "Acme, Inc.", "FiscalIdentifier": "Fiscal identifier", "AdditionalTaxIdentifier": "Additional tax identifier", "DUNS": "150483782", "Telephone": "+420123456789", "TaxIdentifier": "CZ24227781", "InvoicingEmail": "billing@acme.example", "Department": "Billing" } }, "CompanyDetails": null, "AssociatedAccountData": [ { "Discriminator": "BillCompanyData", "BillCustomerData": null, "BillCompanyData": { "Id": "26afba60-06c3-455b-92db-0e3983be0b1d", "Address": { "Line1": "I.P. Pavlova 5", "Line2": null, "City": "Prague", "PostalCode": "12000", "SubdivisionCode": "CZ-PR", "CountryCode": "CZ" }, "LegalIdentifiers": { "TaxIdentifier": "CZ24227781", "CityOfRegistration": "Prague" }, "BillingCode": "Billing code value", "Name": "Acme, Inc.", "FiscalIdentifier": "Fiscal identifier", "AdditionalTaxIdentifier": "Additional tax identifier", "DUNS": "150483782", "Telephone": "+420123456789", "TaxIdentifier": "CZ24227781", "InvoicingEmail": "billing@acme.example", "Department": "Billing" } } ], "EnterpriseData": { "AdditionalTaxIdentifier": "XY00112233445", "CompanyName": "The Sample Hotel Group AS", "BankAccount": "CZ3808000000000012345678", "BankName": "CESKA SPORITELNA A.S.", "Iban": "CZ6508000000192000145399", "Bic": "GIBACZPX" }, "CorrectionState": "Bill", "CorrectionType": null, "CorrectedBillId": null } ], "Cursor": "ea087d64-3901-4eee-b0b7-9fce4c58a005" } ``` | Property | Type | Contract | Description | | -------- | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Bills` | array of [Bill](#bill) | required | The filtered bills. | | `Cursor` | string | optional | Unique identifier of the last and hence oldest bill returned. This can be used in `Limitation` in a subsequent request to fetch the next batch of older bills. | ## Get bill PDF Generates a PDF document of the specified bill. If the PDF cannot be returned immediately, retry the call later with the unique event identifier returned by the first invocation as `BillPrintEventId`. This operation is subject to the [Mews Operations quota](https://help.mews.com/s/article/Quotas-in-Mews-Operations) "Property Financial Document Print Event Weekly Count". Each bill can be printed or previewed up to 30 times within 7 days. Requests that include an existing `BillPrintEventId` do not count against this quota. ### Request `[PlatformAddress]/api/connector/v1/bills/getPdf` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "BillId": "44eba542-193e-47c7-8077-abd7008eb206", "PdfTemplate": "Detailed" } ``` | 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. | | `BillId` | string | required | Unique identifier of the [Bill](#bill) to be printed. | | `BillPrintEventId` | string | optional | Identifier of an existing bill print event returned by a previous call. Provide this value to retry retrieval of a pending PDF without consuming its "Property Financial Document Print Event Weekly Count" quota. | | `PdfTemplate` | [Bill PDF template type](#bill-pdf-template-type) | optional | Bill PDF template type. If not specified, the default template is used. | | `PrintReason` | string | optional, max length 255 characters | The reason for reprinting the bill with different template. Required for France LE. | #### Bill PDF template type * `Detailed` - Detailed overview. Items are grouped by the reservation, item type and price, and consumption date. * `Consumption` - Overview by date (no reservation details). Items of the same type and price are grouped by consumption date. * `Reservation` - Overview by reservation (no date). Items of the same type and price are grouped by reservation. * `OrderItem` - Consumption overview (not fiscal document). Items are grouped by the item type and price without reservation details and consumption date. * `Guest` - Overview by guest. Items are grouped by guest, reservation, consumption date, and item type. ### Response ```javascript { "BillId": "44eba542-193e-47c7-8077-abd7008eb206", "Result": { "Discriminator": "BillPdfFile", "Value": { "Base64Data": "JVBERi0xLj..." } } } ``` | Property | Type | Contract | Description | | -------- | --------------------------------------------------------------- | -------- | -------------------------------------- | | `BillId` | string | required | Unique identifier of the printed bill. | | `Result` | [Bill PDF result discriminator](#bill-pdf-result-discriminator) | required | The result of operation. | #### Bill PDF result discriminator | Property | Type | Contract | Description | | --------------- | --------------------------------------------------------------- | -------- | ----------------------------------------------- | | `Discriminator` | [Bill PDF result discriminator](#bill-pdf-result-discriminator) | required | Determines type of value. | | `Value` | object | required | Structure of object depends on `Discriminator`. | #### Bill PDF result discriminator * `BillPdfFile` - PDF version of a `Bill` was successfully created, `Value` is `BillPdfFile`. * `BillPrintEvent` - PDF version of a `Bill` couldn't be created at this moment (for example bill haven't been reported to authorities yet), `Value` is `BillPrintEvent` #### Bill PDF file | Property | Type | Contract | Description | | ------------ | ------ | -------- | ------------------------ | | `Base64Data` | string | required | Base64 encoded PDF file. | #### Bill print event | Property | Type | Contract | Description | | ------------------ | ------ | -------- | ---------------------------------------------------------------------------------- | | `BillPrintEventId` | string | required | Unique identifier of print event. Must be used in retry calls to retrieve the PDF. | ## Add bill Creates new empty bill assigned to specified account. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/bills/add` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Bills": [ { "AccountId": "a5786a7b-a388-43cc-a838-abd7007b5ff7", "Name": "Bill of Joe Doe" } ] } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `Bills` | array of [Bill parameters](#bill-parameters) | required, max 1000 items | Information about bills to be created. | #### Bill parameters | Property | Type | Contract | Description | | --------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `AccountId` | string | required | Unique identifier of the account (`Customer` or `Company`) the bill is issued to. Company billing may not be enabled for your integration. | | `AssociatedAccountId` | string | optional | Account that has a possible link with the owner of the bill. | | `Name` | string | optional | Name of the newly created bill. | ### Response ```javascript { "BillId": "44eba542-193e-47c7-8077-abd7008eb206", "Result": { "Discriminator": "BillPdfFile", "Value": { "Base64Data": "JVBER....." } } } ``` | Property | Type | Contract | Description | | -------- | ---------------------- | -------- | ------------------ | | `Bills` | array of [Bill](#bill) | required | The created bills. | ## Update bills > ### Restricted! > > This operation is currently in beta-test and as such it is subject to change. Updates one or more existing bills in the system. Closed bills cannot be updated. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/bills/update` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "BillsUpdates": [ { "BillId": "ea087d64-3901-4eee-b0b7-9fce4c58a005", "AccountId": { "Value": "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f" }, "AssociatedAccountIds": { "Value": [ "fadd5bb6-b428-45d5-94f8-fd0d89fece6d" ] } } ], "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `BillsUpdates` | array of [Bill update parameters](#bill-update-parameters) | required, max 10 items | Information about bills to be updated. | #### Bill update parameters | Property | Type | Contract | Description | | ---------------------- | ------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | `BillId` | string | required | Unique identifier of the bill to update. | | `AccountId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique identifier of the account (`Customer` or `Company`) the bill is issued to (or null if the account should not be updated). | | `AssociatedAccountIds` | [Associated account IDs update parameters](#associated-account-ids-update-parameters) | optional | Unique identifiers of the `Customer` or `Company` that are associated to the bill (or null if the account should not be updated). | #### Associated account IDs update parameters Has same structure as [Array of strings update value](/connector-api/operations/_objects#array-of-strings-update-value). | Property | Type | Contract | Description | | -------- | --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Value` | array of string | optional, max 1 item | Unique identifiers of the `Customer` or `Company` that are associated to the bill. Set to `null` to remove all associated accounts. Note that only single associated account is currently supported. | ### Response ```javascript { "Bills": [ { "Id": "ea087d64-3901-4eee-b0b7-9fce4c58a005", "Name": "Accommodation Charges", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "AccountId": "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f", "AccountType": "Company", "CustomerId": null, "CompanyId": null, "AssociatedAccountIds": [ "fadd5bb6-b428-45d5-94f8-fd0d89fece6d" ], "CounterId": null, "State": "Closed", "Type": "Invoice", "Number": "29", "VariableSymbol": null, "CreatedUtc": "2017-01-31T10:48:06Z", "IssuedUtc": "2017-01-31T10:58:06Z", "TaxedUtc": null, "PaidUtc": null, "DueUtc": null, "LastReminderDateUtc": null, "UpdatedUtc": "2017-01-31T10:58:06Z", "PurchaseOrderNumber": "XX-123", "Notes": "", "Options": { "DisplayCustomer": true, "DisplayTaxation": true, "TrackReceivable": true, "DisplayCid": false, "Rebated": false }, "Revenue": [], "Payments": [], "OrderItems": [], "PaymentItems": [], "AssigneeData": null, "OwnerData": { "Discriminator": "BillCompanyData", "Value": { "Id": "26afba60-06c3-455b-92db-0e3983be0b1d", "Address": { "Line1": "I.P. Pavlova 5", "Line2": null, "City": "Prague", "PostalCode": "12000", "SubdivisionCode": "CZ-PR", "CountryCode": "CZ" }, "LegalIdentifiers": { "TaxIdentifier": "CZ24227781", "CityOfRegistration": "Prague" }, "BillingCode": "Billing code value", "Name": "Acme, Inc.", "FiscalIdentifier": "Fiscal identifier", "AdditionalTaxIdentifier": "Additional tax identifier", "DUNS": "150483782", "Telephone": "+420123456789", "TaxIdentifier": "CZ24227781", "InvoicingEmail": "billing@acme.example", "Department": "Billing" } }, "CompanyDetails": null, "AssociatedAccountData": [ { "Discriminator": "BillCompanyData", "BillCustomerData": null, "BillCompanyData": { "Id": "26afba60-06c3-455b-92db-0e3983be0b1d", "Address": { "Line1": "I.P. Pavlova 5", "Line2": null, "City": "Prague", "PostalCode": "12000", "SubdivisionCode": "CZ-PR", "CountryCode": "CZ" }, "LegalIdentifiers": { "TaxIdentifier": "CZ24227781", "CityOfRegistration": "Prague" }, "BillingCode": "Billing code value", "Name": "Acme, Inc.", "FiscalIdentifier": "Fiscal identifier", "AdditionalTaxIdentifier": "Additional tax identifier", "DUNS": "150483782", "Telephone": "+420123456789", "TaxIdentifier": "CZ24227781", "InvoicingEmail": "billing@acme.example", "Department": "Billing" } } ], "EnterpriseData": { "AdditionalTaxIdentifier": "XY00112233445", "CompanyName": "The Sample Hotel Group AS", "BankAccount": "CZ3808000000000012345678", "BankName": "CESKA SPORITELNA A.S.", "Iban": "CZ6508000000192000145399", "Bic": "GIBACZPX" }, "CorrectionState": "Bill", "CorrectionType": null, "CorrectedBillId": null } ] } ``` | Property | Type | Contract | Description | | -------- | ---------------------- | -------- | -------------- | | `Bills` | array of [Bill](#bill) | required | Updated bills. | #### Bill | Property | Type | Contract | Description | | ----------------------- | --------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the bill. | | `Name` | string | optional | Name of the bill. | | `EnterpriseId` | string | required | Unique identifier of the `Enterprise`. | | `AccountId` | string | required | Unique identifier of the account (`Customer` or `Company`) the bill is issued to. | | `AccountType` | [Account type](/connector-api/operations/accounts#account-type) | required | A discriminator specifying the [type of account](/connector-api/operations/accounts#account-type), i.e. `Customer` or `Company`. | | `AssociatedAccountIds` | array of string | optional | Unique identifiers of the `Customers` or `Companies` that are associated to the bill. | | `CounterId` | string | optional | Unique identifier of the bill `Counter`. | | `State` | [Bill state](#bill-state) | required | Whether the bill is `Open` or `Closed`. | | `Type` | [Bill type](#bill-type) | required | After a bill is closed, the Bill Type is set to `Receipt` or `Invoice`. `Receipt` indicates that the bill has been fully paid and the balance is zero. `Invoice` indicates that the bill has not yet been fully paid but an invoice has been issued. Prior to closing, Bill Type should not be used. | | `Number` | string | optional | Number of the bill. | | `VariableSymbol` | string | optional | Variable symbol of the bill. | | `CreatedUtc` | string | required | Date and time of the bill creation in UTC timezone in ISO 8601 format. | | `IssuedUtc` | string | optional | Date and time of the bill issuance in UTC timezone in ISO 8601 format. | | `TaxedUtc` | string | optional | Taxation date of the bill in UTC timezone in ISO 8601 format. | | `PaidUtc` | string | optional | Date when the bill was paid in UTC timezone in ISO 8601 format. | | `DueUtc` | string | optional | Bill due date and time in UTC timezone in ISO 8601 format. | | `LastReminderDateUtc` | string | optional | Date and time when an email reminder to pay an invoice was last sent, in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Date and time when the bill was last updated, in UTC timezone in ISO 8601 format. | | `PurchaseOrderNumber` | string | optional | Unique number of the purchase order from the buyer. | | `Notes` | string | optional | Additional notes. | | `Options` | [Bill options](#bill-options) | optional | Options of the bill. | | `OwnerData` | [Bill owner data](#bill-owner-data) | optional | Additional information about owner of the bill. Can be a `Customer` or `Company`. Persisted at the time of closing of the bill. | | `AssociatedAccountData` | array of [Associated account bill data](#associated-account-bill-data) | optional | Additional information about the associated account of the bill. Can be a `Customer` or `Company`. Persisted at the time of closing of the bill. Currently only one account can be associated with a bill, but this may be extended in future. | | `EnterpriseData` | [Bill enterprise data](#bill-enterprise-data) | optional | Additional information about the enterprise issuing the bill, including bank account details. Persisted at the time of closing of the bill. | | `CorrectionState` | [Bill correction state](#bill-correction-state) | required | Whether the bill is a regular bill or a corrective bill. | | `CorrectionType` | [Bill correction type](#bill-correction-type) | optional | Type of correction. | | `CorrectedBillId` | string | optional | The ID of the bill that the corrective bill corrects. If the corrected bill was deleted, this field is `null`. | | ~~`CustomerId`~~ | ~~string~~ | ~~optional~~ | ~~Unique identifier of the `Customer` the bill is issued to.~~ **Deprecated!** Use `AccountId` instead. | | ~~`CompanyId`~~ | ~~string~~ | ~~optional~~ | ~~Unique identifier of the `Company` specified in `CompanyDetails` or the `Company` the bill is issued to.~~ **Deprecated!** Use `AssociatedAccountIds` instead. | | ~~`Revenue`~~ | ~~array of~~ [~~Accounting item~~](/connector-api/operations/accountingitems#accounting-item) | ~~optional~~ | **Deprecated!** Use `orderItems/getAll` with `BillId` instead. | | ~~`Payments`~~ | ~~array of~~ [~~Accounting item~~](/connector-api/operations/accountingitems#accounting-item) | ~~optional~~ | **Deprecated!** Use `payments/getAll` with `BillId` instead. | | ~~`OrderItems`~~ | ~~array of~~ [~~Order item~~](/connector-api/operations/accountingitems#order-item) | ~~optional~~ | ~~The order items (consumed items such as nights or products) on the bill.~~ **Deprecated!** Use `orderItems/getAll` with `BillId` instead. | | ~~`PaymentItems`~~ | ~~array of~~ [~~Payment item~~](/connector-api/operations/accountingitems#payment-item) | ~~optional~~ | ~~The payment items (such as cash, credit card payments or invoices) on the bill.~~ **Deprecated!** | | ~~`AssigneeData`~~ | [~~Bill assignee data~~](#bill-assignee-data) | ~~optional~~ | **Deprecated!** Use `OwnerData` instead. | | ~~`CompanyDetails`~~ | [~~Bill company data~~](#bill-company-data) | ~~optional~~ | ~~Additional information about the company assigned to the bill. Not the same as the owner. Persisted at the time of closing of the bill.~~ **Deprecated!** Use `AssociatedAccountData` instead. | #### Bill state * `Open` * `Closed` #### Bill type * `Receipt` - Default; the bill has been paid in full; only applicable after the bill is closed. * `Invoice` - Bill has not been paid in full but an invoice has been issued to request payment. #### Bill options Options of the bill. | Property | Type | Contract | Description | | ----------------- | ------- | -------- | -------------------------------------------------------------------------------------- | | `DisplayCustomer` | boolean | required | Display customer information on a bill. | | `DisplayTaxation` | boolean | required | Display taxation detail on a bill. | | `TrackReceivable` | boolean | required | Tracking of payments is enabled for bill, only applicable for `BillType` of `Invoice`. | | `DisplayCid` | boolean | required | Display CID number on bill, only applicable for `BillType` of `Invoice`. | | `Rebated` | boolean | required | Whether the bill is rebated (both fully or partially). | #### Bill assignee data | Property | Type | Contract | Description | | --------------- | ----------------------------------------------------------------------------------------- | -------- | ----------------------------------------------- | | `Discriminator` | [Bill associated account data discriminator](#bill-associated-account-data-discriminator) | required | Determines type of value. | | `Value` | object | required | Structure of object depends on `Discriminator`. | #### Bill associated account data discriminator * `BillCustomerData` * `BillCompanyData` #### Bill company data | Property | Type | Contract | Description | | ------------------------- | -------------------------------------------------------------- | -------- | ------------------------------------------------------------------- | | `Id` | string | optional | ID of the `Company`. | | `Address` | [Address](/connector-api/operations/addresses#account-address) | optional | Address of the company. | | `LegalIdentifiers` | object | optional | The set of `LegalIdentifiers` for the company. | | `BillingCode` | string | optional | A unique code for Mews to list on invoices it sends to the company. | | `Name` | string | required | Name of the company. | | `FiscalIdentifier` | string | optional | Fiscal identifier of the company. | | `AdditionalTaxIdentifier` | string | optional | Additional tax identifier of the company. | | `DUNS` | string | optional | DUNS (Data Universal Numbering System) number of the company. | | `Telephone` | string | optional | Company telephone number. | | `TaxIdentifier` | string | optional | Tax identifier of the company. | | `InvoicingEmail` | string | optional | Invoicing email of the company. | | `Department` | string | optional | Department of the company. | #### Bill customer data | Property | Type | Contract | Description | | ------------------ | -------------------------------------------------------------- | -------- | -------------------------------------------------------------------- | | `Id` | string | required | ID of the `Customer` to whom the bill was assigned. | | `Address` | [Address](/connector-api/operations/addresses#account-address) | optional | Address of the customer. | | `LegalIdentifiers` | object | optional | The set of `LegalIdentifiers` for the customer. | | `BillingCode` | string | optional | A unique code for Mews to list on invoices it sends to the customer. | | `LastName` | string | required | Last name of the customer. | | `FirstName` | string | optional | First name of the customer. | | `SecondLastName` | string | optional | Second last name of the customer. | | `TitlePrefix` | [Title](/connector-api/operations/customers#title) | optional | Title prefix of the customer. | | `TaxIdentifier` | string | optional | Tax identifier of the customer. | #### Bill owner data | Property | Type | Contract | Description | | --------------- | ----------------------------------------------------------------------------------------- | -------- | ----------------------------------------------- | | `Discriminator` | [Bill associated account data discriminator](#bill-associated-account-data-discriminator) | required | Determines type of value. | | `Value` | object | required | Structure of object depends on `Discriminator`. | #### Associated account bill data | Property | Type | Contract | Description | | ------------------ | ----------------------------------------------------------------------------------------- | -------- | ------------------------------------------ | | `Discriminator` | [Bill associated account data discriminator](#bill-associated-account-data-discriminator) | required | Determines type of value. | | `BillCustomerData` | [Bill customer data](#bill-customer-data) | optional | Associated account bill data for customer. | | `BillCompanyData` | [Bill company data](#bill-company-data) | optional | Associated account bill data for company. | #### Bill enterprise data Additional information about the enterprise issuing the bill, including bank account details. Persisted at the time of closing of the bill. | Property | Type | Contract | Description | | ------------------------- | ------ | -------- | ---------------------------------------------------- | | `AdditionalTaxIdentifier` | string | optional | Enterprise additional tax identifier. | | `CompanyName` | string | optional | Enterprise company name. | | `BankAccount` | string | optional | Enterprise bank account. | | `BankName` | string | optional | Enterprise bank name. | | `Iban` | string | optional | Enterprise IBAN (International Bank Account Number). | | `Bic` | string | optional | Enterprise BIC (Bank Identifier Code). | #### Bill correction state * `Bill` - Regular bill. * `CorrectiveBill` - Corrective bill, i.e. the `CorrectionType` is either `Edit`, `Cancellation`, or `ReceivablePaymentsBalance`. #### Bill correction type * `Cancellation` * `Edit` * `CreditNote` * `Reinstatement` * `ReceivablePaymentsBalance` ## Delete bill Removes selected bills. Bill must be empty, otherwise it's not possible to delete it. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/bills/delete` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "BillIds": [ "177966b7-f3d9-42b7-ba49-abd80057329b" ], "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `BillIds` | array of string | required, max 1000 items | Unique identifiers of the [Bill](#bill)s to be deleted. | ### Response ```javascript {} ``` ## Close bill Closes a bill so no further modification to it is possible. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/bills/close` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "BillId": "44eba542-193e-47c7-8077-abd7008eb206", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Type": "Receipt", "BillCounterId": "84b25778-c1dd-48dc-8c00-ab3a00b6df14", "FiscalMachineId": null, "Options": { "DisplayCustomer": { "Value": false }, "DisplayTaxation": null }, "TaxedDate": { "Value": "2020-07-07" }, "DueDate": { "Value": "2020-07-14" }, "VariableSymbol": { "Value": "5343" }, "AccountTaxIdentifier": { "Value": "446768" }, "AccountAddress": { "Line1": "Astronautů 2", "Line2": "", "City": "Havířov", "PostalCode": "736 01", "CountryCode": "CZ", "CountrySubdivisionCode": null }, "PurchaseOrderNumber": { "Value": "XX-123" }, "Notes": { "Value": "Bill closing note" }, "AssociatedAccountData": [ { "Id": "84b25778-c1dd-48dc-8c00-ab3a00b6df14", "TaxIdentifier": { "Value": "123459" }, "Address": { "Line1": "Astronautů 2", "Line2": "", "City": "Havířov", "PostalCode": "736 01", "CountryCode": "CZ", "CountrySubdivisionCode": 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `BillId` | string | required | Unique identifier of the [Bill](#bill) to be closed. | | `Type` | [Bill type](#bill-type) | required | After a bill is closed, the Bill Type is set to `Receipt` or `Invoice`. `Receipt` indicates that the bill has been fully paid and the balance is zero. `Invoice` indicates that the bill has not yet been fully paid but an invoice has been issued. Prior to closing, Bill Type should not be used. | | `BillCounterId` | string | optional | Unique identifier of the [Counter](/connector-api/operations/counters#counter) to be used for closing. Default one is used when no value is provided. | | `FiscalMachineId` | string | optional | Unique identifier of the [Fiscal Machine](/connector-api/operations/devices#device) to be used for closing. Default one is used when no value is provided. | | `Options` | [Bill options parameters](#bill-options-parameters) | optional | Options of the bill. If not provided, both DisplayCustomer and DisplayTaxation are set by default. | | `TaxedDate` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Date of consumption for tax purposes. Can be used only with `Type` of `Invoice`. | | `DueDate` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Deadline when bill is due to be paid. Can be used only with `Type` of `Invoice`. | | `VariableSymbol` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Optional unique identifier of requested payment. Can be used only with `Type` of `Invoice`. | | `AccountTaxIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Tax identifier of account to be put on a bill. | | `PurchaseOrderNumber` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique number of the purchase order from the buyer. | | `Notes` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Notes to be attached to bill. | | `AccountAddress` | [Address parameters](/connector-api/operations/companies#address-parameters) | optional | Address of the account to be displayed on bill. Overrides the default one taken from account profile. | | `AssociatedAccountData` | array of [Bill close account parameters](#bill-close-account-parameters) | optional, max 1 item | Account data of the associated account on a bill. Currently one object is supported and only populated when the bill is closed. | | ~~`TaxIdentifier`~~ | [~~String update value~~](/connector-api/operations/_objects#string-update-value) | ~~optional~~ | ~~Tax identifier of account to be put on a bill.~~ **Deprecated!** Use `AccountTaxIdentifier` or `AssociatedAccountData` instead. | | ~~`CompanyTaxIdentifier`~~ | [~~String update value~~](/connector-api/operations/_objects#string-update-value) | ~~optional~~ | ~~Tax identifier of company to be put on a bill.~~ **Deprecated!** Use `AccountTaxIdentifier` or `AssociatedAccountData` instead. | | ~~`Address`~~ | [~~Address parameters~~](/connector-api/operations/companies#address-parameters) | ~~optional~~ | ~~Address of the account to be displayed on bill. Overrides the default one taken from account profile.~~ **Deprecated!** Use `AccountAddress` or `AssociatedAccountData` instead. | #### Bill options parameters | Property | Type | Contract | Description | | ----------------- | ------------------------------------------------------------------------- | -------- | --------------------------------------- | | `DisplayCustomer` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | required | Display customer information on a bill. | | `DisplayTaxation` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | required | Display taxation detail on a bill. | #### Bill close account parameters | Property | Type | Contract | Description | | --------------- | ----------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the associated account (`Customer` or `Company`) the bill is associated to. | | `TaxIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Tax identifier of the associated account to be put on a bill. | | `Address` | [Address parameters](/connector-api/operations/companies#address-parameters) | optional | Address of the associated account to be displayed on bill. Overrides the default one taken from account profile. | ### Response ```javascript { "BillId": "44eba542-193e-47c7-8077-abd7008eb206", "Result": { "Discriminator": "BillPdfFile", "Value": { "Base64Data": "JVBER....." } } } ``` | Property | Type | Contract | Description | | -------- | ---------------------- | -------- | ----------------- | | `Bills` | array of [Bill](#bill) | required | The closed bills. | # Business segments ## Get all business segments Returns all business segments. This operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/businessSegments/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "Ids": [ "7760b5cb-a666-41bb-9758-76bf5d1df399", "54ec08b6-e6fc-48e9-b8ae-02943e0ac693" ], "ServiceIds": [ "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "8c1bd738-a505-4b29-aa71-9ecc2982b843" ], "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 `Business segment`. | | `ServiceIds` | array of string | optional, max 1000 items | Unique identifiers of the `Services` from which the business segments are requested. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval of `Business segment` last update date and time. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted or both records. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "BusinessSegments": [ { "Id": "7760b5cb-a666-41bb-9758-76bf5d1df399", "ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "IsActive": true, "Name": "Business", "CreatedUtc": "2023-10-01T00:00:00Z", "UpdatedUtc": "2023-10-01T00:00:00Z" }, { "Id": "54ec08b6-e6fc-48e9-b8ae-02943e0ac693", "ServiceId": "8c1bd738-a505-4b29-aa71-9ecc2982b843", "IsActive": true, "Name": "Leisure", "CreatedUtc": "2023-10-01T00:00:00Z", "UpdatedUtc": "2023-10-01T00:00:00Z" } ], "Cursor": "54ec08b6-e6fc-48e9-b8ae-02943e0ac693" } ``` | Property | Type | Contract | Description | | ------------------ | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BusinessSegments` | array of [Business segment](#business-segment) | required | Business segments. | | `Cursor` | string | optional | Unique identifier of the last and hence oldest business segment item returned. This can be used in Limitation in a subsequent request to fetch the next batch of older business segment. | #### Business segment | Property | Type | Contract | Description | | ------------ | ------- | -------- | ------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the business segment. | | `ServiceId` | string | required | Unique identifier of the `Service`. | | `IsActive` | boolean | required | Whether the business segment is still active. | | `Name` | string | required | Name of the business segment. | | `CreatedUtc` | string | required | Creation date and time of the business segment in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the business segment in UTC timezone in ISO 8601 format. | # Cancellation policies ## Get all cancellation policies (ver 2026-07-31) > ### Restricted! > > This operation is currently in beta-test and as such it is subject to change. Returns the current versions of cancellation policies within the enterprise scope in the same shape as the `add`, `update` operations, including policies that are not currently assigned to any rate or reservation. Historical versions produced by fee-affecting updates are not returned. Optionally filtered by `CancellationPolicyIds`, `UpdatedUtc`, and `ActivityStates`; when no filter is provided all current cancellation policies within the enterprise scope are returned. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/cancellationPolicies/getAll/2026-07-31` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CancellationPolicyIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "UpdatedUtc": { "StartUtc": "2026-07-01T00:00:00Z", "EndUtc": "2026-07-31T00:00:00Z" }, "ActivityStates": [ "Active" ], "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "Limitation": { "Count": 100 } } ``` | 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. | | `CancellationPolicyIds` | array of string | optional, max 100 items | Unique identifiers of the requested cancellation policies. If not specified, all current cancellation policy versions within the enterprise scope are returned. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the cancellation policy was updated. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted, or both types of record. If not specified, only active records will be returned. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "CancellationPolicies": [ { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "CreatedUtc": "2023-02-02T00:00:00Z", "UpdatedUtc": "2023-02-02T00:00:00Z", "IsActive": true, "Applicability": "Start", "FeeExtents": [ "TimeUnits", "Products" ], "ApplicabilityOffset": "P0M-1DT0H0M0S", "FeeMaximumTimeUnits": 1, "AbsoluteFee": { "Currency": "EUR", "Value": 50 }, "RelativeFee": 0.5, "Name": "Standard cancellation policy", "ExternalIdentifier": "standard-policy", "IsPortfolioManaged": false } ], "Cursor": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | Property | Type | Contract | Description | | ---------------------- | ---------------------------------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------- | | `CancellationPolicies` | array of [Cancellation policy modification data](#cancellation-policy-modification-data) | required, max 1000 items | The requested cancellation policies. | | `Cursor` | string | optional | Opaque pagination cursor which can be used in `Limitation` to fetch further cancellation policies. | #### Cancellation policy modification data | Property | Type | Contract | Description | | --------------------- | --------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the cancellation policy. | | `EnterpriseId` | string | required | Unique identifier of the enterprise the cancellation policy belongs to. | | `CreatedUtc` | string | required | Creation date and time of the cancellation policy in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the cancellation policy in UTC timezone in ISO 8601 format. | | `IsActive` | boolean | required | Whether the cancellation policy is still active. | | `Applicability` | [Cancellation Policy Applicability](#cancellation-policy-applicability) | required | Applicability mode of the cancellation policy. | | `FeeExtents` | array of [Cancellation Fee Extent](#cancellation-fee-extent) | required | Extent for the cancellation fee, i.e. what should be in scope for the automatic payment. | | `ApplicabilityOffset` | string | required | Offset from which the fee is applied in ISO 8601 duration format. | | `FeeMaximumTimeUnits` | integer | optional | Maximum number of time units the cancellation fee is applicable to. | | `AbsoluteFee` | [Currency value (ver 2023-02-02)](/connector-api/operations/_objects#currency-value-ver-2023-02-02) | required | Absolute value of the fee. | | `RelativeFee` | number | required | Relative value of the fee, as a percentage of the reservation price. | | `Name` | string | optional | Name of the cancellation policy. | | `ExternalIdentifier` | string | optional | Identifier of the cancellation policy from an external system, unique within the enterprise, that can be used to reference the policy from your own system. | | `IsPortfolioManaged` | boolean | required | Whether the cancellation policy is managed by the portfolio. Policies managed by the portfolio cannot be updated or deleted through this resource. | #### Cancellation Policy Applicability * `Creation` * `Start` * `StartDate` #### Cancellation Fee Extent * `Nothing` * `TimeUnits` * `Products` * `Everything` ## Get all cancellation policies > ### Restricted! > > This operation is currently in beta-test and as such it is subject to change. Returns all cancellation policies, filtered by services, rate groups and other filters. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/cancellationPolicies/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "ServiceIds": [ "e654f217-d1b5-46be-a820-e93ba568dfac" ], "CancellationPolicyIds": [ "fe795f96-0b64-445b-89ed-c032563f2bac" ], "RateGroupIds": [ "deb9444e-6897-4f2a-86b4-aff100c2896e" ], "UpdatedUtc": { "StartUtc": "2023-04-27T11:48:57Z", "EndUtc": "2023-04-27T11:48:57Z" }, "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. | | `ServiceIds` | array of string | required, max 100 items | Unique identifiers of the [Service](/connector-api/operations/services#service). | | `CancellationPolicyIds` | array of string | optional, max 1000 items | Unique identifiers of the [Cancellation Policy](#cancellationpolicy). Required if no other filter is provided. | | `RateGroupIds` | array of string | optional, max 1000 items | Unique identifiers of the [Rate group](/connector-api/operations/rates#rategroup). Required if no other filter is provided. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the Cancellation Policy was updated. Required if no other filter is provided. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted, or both types of record. If not specified, only active records will be returned. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "CancellationPolicies": [ { "Id": "769fc613-838f-41a7-ac2a-aff100c3189f", "RateGroupId": "deb9444e-6897-4f2a-86b4-aff100c2896e", "CreatedUtc": "2023-04-27T11:48:57Z", "UpdatedUtc": "2023-04-27T11:48:57Z", "Applicability": "Creation", "FeeExtent": [ "TimeUnits", "Products" ], "ApplicabilityOffset": "0M0D0:0:0.0", "FeeMaximumTimeUnits": 0, "AbsoluteFee": { "Currency": "EUR", "Value": 15 }, "RelativeFee": 0 } ], "Cursor": "769fc613-838f-41a7-ac2a-aff100c3189f" } ``` | Property | Type | Contract | Description | | ---------------------- | ---------------------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CancellationPolicies` | array of [Cancellation Policy](#cancellation-policy) | required, max 1000 items | The filtered cancellation policies. | | `Cursor` | string | optional | Unique identifier of the last and hence oldest cancellation policy returned. This can be used in [Limitation](/connector-api/guidelines/pagination#limitation) in a subsequent request to fetch the next batch of older cancellation policies. | #### Cancellation Policy | Property | Type | Contract | Description | | --------------------- | --------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the cancellation policy. | | `RateGroupId` | string | required | Unique identifier of the rate group the cancellation policy belongs to. | | `CreatedUtc` | string | required | Date and time of the cancellation policy creation in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Date and time of the cancellation policy update in UTC timezone in ISO 8601 format. | | `Applicability` | [Cancellation Policy Applicability](#cancellation-policy-applicability) | required | Applicability mode of the cancellation policy. | | `FeeExtent` | array of [Cancellation Fee Extent](#cancellation-fee-extent) | required | Extent for the cancellation fee, i.e. what should be in scope for the automatic payment. | | `ApplicabilityOffset` | string | required | Offset for order start (assuming Applicability is set to Start) from which the fee is applied. | | `FeeMaximumTimeUnits` | integer | optional | Maximum number of time units the cancellation fee is applicable to. | | `AbsoluteFee` | [Currency value (ver 2023-02-02)](/connector-api/operations/_objects#currency-value-ver-2023-02-02) | required | Absolute value of the fee. | | `RelativeFee` | number | required | Relative value of the fee, as a percentage of the reservation price. | | `IsActive` | boolean | required | Whether the cancellation policy is still active. | #### Cancellation Policy Applicability * `Creation` * `Start` * `StartDate` #### Cancellation Fee Extent * `TimeUnits` * `Products` ## Get cancellation policies by reservations > ### Restricted! > > This operation is currently in beta-test and as such it is subject to change. Gets cancellation policies for enterprise grouped by reservation for granular cancellation policies flow. This operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/cancellationPolicies/getByReservations` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ReservationIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ] } ``` | 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. | | `ReservationIds` | array of string | required, max 100 items | Unique identifiers of the `Reservation`. | ### Response ```javascript { "CancellationPolicies": [ { "ReservationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Policies": [ { "Applicability": "Start", "FeeExtents": [ "TimeUnits", "Products" ], "ApplicabilityOffset": "P10DT20H30M", "FeeMaximumTimeUnits": 1, "AbsoluteFee": { "Currency": "EUR", "Value": 20 }, "RelativeFee": 0.1 } ] }, { "ReservationId": "4d0201db-36f5-428b-8d11-4f0a65e960cc", "Policies": [ { "Applicability": "Start", "FeeExtents": [ "TimeUnits", "Products" ], "ApplicabilityOffset": "P5DT10H30M", "FeeMaximumTimeUnits": 2, "AbsoluteFee": { "Currency": "EUR", "Value": 15 }, "RelativeFee": 0.4 }, { "Applicability": "Start", "FeeExtents": [ "TimeUnits", "Products" ], "ApplicabilityOffset": "P10DT10H30M", "FeeMaximumTimeUnits": 2, "AbsoluteFee": { "Currency": "EUR", "Value": 15 }, "RelativeFee": 0.2 } ] } ] } ``` | Property | Type | Contract | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------ | ---------------------------------------------------------- | | `CancellationPolicies` | array of [Cancellation policy data grouped by reservation](#cancellation-policy-data-grouped-by-reservation) | required, max 1300 items | List of cancellation policies data grouped by reservation. | #### Cancellation policy data grouped by reservation | Property | Type | Contract | Description | | --------------- | -------------------------------------------------------------- | -------- | --------------------------------------- | | `ReservationId` | string | required | Unique identifier of the reservation. | | `Policies` | array of [Cancellation policy data](#cancellation-policy-data) | required | Collection of cancellation policy data. | #### Cancellation policy data | Property | Type | Contract | Description | | --------------------- | --------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `Applicability` | [Cancellation Policy Applicability](#cancellation-policy-applicability) | required | Applicability mode of the cancellation policy. | | `FeeExtents` | array of [Cancellation Fee Extent](#cancellation-fee-extent) | required | Extent for the cancellation fee, i.e. what should be in scope for the automatic payment. | | `ApplicabilityOffset` | string | required | Offset for order start (assuming Applicability is set to Start) from which the fee is applied in ISO 8601 duration format. | | `FeeMaximumTimeUnits` | integer | optional | Maximum number of time units the cancellation fee is applicable to. | | `AbsoluteFee` | [Currency value (ver 2023-02-02)](/connector-api/operations/_objects#currency-value-ver-2023-02-02) | required | Absolute value of the fee. | | `RelativeFee` | number | required | Relative value of the fee, as a percentage of the reservation price. | ## Get cancellation policies by rates > ### Restricted! > > This operation is currently in beta-test and as such it is subject to change. Gets cancellation policies for enterprise grouped by rate for granular cancellation policies flow. This operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/cancellationPolicies/getByRates` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "RateIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ] } ``` | 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. | | `RateIds` | array of string | required, max 100 items | Unique identifiers of the `Rate`. | | `ReservationStartUtc` | string | required | Start of the reservation interval in UTC timezone in ISO 8601 format. | | `ReservationEndUtc` | string | required | End of the reservation interval in UTC timezone in ISO 8601 format. | ### Response ```javascript { "CancellationPolicies": [ { "RateId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Policies": [ { "Applicability": "Start", "FeeExtents": [ "TimeUnits", "Products" ], "ApplicabilityOffset": "P10DT20H30M", "FeeMaximumTimeUnits": 1, "AbsoluteFee": { "Currency": "EUR", "Value": 20 }, "RelativeFee": 0.1 } ] }, { "RateId": "4d0201db-36f5-428b-8d11-4f0a65e960cc", "Policies": [ { "Applicability": "Start", "FeeExtents": [ "TimeUnits", "Products" ], "ApplicabilityOffset": "P5DT10H30M", "FeeMaximumTimeUnits": 2, "AbsoluteFee": { "Currency": "EUR", "Value": 15 }, "RelativeFee": 0.4 }, { "Applicability": "Start", "FeeExtents": [ "TimeUnits", "Products" ], "ApplicabilityOffset": "P10DT10H30M", "FeeMaximumTimeUnits": 2, "AbsoluteFee": { "Currency": "EUR", "Value": 15 }, "RelativeFee": 0.2 } ] } ] } ``` | Property | Type | Contract | Description | | ---------------------- | ---------------------------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------- | | `CancellationPolicies` | array of [Cancellation policy data grouped by rate](#cancellation-policy-data-grouped-by-rate) | required, max 1300 items | List of cancellation policies data grouped by rate. | #### Cancellation policy data grouped by rate | Property | Type | Contract | Description | | ---------- | -------------------------------------------------------------- | -------- | --------------------------------------- | | `RateId` | string | required | Unique identifier of the `Rate`. | | `Policies` | array of [Cancellation policy data](#cancellation-policy-data) | required | Collection of cancellation policy data. | ## Add cancellation policies > ### Restricted! > > This operation is currently in beta-test and as such it is subject to change. Adds one or more cancellation policies to the specified enterprise. This operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/cancellationPolicies/add` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CancellationPolicies": [ { "Applicability": "Start", "FeeExtents": [ "TimeUnits", "Products" ], "ApplicabilityOffset": "P0M-1DT0H0M0S", "FeeMaximumTimeUnits": 1, "AbsoluteFee": { "Currency": "EUR", "Value": 50 }, "RelativeFee": 0.5, "Name": "Standard cancellation policy", "ExternalIdentifier": "standard-policy" } ], "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `CancellationPolicies` | array of [Cancellation policy add parameters](#cancellation-policy-add-parameters) | required, max 100 items | Parameters of the new cancellation policies to be created. | #### Cancellation policy add parameters | Property | Type | Contract | Description | | --------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Applicability` | [Cancellation Policy Applicability](#cancellation-policy-applicability) | required | Applicability mode of the cancellation policy. | | `FeeExtents` | array of [Cancellation Fee Extent](#cancellation-fee-extent) | required, max 10 items | Extent for the cancellation fee, i.e. what should be in scope for the automatic payment. | | `ApplicabilityOffset` | string | optional | Offset from which the fee is applied in ISO 8601 duration format. Defaults to zero when not provided. | | `FeeMaximumTimeUnits` | integer | optional | Maximum number of time units the cancellation fee is applicable to. | | `AbsoluteFee` | [Currency value (ver 2023-02-02)](/connector-api/operations/_objects#currency-value-ver-2023-02-02) | required | Absolute value of the fee. | | `RelativeFee` | number | required | Relative value of the fee, as a percentage of the reservation price. Must be between 0 and 1. Defaults to 0. | | `Name` | string | optional, max length 255 characters | Name of the cancellation policy. | | `ExternalIdentifier` | string | optional, max length 255 characters | Identifier of the cancellation policy from an external system, unique within the enterprise. Use it to reference the policy from your own system. Adding another policy with the same external identifier in the same enterprise is rejected. Note that `add` always creates a new policy; it never updates an existing one matched by this identifier. | ### Response ```javascript { "CancellationPolicies": [ { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "CreatedUtc": "2023-02-02T00:00:00Z", "UpdatedUtc": "2023-02-02T00:00:00Z", "IsActive": true, "Applicability": "Start", "FeeExtents": [ "TimeUnits", "Products" ], "ApplicabilityOffset": "P0M-1DT0H0M0S", "FeeMaximumTimeUnits": 1, "AbsoluteFee": { "Currency": "EUR", "Value": 50 }, "RelativeFee": 0.5, "Name": "Standard cancellation policy", "ExternalIdentifier": "standard-policy", "IsPortfolioManaged": false } ] } ``` | Property | Type | Contract | Description | | ---------------------- | ---------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------ | | `CancellationPolicies` | array of [Cancellation policy modification data](#cancellation-policy-modification-data) | required, max 100 items | Cancellation policies affected by the operation. | ## Update cancellation policies > ### Restricted! > > This operation is currently in beta-test and as such it is subject to change. Updates one or more existing cancellation policies. Only the fields that are set are updated. Cancellation policies managed by portfolio cannot be updated. This operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/cancellationPolicies/update` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CancellationPolicyUpdates": [ { "CancellationPolicyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "AbsoluteFee": { "Value": { "Currency": "EUR", "Value": 75 } }, "RelativeFee": { "Value": 0.75 }, "Name": { "Value": "Updated cancellation policy" } } ], "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `CancellationPolicyUpdates` | array of [Cancellation policy update parameters](#cancellation-policy-update-parameters) | required, max 100 items | Details of the cancellation policies to be updated. | #### Cancellation policy update parameters | Property | Type | Contract | Description | | ---------------------- | ------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `CancellationPolicyId` | string | required | Unique identifier of the cancellation policy to be updated. | | `Applicability` | [Cancellation Policy Applicability update value](#cancellation-policy-applicability-update-value) | optional | Applicability mode of the cancellation policy (or null if it should not be updated). | | `FeeExtents` | [Cancellation Fee Extent array update value](#cancellation-fee-extent-array-update-value) | optional | Extent for the cancellation fee, up to 10 values (or null if it should not be updated). | | `ApplicabilityOffset` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Offset from which the fee is applied in ISO 8601 duration format. Set the inner value to null to reset it to zero (or null if it should not be updated). | | `FeeMaximumTimeUnits` | [Number update value](/connector-api/operations/_objects#number-update-value) | optional | Maximum number of time units the cancellation fee is applicable to. Set the inner value to null to clear it (or null if it should not be updated). | | `AbsoluteFee` | [Currency value (ver 2023-02-02) update value](#currency-value-ver-2023-02-02-update-value) | optional | Absolute value of the fee (or null if it should not be updated). | | `RelativeFee` | [Decimal update value](/connector-api/operations/_objects#decimal-update-value) | optional | Relative value of the fee, as a percentage of the reservation price. Must be between 0 and 1 (or null if it should not be updated). | | `Name` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Name of the cancellation policy. Set the inner value to null to clear it (or null if it should not be updated). | | `ExternalIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Identifier of the cancellation policy from an external system, unique within the enterprise, used to reference the policy from your own system. Set the inner value to null to clear it (or null if it should not be updated). | #### Cancellation Policy Applicability update value | Property | Type | Contract | Description | | -------- | ----------------------------------------------------------------------- | -------- | ----------------------------- | | `Value` | [Cancellation Policy Applicability](#cancellation-policy-applicability) | required | Value which is to be updated. | #### Cancellation Fee Extent array update value | Property | Type | Contract | Description | | -------- | ------------------------------------------------------------ | -------- | ----------------------------- | | `Value` | array of [Cancellation Fee Extent](#cancellation-fee-extent) | optional | Value which is to be updated. | #### Currency value (ver 2023-02-02) update value | Property | Type | Contract | Description | | -------- | --------------------------------------------------------------------------------------------------- | -------- | ----------------------------- | | `Value` | [Currency value (ver 2023-02-02)](/connector-api/operations/_objects#currency-value-ver-2023-02-02) | optional | Value which is to be updated. | ### Response ```javascript { "CancellationPolicies": [ { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "CreatedUtc": "2023-02-02T00:00:00Z", "UpdatedUtc": "2023-02-02T00:00:00Z", "IsActive": true, "Applicability": "Start", "FeeExtents": [ "TimeUnits", "Products" ], "ApplicabilityOffset": "P0M-1DT0H0M0S", "FeeMaximumTimeUnits": 1, "AbsoluteFee": { "Currency": "EUR", "Value": 50 }, "RelativeFee": 0.5, "Name": "Standard cancellation policy", "ExternalIdentifier": "standard-policy", "IsPortfolioManaged": false } ] } ``` | Property | Type | Contract | Description | | ---------------------- | ---------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------ | | `CancellationPolicies` | array of [Cancellation policy modification data](#cancellation-policy-modification-data) | required, max 100 items | Cancellation policies affected by the operation. | ## Delete cancellation policies > ### Restricted! > > This operation is currently in beta-test and as such it is subject to change. Deletes the specified cancellation policies. Cancellation policies managed by portfolio cannot be deleted. This operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/cancellationPolicies/delete` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CancellationPolicyIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `CancellationPolicyIds` | array of string | required, max 100 items | Unique identifiers of the cancellation policies to be deleted. | ### Response ```javascript {} ``` # Cashiers ## Get all cashiers Returns all cashiers. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/cashiers/getAll` ```javascript { "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](#cashier). | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which `Cashier` was updated. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted or both records. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "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](#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. | #### Cashier | Property | Type | Contract | Description | | -------------- | ------- | -------- | ---------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the cashier. | | `EnterpriseId` | string | required | Unique identifier of the [Enterprise](/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. | # Cashier transactions ## Get all cashier transactions Returns all cashier transactions. At least one of the filter parameters `CashierTransactionIds` or `CreatedUtc` must be specified in the request. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/cashierTransactions/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "CashierTransactionIds": [ "177740c3-fec9-4338-a224-a3b03a35b3e1" ], "CreatedUtc": { "StartUtc": "2020-01-05T00:00:00Z", "EndUtc": "2020-01-10T00:00:00Z" }, "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. | | `CashierTransactionIds` | array of string | optional, max 1000 items | Unique identifiers of the Cashier transactions. | | `CreatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which Cashier transaction was created. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "CashierTransactions": [ { "Amount": { "Currency": "EUR", "Value": 100 }, "CashierId": "9a36e3fa-2299-474b-a8a2-5ea4da317abc", "CreatedUtc": "2017-01-10T00:00:00Z", "Id": "177740c3-fec9-4338-a224-a3b03a35b3e1", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Notes": "Cash payment EUR", "Number": "47", "PaymentId": "a68ef257-2fbc-4a4f-85de-59d808cef657" } ], "Cursor": "177740c3-fec9-4338-a224-a3b03a35b3e1" } ``` | Property | Type | Contract | Description | | --------------------- | ---------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CashierTransactions` | array of [Cashier transaction](#cashier-transaction) | required | The collection of cashier transactions. | | `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. | #### Cashier transaction | Property | Type | Contract | Description | | -------------- | --------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the transaction. | | `EnterpriseId` | string | required | Unique identifier of the [Enterprise](/connector-api/operations/enterprises#enterprise). | | `CashierId` | string | required | Unique identifier of the [Cashier](/connector-api/operations/cashiers#cashier). | | `PaymentId` | string | optional | Unique identifier of the corresponding payment [Payment item](/connector-api/operations/accountingitems#payment-item). | | `CreatedUtc` | string | required | Creation date and time of the transaction. | | `Number` | string | required | Number of the transaction. | | `Notes` | string | optional | Additional notes of the transaction. | | `Amount` | [Currency value (ver 2018-06-07)](/connector-api/operations/_objects#currency-value-ver-2018-06-07) | required | Total price of the transaction | | `Type` | [Cashier transaction type](#cashier-transaction-type) | optional | Type of the cashier transaction. Not set for legacy transactions created before the type was tracked. | #### Cashier transaction type * `CashIn` - Cash received into the cashier. * `CashOut` - Cash paid out of the cashier. * `CashOutTip` - Cash paid out of the cashier as a tip. * `CashOutExpense` - Cash paid out of the cashier as an expense. * `CashOutFloatAdjustment` - Cash paid out of the cashier as a float adjustment. # Commands ## Get all fiscal machine commands > ### Restricted! > > This operation is currently in beta-test and as such it is subject to change. Returns fiscal machine commands. The commands can be filtered either by unique command identifiers or by `Device` unique identifiers and command states. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/fiscalMachineCommands/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "DeviceIds": [ "d117866d-78de-4459-9077-42d7ea0120e3", "7dafffff-a727-4917-a203-bd53995f21bf" ], "States": [ "Processed", "Processing" ], "UpdatedUtc": { "StartUtc": "2025-01-10T00:00:00Z", "EndUtc": "2025-01-17T00:00:00Z" }, "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "Limitation": { "Count": 100 } } ``` This operation accepts one of the following mutually exclusive parameter sets. #### Get all commands by unique identifiers Filter commands by their unique identifiers. | 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. | | `CommandIds` | array of string | required, max 1000 items | Unique identifiers of the commands to filter by. | | `EnterpriseIds` | array,null | required, max 1000 items | Unique identifiers of the Enterprises. If not specified, the operation returns data for all enterprises within scope of the Access Token. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | #### Get all commands by device identifiers and states Filter commands by the unique identifiers of `Device` and states, with optional filtering by update interval. | 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. | | `DeviceIds` | array of string | required, max 100 items | Unique identifiers of `Device` to filter by. | | `States` | array of [Command state](#command-state) | required | States of the commands to filter by. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | required, max length 3 months | Interval in which the commands were updated. | | `EnterpriseIds` | array,null | required, max 1000 items | Unique identifiers of the Enterprises. If not specified, the operation returns data for all enterprises within scope of the Access Token. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "Commands": [ { "Id": "aa20961f-6d9e-4b35-ad25-071213530aec", "State": "Processing", "CreatedUtc": "2025-01-15T14:30:00Z", "Creator": { "Discriminator": "Enterprise", "EnterpriseProfile": { "ProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf" } }, "FiscalMachineId": "FM-001", "ApiUrl": "https://fiscal-machine.example.com/api", "FiscalMachineData": "{\"printerPort\": \"COM1\", \"baudRate\": 9600}", "TaxIdentifier": "12345678901", "Device": { "Id": "d117866d-78de-4459-9077-42d7ea0120e3", "Type": "FiscalMachine", "Name": "Fiscal Printer FP-001", "Identifier": null }, "Bill": { "Id": "ea087d64-3901-4eee-b0b7-9fce4c58a005", "Name": "Hotel Invoice #1001", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "AccountId": "fadd5bb6-b428-45d5-94f8-fd0d89fece6d", "AccountType": "Customer", "AssociatedAccountIds": null, "CounterId": null, "State": "Closed", "Type": "Invoice", "Number": "1001", "VariableSymbol": "VS001", "CreatedUtc": "2025-01-15T10:00:00Z", "UpdatedUtc": "2025-01-15T14:25:00Z", "IssuedUtc": "2025-01-15T14:25:00Z", "TaxedUtc": "2025-01-15T14:25:00Z", "PaidUtc": null, "DueUtc": "2025-01-29T23:59:59Z", "LastReminderDateUtc": null, "PurchaseOrderNumber": "PO-2025-001", "Notes": "Hotel accommodation services", "Options": null, "Owner": null, "AssociatedAccountsData": null, "EnterpriseData": null, "CorrectionState": "Bill", "CorrectionType": null, "CorrectedBillId": null }, "CommandData": { "Discriminator": "ItalianFiscalMachineData", "ItalianFiscalMachineData": { "IsRefund": false, "RebatedReceiptNumber": null, "RebatedReceiptSequence": null, "RebatedReceiptDateTimeUtc": null, "PrinterSerialNumber": "FP001-123456" }, "ItalianFiscalMachinePayload": null } }, { "Id": "f2e8c456-1234-4567-89ab-cdef01234567", "State": "Processed", "CreatedUtc": "2025-01-15T13:15:00Z", "Creator": { "Discriminator": "Enterprise", "EnterpriseProfile": { "ProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf" } }, "FiscalMachineId": "FM-002", "ApiUrl": "https://fiscal-machine-2.example.com/api", "FiscalMachineData": "{\"printerPort\": \"USB001\", \"certificatePath\": \"/etc/fiscal/cert.p12\"}", "TaxIdentifier": "98765432109", "Device": { "Id": "7dafffff-a727-4917-a203-bd53995f21bf", "Type": "FiscalMachine", "Name": "Fiscal Printer FP-002", "Identifier": null }, "Bill": { "Id": "12345678-1234-1234-1234-123456789012", "Name": "Restaurant Bill #2001", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "AccountId": "fadd5bb6-b428-45d5-94f8-fd0d89fece6d", "AccountType": "Customer", "AssociatedAccountIds": null, "CounterId": null, "State": "Closed", "Type": "Receipt", "Number": "2001", "VariableSymbol": "VS002", "CreatedUtc": "2025-01-15T12:30:00Z", "UpdatedUtc": "2025-01-15T13:10:00Z", "IssuedUtc": "2025-01-15T13:10:00Z", "TaxedUtc": "2025-01-15T13:10:00Z", "PaidUtc": "2025-01-15T13:10:00Z", "DueUtc": null, "LastReminderDateUtc": null, "PurchaseOrderNumber": null, "Notes": "Restaurant services - Table 15", "Options": null, "Owner": null, "AssociatedAccountsData": null, "EnterpriseData": null, "CorrectionState": "Bill", "CorrectionType": null, "CorrectedBillId": null }, "CommandData": { "Discriminator": "ItalianFiscalMachinePayload", "ItalianFiscalMachineData": null, "ItalianFiscalMachinePayload": { "Payload": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPGZ2cF9kb2M+CiAgPGhlYWRlcj4KICAgIDx0aW1lc3RhbXA+MjAyNS0wMS0xNVQxMzoxMDowMFo8L3RpbWVzdGFtcD4KICA8L2hlYWRlcj4KICA8Ym9keT4KICAgIDxyZWNlaXB0X2RhdGE+U2FtcGxlIGZpc2NhbCByZWNlaXB0IGRhdGE8L3JlY2VpcHRfZGF0YT4KICA8L2JvZHk+CjwvZnZwX2RvYz4=" } } } ], "Cursor": "f2e8c456-1234-4567-89ab-cdef01234567" } ``` | Property | Type | Contract | Description | | ---------- | ----------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `Commands` | array of [Fiscal machine command data (ver. 2025-06-23)](#fiscal-machine-command-data-ver-2025-06-23) | required | The filtered fiscal machine commands. | | `Cursor` | string | optional | Unique identifier of the last returned command. This can be used in Limitation in a subsequent request to fetch the next batch of commands. | #### Fiscal machine command data (ver. 2025-06-23) | Property | Type | Contract | Description | | ------------------- | --------------------------------------------------------------- | -------- | ---------------------------------------------- | | `Id` | string | required | Unique identifier of the command. | | `State` | [Command state](#command-state) | required | State of the command. | | `CreatedUtc` | string | required | Creation date and time of the command. | | `Creator` | [Profile data](/connector-api/operations/_objects#profile-data) | optional | Creator of the command. | | `FiscalMachineId` | string | required | Identifier of the fiscal machine. | | `ApiUrl` | string | required | URL of the fiscal machine API. | | `FiscalMachineData` | string | required | Custom JSON data. | | `TaxIdentifier` | string | optional | Tax identifier to be used for fiscalization. | | `Device` | [Device](/connector-api/operations/devices#device) | required | Device that the command should be executed on. | | `Bill` | [Bill (ver 2025-06-23)](#bill-ver-2025-06-23) | required | The issued bill that should be fiscalized. | | `CommandData` | [FiscalMachineAdditionalData](#fiscalmachineadditionaldata) | optional | Additional data of the fiscal machine. | #### Command state * `Pending` - Created in Mews, but not yet received by the client application. * `Received` - Received by the client application. * `Processing` - Being processed by the client application. * `Processed` - Successfully processed command. * `Cancelled` - A command whose execution has been canceled before (or during) processing. * `Error` - A command whose execution or processing was terminated by an error. #### Bill (ver 2025-06-23) | Property | Type | Contract | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the bill. | | `Name` | string | optional | Name of the bill. | | `EnterpriseId` | string | required | Unique identifier of the `Enterprise`. | | `AccountId` | string | required | Unique identifier of the account (`Customer` or `Company`) the bill is issued to. | | `AccountType` | [Account type](/connector-api/operations/accounts#account-type) | required | A discriminator specifying the account type, i.e. `Customer` or `Company`. | | `AssociatedAccountIds` | array of string | optional | Unique identifiers of the `Customers` or `Companies` that are associated to the bill. | | `CounterId` | string | optional | Unique identifier of the bill `Counter`. | | `State` | [Bill state](/connector-api/operations/bills#bill-state) | required | Whether the bill is `Open` or `Closed`. | | `Type` | [Bill type](/connector-api/operations/bills#bill-type) | required | After a bill is closed, the Bill Type is set to `Receipt` or `Invoice`. `Receipt` indicates that the bill has been fully paid and the balance is zero. `Invoice` indicates that the bill has not yet been fully paid but an invoice has been issued. Prior to closing, Bill Type should not be used. | | `Number` | string | optional | Number of the bill. | | `VariableSymbol` | string | optional | Variable symbol of the bill. | | `CreatedUtc` | string | required | Date and time of the bill creation in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Date and time when the bill was last updated, in UTC timezone in ISO 8601 format. | | `IssuedUtc` | string | optional | Date and time of the bill issuance in UTC timezone in ISO 8601 format. | | `TaxedUtc` | string | optional | Taxation date of the bill in UTC timezone in ISO 8601 format. | | `PaidUtc` | string | optional | Date when the bill was paid in UTC timezone in ISO 8601 format. | | `DueUtc` | string | optional | Bill due date and time in UTC timezone in ISO 8601 format. | | `LastReminderDateUtc` | string | optional | Date and time when an email reminder to pay an invoice was last sent, in UTC timezone in ISO 8601 format. | | `PurchaseOrderNumber` | string | optional | Unique number of the purchase order from the buyer. | | `Notes` | string | optional | Additional notes. | | `Options` | [Bill options](/connector-api/operations/bills#bill-options) | optional | Options of the bill. | | `Owner` | [Associated account bill data](/connector-api/operations/bills#associated-account-bill-data) | optional | Additional information about owner of the bill. Can be a `Customer` or `Company`. Persisted at the time of closing of the bill. | | `AssociatedAccountsData` | array of [Associated account bill data](/connector-api/operations/bills#associated-account-bill-data) | optional | Additional information about the associated account of the bill. Can be a `Customer` or `Company`. Persisted at the time of closing of the bill. Currently only one account can be associated with a bill, but this may be extended in future. | | `EnterpriseData` | [Bill enterprise data](/connector-api/operations/bills#bill-enterprise-data) | optional | Additional information about the enterprise issuing the bill, including bank account details. Persisted at the time of closing of the bill. | | `CorrectionState` | [Bill correction state](/connector-api/operations/bills#bill-correction-state) | required | Whether the bill is a regular bill or a corrective bill. | | `CorrectionType` | [Bill correction type](/connector-api/operations/bills#bill-correction-type) | optional | Type of correction. | | `CorrectedBillId` | string | optional | The ID of the bill that the corrective bill corrects. If the corrected bill was deleted, this field is `null`. | #### FiscalMachineAdditionalData | Property | Type | Contract | Description | | ----------------------------- | ----------------------------------------------------------------------- | -------- | --------------------------------------------------- | | `Discriminator` | [Fiscal machine data discriminator](#fiscal-machine-data-discriminator) | optional | Type of additional data for Italian fiscal machine. | | `ItalianFiscalMachineData` | [Italian fiscal machine data](#italian-fiscal-machine-data) | optional | Fiscal machine data for Italian fiscal machine. | | `ItalianFiscalMachinePayload` | [Italian fiscal machine payload.](#italian-fiscal-machine-payload) | optional | Fiscal machine payload for Italian fiscal machine. | #### Fiscal machine data discriminator * `ItalianFiscalMachineData` * `ItalianFiscalMachinePayload` #### Italian fiscal machine data | Property | Type | Contract | Description | | --------------------------- | ------- | -------- | -------------------------------------------- | | `IsRefund` | boolean | required | Indicates if the transaction is a refund. | | `RebatedReceiptNumber` | string | optional | Number of the rebated receipt. | | `RebatedReceiptSequence` | string | optional | Sequence of the rebated receipt. | | `RebatedReceiptDateTimeUtc` | string | optional | Date and time of the rebated receipt in UTC. | | `PrinterSerialNumber` | string | optional | Serial number of the printer. | #### Italian fiscal machine payload. | Property | Type | Contract | Description | | --------- | ------ | -------- | ---------------------------------------------- | | `Payload` | string | required | Base64-encoded data of the file to be printed. | ## Get all commands by ids Returns all commands by their identifiers. ### Request `[PlatformAddress]/api/connector/v1/commands/getAllByIds` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CommandIds": [ "aa20961f-6d9e-4b35-ad25-071213530aec" ] } ``` | 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. | | `CommandIds` | array of string | required, max 1000 items | Unique identifiers of [Commands](#command) to be returned. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | optional | Limitation on the quantity of data returned. | ### Response ```javascript { "Commands": [ { "Id": "aa20961f-6d9e-4b35-ad25-071213530aec", "State": "Pending", "CreatedUtc": "2015-09-02T19:25:44Z", "Creator": { "FirstName": "Sample", "LastName": "User", "ImageUrl": "..." }, "Device": { "Id": "63efb573-fc58-4065-b687-9bdd51568529", "Name": "Test Printer", "Type": "Printer" }, "Data": { "CopyCount": 1, "FileType": "application/pdf", "FileData": "...", "PrinterName": "Printer", "PrinterDriverName": "", "PrinterPortName": "" } } ] } ``` | Property | Type | Contract | Description | | ---------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `Commands` | array of [Command](#command) | required | The active commands. | | `Cursor` | string | optional | Unique identifier of the last returned command. This can be used in Limitation in a subsequent request to fetch the next batch of commands. | #### Command | Property | Type | Contract | Description | | ------------ | -------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | | `Id` | string | required | Unique identifier of the command. | | `State` | [Command state](#command-state) | required | State of the command. | | `CreatedUtc` | string | required | Creation date and time of the command. | | `Creator` | [User](#user) | optional | Creator of the command. | | `Device` | [Device](/connector-api/operations/devices#device) | required | Device that the command should be executed on. | | `Data` | object | required | Structure of the object depends on [Device type](/connector-api/operations/devices#device-type). | #### User | Property | Type | Contract | Description | | ----------- | ------ | -------- | ------------------------- | | `FirstName` | string | optional | First name of the user. | | `LastName` | string | required | Last name of the user. | | `ImageUrl` | string | optional | URL of the profile image. | #### Payment terminal command data | Property | Type | Contract | Description | | --------------------- | --------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------- | | `PaymentTerminalId` | string | required | Identifier of the payment terminal. | | `AccountId` | string | required | Unique identifier of the account. | | `BillId` | string | optional | Identifier of the bill. | | `PaymentId` | string | optional | Identifier of the `Payment`. | | `PreauthorizationId` | string | optional | Identifier of the `Preauthorization`. | | `Amount` | [Extended amount](/connector-api/operations/_objects#amount) | required | Amount to be processed. | | `Fee` | [Extended amount](/connector-api/operations/_objects#amount) | optional | Payment fee to be processed. | | `PaymentTerminalData` | string | optional | Custom JSON data. | | `AccountData` | [Account data for payment terminal command](#account-data-for-payment-terminal-command) | required | Account data for the payment terminal command. | | ~~`CustomerId`~~ | ~~string~~ | ~~required~~ | **Deprecated!** Use `AccountId` instead. | | ~~`FullName`~~ | ~~string~~ | ~~optional~~ | **Deprecated!** Use `AccountData.Customer.FullName`, if `AccountData.Discriminator` is `Customer`. | #### Account data for payment terminal command | Property | Type | Contract | Description | | --------------- | ------------------------------------------------------------------------------------------ | -------- | --------------------------------------------------- | | `Discriminator` | [Account type](/connector-api/operations/accounts#account-type) | required | Type of the account. | | `Customer` | [Customer data for payment terminal command.](#customer-data-for-payment-terminal-command) | optional | Customer data if the `Discriminator` is `Customer`. | | `Company` | [Company data for payment terminal command.](#company-data-for-payment-terminal-command) | optional | Company data if the `Discriminator` is `Company`. | #### Customer data for payment terminal command. | Property | Type | Contract | Description | | ---------- | ------ | -------- | -------------------------- | | `FullName` | string | required | Full name of the customer. | #### Company data for payment terminal command. | Property | Type | Contract | Description | | -------- | ------ | -------- | -------------------- | | `Name` | string | required | Name of the company. | #### Printer command data | Property | Type | Contract | Description | | ------------------- | ------- | -------- | ------------------------------------------------------------- | | `CopyCount` | integer | required | Number of copies to be printed. | | `FileType` | string | required | MIME type of the file to be printed (e.g. `application/pdf`). | | `FileData` | string | required | Base64-encoded data of the file to be printed. | | `PrinterName` | string | required | Name of the printer. | | `PrinterDriverName` | string | required | Name of the printer driver. | | `PrinterPortName` | string | required | Name of the printer port. | #### Key cutter command data | Property | Type | Contract | Description | | --------------------- | --------------- | -------- | ----------------------------------------------------------------- | | `KeyCutterId` | string | optional | Identifier of the key cutter. | | `ApiUrl` | string | optional | URL of the key cutter server API. | | `KeyCutterData` | string | optional | Custom JSON data. | | `KeyCount` | integer | required | Count of keys to cut. | | `LockIds` | array of string | required | Identifiers of locks/rooms the key should open. | | `StartUtc` | string | required | Reservation start. | | `EndUtc` | string | required | Reservation end. | | `FirstName` | string | optional | First name of the reservation owner. | | `LastName` | string | required | Last name of the reservation owner. | | `NormalizedFirstName` | string | optional | Normalized first name of the customer without special characters. | | `NormalizedLastName` | string | optional | Normalized last name of the customer without special characters. | | `Telephone` | string | optional | Telephone of the reservation owner. | | `Email` | string | optional | Email of the reservation owner. | | `ReservationId` | string | optional | Unique identifier of the reservation. | | `ReservationNumber` | string | optional | Confirmation number of the reservation in Mews. | #### Fiscal machine command data | Property | Type | Contract | Description | | ----------------------- | ------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | | `FiscalMachineId` | string | optional | Identifier of the fiscal machine. | | `ApiUrl` | string | optional | URL of the fiscal machine API. | | `FiscalMachineData` | string | optional | Custom JSON data. | | `Bill` | [Bill](/connector-api/operations/bills#bill) | required | The issued bill that should be fiscalized. | | `TaxIdentifier` | string | optional | Tax identifier to be used for fiscalization. | | `BillFiscalMachineData` | [Fiscal machine data](#fiscal-machine-data) | optional | Fiscal machine data; currently only `ItalianFiscalMachineData` is supported. | | `PayloadData` | [Fiscal machine payload](#fiscal-machine-payload) | optional | Fiscal machine payload data; currently only `ItalianFiscalMachinePayloadData` is supported. | #### Fiscal machine data | Property | Type | Contract | Description | | --------------- | ------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | | `Discriminator` | [Fiscal machine data discriminator](#fiscal-machine-data-discriminator) | required | Discriminator of the object. | | `Value` | [Fiscal machine data for Italian fiscal machine](#fiscal-machine-data-for-italian-fiscal-machine) | required | Structure of the object depends on `Discriminator` (currently only `ItalianFiscalMachineData` is supported). | #### Fiscal machine data discriminator * `ItalianFiscalMachineData` #### Fiscal machine data for Italian fiscal machine | Property | Type | Contract | Description | | --------------------------- | ------- | -------- | -------------------------------------------- | | `IsRefund` | boolean | required | Indicates if the transaction is a refund. | | `RebatedReceiptNumber` | string | optional | Number of the rebated receipt. | | `RebatedReceiptSequence` | string | optional | Sequence of the rebated receipt. | | `RebatedReceiptDateTimeUtc` | string | optional | Date and time of the rebated receipt in UTC. | | `PrinterSerialNumber` | string | optional | Serial number of the printer. | #### Fiscal machine payload | Property | Type | Contract | Description | | --------------- | ----------------------------------------------------------------------------- | -------- | ---------------------------------------------- | | `Discriminator` | [Fiscal machine payload discriminator](#fiscal-machine-payload-discriminator) | required | Discriminator of the object. | | `Value` | string | required | Base64-encoded data of the file to be printed. | #### Fiscal machine payload discriminator * `ItalianFiscalMachine` #### Passport scanner command data | Property | Type | Contract | Description | | ------------------- | ------ | -------- | -------------------------------------------------------------------------- | | `PassportScannerId` | string | optional | Identifier of the passport scanner. | | `CustomerId` | string | optional | Unique identifier of the `Customer` who should be processed. | | `ReservationId` | string | optional | Unique identifier of the reservation whose companions should be processed. | ## Get all commands Returns all commands the are still active from the client application point of view. That means commands that are in either `Pending` or `Received` state. ### Request `[PlatformAddress]/api/connector/v1/commands/getAllActive` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0" } ``` | 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. | ### Response ```javascript { "Commands": [ { "Id": "aa20961f-6d9e-4b35-ad25-071213530aec", "State": "Pending", "CreatedUtc": "2015-09-02T19:25:44Z", "Creator": { "FirstName": "Sample", "LastName": "User", "ImageUrl": "..." }, "Device": { "Id": "63efb573-fc58-4065-b687-9bdd51568529", "Name": "Test Printer", "Type": "Printer" }, "Data": { "CopyCount": 1, "FileType": "application/pdf", "FileData": "...", "PrinterName": "Printer", "PrinterDriverName": "", "PrinterPortName": "" } } ] } ``` | Property | Type | Contract | Description | | ---------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `Commands` | array of [Command](#command) | required | The active commands. | | `Cursor` | string | optional | Unique identifier of the last returned command. This can be used in Limitation in a subsequent request to fetch the next batch of commands. | ## Add printer command Adds a new printer command representing printing of the specified document on a printer. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/commands/addPrinter` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "PrinterId": "d117866d-78de-4459-9077-42d7ea0120e3", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "CopyCount": 1, "Data": "JVBERi0xLjcKCjEgMCBvYmogICUgZW50cnkgcG9pbnQKPDwKICAvVHlwZSAvQ2F0YWxvZwogIC9QYWdlcyAyIDAgUgo+PgplbmRvYmoKCjIgMCBvYmoKPDwKICAvVHlwZSAvUGFnZXMKICAvTWVkaWFCb3ggWyAwIDAgMjAwIDIwMCBdCiAgL0NvdW50IDEKICAvS2lkcyBbIDMgMCBSIF0KPj4KZW5kb2JqCgozIDAgb2JqCjw8CiAgL1R5cGUgL1BhZ2UKICAvUGFyZW50IDIgMCBSCiAgL1Jlc291cmNlcyA8PAogICAgL0ZvbnQgPDwKICAgICAgL0YxIDQgMCBSIAogICAgPj4KICA+PgogIC9Db250ZW50cyA1IDAgUgo+PgplbmRvYmoKCjQgMCBvYmoKPDwKICAvVHlwZSAvRm9udAogIC9TdWJ0eXBlIC9UeXBlMQogIC9CYXNlRm9udCAvVGltZXMtUm9tYW4KPj4KZW5kb2JqCgo1IDAgb2JqICAlIHBhZ2UgY29udGVudAo8PAogIC9MZW5ndGggNDQKPj4Kc3RyZWFtCkJUCjcwIDUwIFRECi9GMSAxMiBUZgooSGVsbG8sIHdvcmxkISkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iagoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDEwIDAwMDAwIG4gCjAwMDAwMDAwNzkgMDAwMDAgbiAKMDAwMDAwMDE3MyAwMDAwMCBuIAowMDAwMDAwMzAxIDAwMDAwIG4gCjAwMDAwMDAzODAgMDAwMDAgbiAKdHJhaWxlcgo8PAogIC9TaXplIDYKICAvUm9vdCAxIDAgUgo+PgpzdGFydHhyZWYKNDkyCiUlRU9G" } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `PrinterId` | string | required | Unique identifier of the `Printer` `Device` where to print the document. | | `Data` | string | required | Base64 encoded data of PDF document to print. | | `CopyCount` | integer | required | Count of copies to be printed. | ### Response ```javascript { "CommandId": "2391a3df-1c61-4131-b6f8-c85b4234adcb" } ``` | Property | Type | Contract | Description | | ----------- | ------ | -------- | ------------------------------------------- | | `CommandId` | string | required | Unique identifier of the created `Command`. | ## Add payment command > ### Restricted! > > This operation is part of a custom workflow for Mews partners such as POS systems to access Mews Payment Terminals. See [Mews Payment Terminals](/connector-api/use-cases/mews-terminals). Adds a new Mews Payment Terminal command for taking a customer payment. The operation instructs a specified terminal device to take a payment from a specified customer for a specified amount. ### Request `[PlatformAddress]/api/connector/v1/commands/addPaymentTerminal` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "7059D2C25BF64EA681ACAB3A00B859CC-D91BFF2B1E3047A3E0DEC1D57BE1382", "Client": "MyPOS 1.0", "Type": "Payment", "TerminalId": "be35b39e-ad7e-460a-8de9-4c7581e016a2", "CustomerId": "35d4b117-4e60-44a3-9580-c582117eff98", "BillId": null, "Amount": { "Currency": "EUR", "Value": 230 } } ``` | 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. | | `TerminalId` | string | required | Unique identifier of the payment terminal. | | `CustomerId` | string | required | Unique identifier of the `Customer`. | | `Type` | [Payment type](#payment-type) | required | The type of payment, e.g. `Preauthorization`. | | `Amount` | [Currency value (ver 2018-06-07)](/connector-api/operations/_objects#currency-value-ver-2018-06-07) | required | Amount of the payment. | | `BillId` | string | optional | Unique identifier of the `Bill`. | | `PaymentRequestId` | string | optional | Unique identifier of the `PaymentRequest`. | | `ReservationId` | string | optional | Unique identifier of the `Reservation`. | #### Payment type * `Payment` * `Preauthorization` ### Response ```javascript { "CommandId": "2391a3df-1c61-4131-b6f8-c85b4234adcb" } ``` | Property | Type | Contract | Description | | ----------- | ------ | -------- | ------------------------------------------- | | `CommandId` | string | required | Unique identifier of the created `Command`. | ## Add key cutter command Adds a new key cutter command representing cutting of a key for the specified reservation. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/commands/addKeyCutter` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "KeyCutterId": "7dafffff-a727-4917-a203-bd53995f21bf", "ReservationId": "be35b39e-ad7e-460a-8de9-4c7581e016a2", "KeyCount": 1 } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `KeyCutterId` | string | required | Unique identifier of the KeyCutter [Device](/connector-api/operations/devices#device) where to encode the key. | | `ReservationId` | string | required | Unique identifier of the reservation to encode the key for. | | `KeyCount` | integer | required | Count of keys to encode. | ### Response ```javascript { "CommandId": "2391a3df-1c61-4131-b6f8-c85b4234adcb" } ``` | Property | Type | Contract | Description | | ----------- | ------ | -------- | ------------------------------------------- | | `CommandId` | string | required | Unique identifier of the created `Command`. | ## Update command Updates state of a command. ### Request `[PlatformAddress]/api/connector/v1/commands/update` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CommandId": "aa20961f-6d9e-4b35-ad25-071213530aec", "State": "Processed" } ``` | 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. | | `CommandId` | string | required | Identifier of the `Command` to be updated. | | `State` | [Command state](#command-state) | required | New state of the command. | | `Progress` | number | optional | Progress of the command processing. Only used if the `State` is `Processing`, otherwise ignored. | | `Notes` | string | optional | Notes about command execution. Only used if the `State` is `Processed`, `Cancelled` or `Error`, otherwise ignored. | ### Response ```javascript {} ``` # Companies ## Get all companies Returns all company profiles of the enterprise, possibly filtered by identifiers, names or other filters. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/companies/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ChainIds": [ "1df21f06-0cfc-4960-9c58-a3bf1261663e", "5fcd1933-22f2-40b9-84da-7db04cbecec2" ], "Ids": [ "3ed9e2f3-4bba-4df6-8d41-ab1b009b6425", "8a98965a-7c03-48a1-a28c-ab1b009b53c8" ], "Names": [ "AC Company" ], "CreatedUtc": { "StartUtc": "2019-12-05T00:00:00Z", "EndUtc": "2019-12-10T00:00:00Z" }, "UpdatedUtc": { "StartUtc": "2019-12-10T00:00:00Z", "EndUtc": "2019-12-17T00:00:00Z" }, "ExternalIdentifiers": [ "12345", "4312343" ], "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. | | `ChainIds` | array of string | optional, max 1000 items | Unique identifiers of `Chain`. If not specified, the operation returns data for all chains within scope of the Access Token. | | `MotherCompanyIds` | array of string | optional, max 1000 items | Unique identifiers of mother `Company`. | | `CreatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the companies were created. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the companies were updated. | | `Ids` | array of string | optional, max 1000 items | Unique identifiers of [Companies](#company). | | `ExternalIdentifiers` | array of string | optional, max 1000 items | Identifiers of [Company](#company) from external system. | | `Names` | array of string | optional, max 1000 items | Names of [Companies](#company). | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted, or both types of record. If not specified, both active and deleted records will be returned. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | | ~~`TimeFilter`~~ | [~~Company Time Filter~~](#company-time-filter) | ~~optional~~ | **Deprecated!** Use CreatedUtc or UpdatedUtc instead. | | ~~`StartUtc`~~ | ~~string~~ | ~~optional~~ | **Deprecated!** Use CreatedUtc or UpdatedUtc instead. | | ~~`EndUtc`~~ | ~~string~~ | ~~optional~~ | **Deprecated!** Use CreatedUtc or UpdatedUtc instead. | #### Company Time Filter * `Created` * `Updated` ### Response ```javascript { "Companies": [ { "Id": "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "ChainId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "Name": "Sample Company 1", "IsActive": true, "Number": 11, "Identifier": null, "TaxIdentifier": null, "AdditionalTaxIdentifier": null, "ElectronicInvoiceIdentifier": null, "InvoiceDueInterval": "P2DT23H", "AccountingCode": null, "MotherCompanyId": null, "CreatedUtc": "2022-07-11T09:56:54Z", "UpdatedUtc": "2022-07-11T09:56:54Z", "AddressId": "bab7441c-4b82-43bc-8001-ab0400a346ec", "BillingCode": null, "Iata": "PAO", "Telephone": "111-222-333", "InvoicingEmail": "sample1@mews.com", "ContacPerson": "Sample Person 1", "Contact": "Contact Info 1", "Notes": "Note 1", "Options": { "Invoiceable": true, "AddFeesToInvoices": true }, "Department": "Sales", "DunsNumber": "123456789", "CreditRating": { "Basic": "PaymentRequiredUpfront" }, "ReferenceIdentifier": "da34b396-77e3-495a-bd61-aecf00a3f19d", "WebsiteUrl": "https://www.mewssystems.com", "ExternalIdentifier": "company0001" }, { "Id": "da34b396-41f7-47f6-8847-aecf00a3f19e", "ChainId": "5fcd1933-22f2-40b9-84da-7db04cbecec2", "Name": "Sample Company 2", "IsActive": true, "Number": 12, "Identifier": null, "TaxIdentifier": null, "AdditionalTaxIdentifier": null, "ElectronicInvoiceIdentifier": null, "InvoiceDueInterval": "P2DT23H", "AccountingCode": null, "MotherCompanyId": null, "CreatedUtc": "2022-07-11T09:56:54Z", "UpdatedUtc": "2022-07-11T09:56:54Z", "AddressId": null, "BillingCode": null, "Iata": "PAO", "Telephone": "111-222-333", "InvoicingEmail": "sample2@mews.com", "ContacPerson": "Sample Person 2", "Contact": "Contact Info 2", "Notes": "Note 2", "Options": { "Invoiceable": true, "AddFeesToInvoices": false }, "Department": "Accounting", "DunsNumber": "987654321", "CreditRating": { "Basic": "CreditOk" }, "ReferenceIdentifier": "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "WebsiteUrl": "https://www.mews.com", "ExternalIdentifier": "company0002" } ], "Cursor": "da34b396-41f7-47f6-8847-aecf00a3f19e" } ``` | Property | Type | Contract | Description | | ----------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Companies` | array of [Company](#company) | required | The company profiles of the enterprise. | | `Cursor` | string | optional | Unique identifier of the last and hence oldest company item returned. This can be used in [Limitation](/connector-api/guidelines/pagination#limitation) in a subsequent request to fetch the next batch of older companies. If [Limitation](/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. | ## Add company Adds a new company. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/companies/add` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ChainId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "Name": "Mews", "Options": { "Invoiceable": true, "AddFeesToInvoices": true }, "MotherCompanyId": null, "Identifier": null, "TaxIdentifier": null, "AdditionalTaxIdentifier": null, "BillingCode": null, "AccountingCode": null, "Address": null, "InvoiceDueInterval": "P2DT23H", "Telephone": "111-222-333", "ContacPerson": "SamplePerson", "Contact": "ContactInfo", "Notes": "Note1", "Iata": "PAO", "Department": "Sales", "DunsNumber": "987654321", "CreditRating": { "Basic": "CreditOk" }, "ExternalIdentifier": "1234", "ReferenceIdentifier": "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "WebsiteUrl": "https://www.mews.com" } ``` | 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `Name` | string | required | Name of the company. | | `MotherCompanyId` | string | optional | Unique identifier of the mother company. | | `InvoicingEmail` | string | optional | Email for issuing invoices to the company. | | `WebsiteUrl` | string | optional | The website url of the company. | | `InvoiceDueInterval` | string | optional | The maximum time, when the invoice has to be be paid in ISO 8601 duration format. | | `Options` | [Company Options Parameters](#company-options-parameters) | required | Options of the company. | | `CreditRating` | [Credit rating parameters](#credit-rating-parameters) | optional | Credit rating to define creditworthiness of the company. | | `Department` | string | optional | The internal segmentation of a company, e.g. sales department. | | `DunsNumber` | string | optional | The Dun & Bradstreet unique 9-digit DUNS number. | | `ReferenceIdentifier` | string | optional | External system identifier - custom identifier used by an external system such as an external database. | | `AccountingCode` | string | optional | Accounting code of the company. | | `AdditionalTaxIdentifier` | string | optional | Additional tax identifer of the company. | | `BillingCode` | string | optional | Billing code of the company. | | `Contact` | string | optional | Other contact details, such as telephone, email or similar. | | `ContactPerson` | string | optional | Contact person of the company. | | `Identifier` | string | optional | Fiscal or legal identifier of the company. | | `Iata` | string | optional | Iata of the company. | | `Notes` | string | optional | Notes of the company. | | `TaxIdentifier` | string | optional | Tax identification number of the company. | | `Telephone` | string | optional | Contact telephone number. | | `Address` | [Address parameters](#address-parameters) | optional | New address details. | | `ExternalIdentifier` | string | optional, max length 255 characters | Identifier of the company from external system. | #### Company Options Parameters Options of the company. | Property | Type | Contract | Description | | --------------------------------- | ------- | -------- | ------------------------------------------------------------------------ | | `Invoiceable` | boolean | required | Whether the company is invoiceable or not. | | `AddFeesToInvoices` | boolean | required | Whether the company has an additional fee applied for invoicing or not. | | `AddTaxDeductedPaymentToInvoices` | boolean | required | Whether tax-deducted payments should be automatically added to invoices. | #### Credit rating parameters Credit rating to define creditworthiness of the company. | Property | Type | Contract | Description | | -------- | ------------------------------------------- | -------- | ----------------------------------------- | | `Basic` | [Credit rating basic](#credit-rating-basic) | optional | Indicates the credit status of a company. | #### Address parameters New address details. | Property | Type | Contract | Description | | ------------------------ | ------ | -------- | ---------------------------------------------------------- | | `Line1` | string | optional | First line of the address. | | `Line2` | string | optional | Second line of the address. | | `City` | string | optional | The city. | | `PostalCode` | string | optional | Postal code. | | `CountryCode` | string | optional | ISO 3166-1 code of the Country. | | `CountrySubdivisionCode` | string | optional | ISO 3166-2 code of the administrative division, e.g. DE-BW | ### Response ```javascript { "Companies": [ { "Id": "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "ChainId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "Name": "Sample Company 1", "IsActive": true, "Number": 11, "Identifier": null, "TaxIdentifier": null, "AdditionalTaxIdentifier": null, "ElectronicInvoiceIdentifier": null, "InvoiceDueInterval": "P2DT23H", "AccountingCode": null, "MotherCompanyId": null, "CreatedUtc": "2022-07-11T09:56:54Z", "UpdatedUtc": "2022-07-11T09:56:54Z", "AddressId": "bab7441c-4b82-43bc-8001-ab0400a346ec", "BillingCode": null, "Iata": "PAO", "Telephone": "111-222-333", "InvoicingEmail": "sample1@mews.com", "ContacPerson": "Sample Person 1", "Contact": "Contact Info 1", "Notes": "Note 1", "Options": { "Invoiceable": true, "AddFeesToInvoices": true }, "Department": "Sales", "DunsNumber": "123456789", "CreditRating": { "Basic": "PaymentRequiredUpfront" }, "ReferenceIdentifier": "da34b396-77e3-495a-bd61-aecf00a3f19d", "WebsiteUrl": "https://www.mewssystems.com", "ExternalIdentifier": "company0001" }, { "Id": "da34b396-41f7-47f6-8847-aecf00a3f19e", "ChainId": "5fcd1933-22f2-40b9-84da-7db04cbecec2", "Name": "Sample Company 2", "IsActive": true, "Number": 12, "Identifier": null, "TaxIdentifier": null, "AdditionalTaxIdentifier": null, "ElectronicInvoiceIdentifier": null, "InvoiceDueInterval": "P2DT23H", "AccountingCode": null, "MotherCompanyId": null, "CreatedUtc": "2022-07-11T09:56:54Z", "UpdatedUtc": "2022-07-11T09:56:54Z", "AddressId": null, "BillingCode": null, "Iata": "PAO", "Telephone": "111-222-333", "InvoicingEmail": "sample2@mews.com", "ContacPerson": "Sample Person 2", "Contact": "Contact Info 2", "Notes": "Note 2", "Options": { "Invoiceable": true, "AddFeesToInvoices": false }, "Department": "Accounting", "DunsNumber": "987654321", "CreditRating": { "Basic": "CreditOk" }, "ReferenceIdentifier": "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "WebsiteUrl": "https://www.mews.com", "ExternalIdentifier": "company0002" } ], "Cursor": "da34b396-41f7-47f6-8847-aecf00a3f19e" } ``` | Property | Type | Contract | Description | | ----------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Companies` | array of [Company](#company) | required | The company profiles of the enterprise. | | `Cursor` | string | optional | Unique identifier of the last and hence oldest company item returned. This can be used in [Limitation](/connector-api/guidelines/pagination#limitation) in a subsequent request to fetch the next batch of older companies. If [Limitation](/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. | #### Company | Property | Type | Contract | Description | | --------------------------------- | -------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the company. | | `ChainId` | string | required | Unique identifier of the chain. | | `Name` | string | required | Name of the company. | | `MotherCompanyId` | string | optional | Unique identifier of mother company. | | `InvoicingEmail` | string | optional | Email for issuing invoices to the company. | | `WebsiteUrl` | string | optional | The website url of the company. | | `InvoiceDueInterval` | string | optional | The maximum time, when the invoice has to be be paid in ISO 8601 duration format. | | `Options` | [Company Options](#company-options) | required | Options of the company. | | `CreditRating` | [Credit Rating](#credit-rating) | required | Credit rating to define creditworthiness of the company. | | `Department` | string | optional | The internal segmentation of a company, e.g. sales department. | | `DunsNumber` | string | optional | The Dun & Bradstreet unique 9-digit DUNS number. | | `ReferenceIdentifier` | string | optional | External system identifier - custom identifier used by an external system such as an external database. | | `AccountingCode` | string | optional | Accounting code of the company. | | `AdditionalTaxIdentifier` | string | optional | Additional tax identifier of the company. | | `BillingCode` | string | optional | Billing code of the company. | | `Contact` | string | optional | Other contact details, such as telephone, email or similar. | | `ContactPerson` | string | optional | Contact person of the company. | | `Identifier` | string | optional | Fiscal or legal identifier of the company. | | `Iata` | string | optional | Iata of the company. | | `IsActive` | boolean | required | Whether the company is still active. | | `Notes` | string | optional | Additional notes. | | `Number` | integer | required | Unique number of the company (max 19 digits). | | `TaxIdentifier` | string | optional | Tax identification number of the company. | | `Telephone` | string | optional | Contact telephone number. | | `CreatedUtc` | string | optional | Date of [Company](#company) creation date and time. | | `UpdatedUtc` | string | optional | Date of [Company](#company) last update date and time. | | `AddressId` | string | optional | Unique identifier of the company [Address](/connector-api/operations/addresses#account-address). | | `MergeTargetId` | string | optional | Unique identifier of the account (Customer) to which this company is linked. | | `ExternalIdentifier` | string | optional, max length 255 characters | Identifier of company from external system. | | ~~`ElectronicInvoiceIdentifier`~~ | ~~string~~ | ~~optional~~ | ~~Electronic invoice identifier of the company.~~ **Deprecated!** Use `AdditionalTaxIdentifier` instead. | | ~~`Address`~~ | [~~Address~~](/connector-api/operations/configuration#address) | ~~optional~~ | **Deprecated!** Use AddressId instead. | | ~~`TaxIdentificationNumber`~~ | ~~string~~ | ~~optional~~ | **Deprecated!** Use TaxIdentifier instead. | #### Company Options Options of the company. | Property | Type | Contract | Description | | --------------------------------- | ------- | -------- | ------------------------------------------------------------------------ | | `Invoiceable` | boolean | required | Whether the company is invoiceable or not. | | `AddFeesToInvoices` | boolean | required | Whether the company has an additional fee applied for invoicing or not. | | `AddTaxDeductedPaymentToInvoices` | boolean | required | Whether tax-deducted payments should be automatically added to invoices. | #### Credit Rating Credit rating to define creditworthiness of the company. | Property | Type | Contract | Description | | -------- | ------------------------------------------- | -------- | ----------------------------------------- | | `Basic` | [Credit rating basic](#credit-rating-basic) | optional | Indicates the credit status of a company. | #### Credit rating basic * `CreditOk` - Company can book services. * `PaymentRequiredUpfront` - Company must pay upfront. * `LocalDecisionRequired` - Requires local approval. ## Update company Updates information of the company. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/companies/update` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ChainId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "CompanyId": "7a1e4d67-d6a2-4a4c-a464-ab1100bea786", "Name": { "Value": "Sample company name" }, "Options": { "Invoiceable": { "Value": true }, "AddFeesToInvoices": { "Value": false } }, "MotherCompanyId": { "Value": "ff649bce-0c4b-4395-9cdd-02039acb7cb3" }, "Identifier": null, "TaxIdentifier": null, "AdditionalTaxIdentifier": null, "BillingCode": null, "AccountingCode": null, "InvoiceDueInterval": { "Value": "P2DT23H" }, "ContactPerson": { "Value": "John Snow" }, "Contact": { "Value": "John Snow" }, "Notes": { "Value": "Notes" }, "Iata": { "Value": "PAO" }, "Department": { "Value": "Marketing" }, "DunsNumber": { "Value": "123456789" }, "CreditRating": { "Basic": { "Value": "PaymentRequiredUpfront" } }, "ExternalIdentifier": { "Value": "4321" }, "ReferenceIdentifier": { "Value": "ff64395-9cdd-4395-9cdd-02039acb7cb3" }, "WebsiteUrl": { "Value": "https://www.mews.com" } } ``` | 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `CompanyId` | string | required | Unique identifier of the [Company](#company). | | `Name` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Name of the company (or `null` if the name should not be updated). | | `MotherCompanyId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique identifier of the mother company (or `null` if the mother company should not be updated). | | `InvoicingEmail` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Email for issuing invoices to the company (or `null` if the email for issuing invoices should not be updated). | | `WebsiteUrl` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | The website url of the company (or `null` if the website url should not be updated). | | `InvoiceDueInterval` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | The maximum time, when the invoice has to be be paid in ISO 8601 duration format (or `null` if the interval should not be updated). | | `Options` | [Company update options](#company-update-options) | optional | Options of the company (or `null` if the company options should not be updated). | | `CreditRating` | [Credit rating update parameters](#credit-rating-update-parameters) | optional | Credit rating to define creditworthiness of the company (or `null` if the credit rating should not be updated). | | `Department` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | The internal segmentation of a company, e.g. sales department (or `null` if the department should not be updated). | | `DunsNumber` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | The Dun & Bradstreet unique 9-digit DUNS number (or `null` if the Duns number should not be updated). | | `ReferenceIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | External system identifier - custom identifier used by an external system such as an external database (or `null` if the identifier should not be updated). | | `AccountingCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Accounting code of the company (or `null` if the accounting code should not be updated). | | `AdditionalTaxIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Additional tax identifier of the company (or `null` if the additional tax identifier should not be updated). | | `BillingCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Billing code of the company (or `null` if the billing code should not be updated). | | `Contact` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Other contact details, such as telephone, email or similar (or `null` if the contact should not be updated). | | `ContactPerson` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Contact person of the company (or `null` if the contact person should not be updated). | | `Identifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Fiscal or legal identifier of the company (or `null` if the identifier should not be updated). | | `Iata` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Iata of the company (or `null` if the Iata should not be updated). | | `Notes` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Notes of the company (or `null` if the notes should not be updated). | | `TaxIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Tax identification number of the company (or `null` if the tax identifier should not be updated). | | `Telephone` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Contact telephone number (or `null` if the telephone number should not be updated). | | `ExternalIdentifier` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 255 characters | Identifier of the company from external system (or `null` if the External Identifier should not be updated). | #### Company update options Options of the company. | Property | Type | Contract | Description | | --------------------------------- | ------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Invoiceable` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Whether the company is invoiceable or not (or `null` if the `Invoiceable` field should not be updated). | | `AddFeesToInvoices` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Whether the company has an additional fee applied for invoicing or not (or `null` if the `AddFeesToInvoices` field should not be updated). | | `AddTaxDeductedPaymentToInvoices` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Whether tax-deducted payments should be automatically added to invoices (or `null` if the `AddTaxDeductedPaymentToInvoices` field should not be updated). | #### Credit rating update parameters Credit rating to define creditworthiness of the company. | Property | Type | Contract | Description | | -------- | ------------------------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------- | | `Basic` | [Credit rating basic update value](/connector-api/operations/_objects#string-update-value) | optional | Credit status of a company (or `null` if the credit status should not be updated). | ### Response ```javascript { "Companies": [ { "Id": "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "ChainId": "1df21f06-0cfc-4960-9c58-a3bf1261663e", "Name": "Sample Company 1", "IsActive": true, "Number": 11, "Identifier": null, "TaxIdentifier": null, "AdditionalTaxIdentifier": null, "ElectronicInvoiceIdentifier": null, "InvoiceDueInterval": "P2DT23H", "AccountingCode": null, "MotherCompanyId": null, "CreatedUtc": "2022-07-11T09:56:54Z", "UpdatedUtc": "2022-07-11T09:56:54Z", "AddressId": "bab7441c-4b82-43bc-8001-ab0400a346ec", "BillingCode": null, "Iata": "PAO", "Telephone": "111-222-333", "InvoicingEmail": "sample1@mews.com", "ContacPerson": "Sample Person 1", "Contact": "Contact Info 1", "Notes": "Note 1", "Options": { "Invoiceable": true, "AddFeesToInvoices": true }, "Department": "Sales", "DunsNumber": "123456789", "CreditRating": { "Basic": "PaymentRequiredUpfront" }, "ReferenceIdentifier": "da34b396-77e3-495a-bd61-aecf00a3f19d", "WebsiteUrl": "https://www.mewssystems.com", "ExternalIdentifier": "company0001" }, { "Id": "da34b396-41f7-47f6-8847-aecf00a3f19e", "ChainId": "5fcd1933-22f2-40b9-84da-7db04cbecec2", "Name": "Sample Company 2", "IsActive": true, "Number": 12, "Identifier": null, "TaxIdentifier": null, "AdditionalTaxIdentifier": null, "ElectronicInvoiceIdentifier": null, "InvoiceDueInterval": "P2DT23H", "AccountingCode": null, "MotherCompanyId": null, "CreatedUtc": "2022-07-11T09:56:54Z", "UpdatedUtc": "2022-07-11T09:56:54Z", "AddressId": null, "BillingCode": null, "Iata": "PAO", "Telephone": "111-222-333", "InvoicingEmail": "sample2@mews.com", "ContacPerson": "Sample Person 2", "Contact": "Contact Info 2", "Notes": "Note 2", "Options": { "Invoiceable": true, "AddFeesToInvoices": false }, "Department": "Accounting", "DunsNumber": "987654321", "CreditRating": { "Basic": "CreditOk" }, "ReferenceIdentifier": "a58ff7cb-77e3-495a-bd61-aecf00a3f19d", "WebsiteUrl": "https://www.mews.com", "ExternalIdentifier": "company0002" } ], "Cursor": "da34b396-41f7-47f6-8847-aecf00a3f19e" } ``` | Property | Type | Contract | Description | | ----------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Companies` | array of [Company](#company) | required | The company profiles of the enterprise. | | `Cursor` | string | optional | Unique identifier of the last and hence oldest company item returned. This can be used in [Limitation](/connector-api/guidelines/pagination#limitation) in a subsequent request to fetch the next batch of older companies. If [Limitation](/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. | ## Delete companies Deletes specified companies. ### Request `[PlatformAddress]/api/connector/v1/companies/delete` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CompanyIds": [ "eb02cbff-353d-48ec-97da-7def2305a5c5", "63551515-1740-49b3-914e-309a8b1429f0" ] } ``` | 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `CompanyIds` | array of string | required, max 1000 items | Unique identifiers of the companies to be deleted. | ### Response ```javascript {} ``` # Companionships ## Get all companionships Returns all companionships based on customers, reservations or reservation groups. One of them must be specified in the request. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/companionships/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "CompanionshipIds": [ "72d4b117-1f84-44a3-1f84-8b2c0635ac60" ], "CustomerIds": [ "35d4b117-4e60-44a3-9580-c582117eff98" ], "ReservationIds": [ "bfee2c44-1f84-4326-a862-5289598f6e2d" ], "ReservationGroupIds": [ "c704dff3-7811-4af7-a3a0-7b2b0635ac59" ], "UpdatedUtc": { "StartUtc": "2020-02-05T00:00:00Z", "EndUtc": "2020-02-10T00:00:00Z" }, "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. | | `CompanionshipIds` | array of string | optional, max 1000 items | Unique identifiers of `Companionship`. Required if no other filter is provided. | | `Extent` | [Companionship extent](#companionship-extent) | required | Extent of data to be returned. E.g. it is possible to specify that together with the companionships, customers, reservations, and reservation groups should be also returned. | | `ReservationIds` | array of string | optional, max 1000 items | Unique identifiers of `Reservation`. Required if no other filter is provided. | | `CustomerIds` | array of string | optional, max 1000 items | Unique identifiers of `Customer`. Required if no other filter is provided. | | `ReservationGroupIds` | array of string | optional, max 1000 items | Unique identifiers of `ReservationGroup`. Required if no other filter is provided. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the `Companionship` was updated. Must be used together with at least one another filter. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | #### Companionship extent | Property | Type | Contract | Description | | ------------------- | ------- | -------- | ------------------------------------------------------- | | `Reservations` | boolean | optional | Whether the response should contain reservations. | | `ReservationGroups` | boolean | optional | Whether the response should contain reservation groups. | | `Customers` | boolean | optional | Whether the response should contain customers. | ### Response ```javascript { "Companionships": [ { "Id": "72d4b117-1f84-44a3-1f84-8b2c0635ac60", "CustomerId": "35d4b117-4e60-44a3-9580-c582117eff98", "ReservationGroupId": "c704dff3-7811-4af7-a3a0-7b2b0635ac59", "ReservationId": "bfee2c44-1f84-4326-a862-5289598f6e2d" } ], "Customers": null, "Reservations": null, "ReservationGroups": null, "Cursor": "72d4b117-1f84-44a3-1f84-8b2c0635ac60" } ``` | Property | Type | Contract | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Companionships` | array of [Companionship](#companionship) | optional | Companionships. | | `Reservations` | array of [Reservation (ver 2017-04-12)](/connector-api/operations/reservations#reservation-ver-2017-04-12) | optional | The accompanied reservations. | | `ReservationGroups` | array of [Reservation groups (ver 2017-04-12)](/connector-api/operations/reservations#reservation-groups-ver-2017-04-12) | optional | The accompanied reservation groups. | | `Customers` | array of [Customer](/connector-api/operations/customers#customer) | optional | Customers that belong to the companionships. | | `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. | #### Companionship | Property | Type | Contract | Description | | -------------------- | ------ | -------- | -------------------------------------- | | `Id` | string | required | Unique identifier of `Companionship`. | | `CustomerId` | string | required | Unique identifier of Customer. | | `ReservationGroupId` | string | required | Unique identifier of ReservationGroup. | | `ReservationId` | string | optional | Unique identifier of reservation. | # Company contracts ## Get all company contracts Returns all contracts between the enterprise and other companies. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/companyContracts/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CompanyContractIds": [ "3396f6f3-6733-443b-92e0-b2a0009a05a7" ], "CompanyIds": [ "bfd5667b-533f-424f-860d-af150065f4d6" ], "ServiceIds": [ "c8f88563-dc60-47f3-aca3-af150065d951" ], "UpdatedUtc": { "StartUtc": "2023-10-01T00:00:00Z", "EndUtc": "2023-10-31T00:00:00Z" }, "ActivityStates": [ "Active", "Deleted" ], "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. | | `CompanyContractIds` | array of string | optional, max 1000 items | Unique identifier of the Travel agency contracts to fetch. | | `CompanyIds` | array of string | optional, max 1000 items | Unique identifiers of `Company` assigned with Travel agency contracts. | | `ServiceIds` | array of string | optional, max 1000 items | Unique identifiers of `Service` where the Travel agency contracts belong to. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the Travel agency contracts were updated. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted or both records. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "TravelAgencyContracts": [ { "Id": "0078f370-3787-43dc-a615-af150066bb88", "ServiceId": "c8f88563-dc60-47f3-aca3-af150065d951", "CompanyId": "bfd5667b-533f-424f-860d-af150065f4d6", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z", "IsActive": true, "CommissionIncluded": true, "Commission": 0.1, "ChannelManagerAbsoluteAdjustment": 10, "ChannelManagerRelativeAdjustment": 0.15, "Options": { "IncludeCancellationFeeInCommissionEstimate": true, "SkipAutomaticSettlement": true }, "AccountingCode": "P2DT23H", "InvoiceDueInterval": "P0M15DT0H0M0S", "ChannelManagerBusinessSegmentId": "1289d3c8-3c83-4169-b756-af150066bb87", "ContactPerson": "Sample person", "ContactEmail": "sample-person@email.com", "AdditionalContactInfo": null, "Notes": null } ] } ``` | Property | Type | Contract | Description | | ----------------------- | ---------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TravelAgencyContracts` | array of [Travel agency contract](#travel-agency-contract) | required | The travel agency contracts. | | `Cursor` | string | optional | Unique identifier of the last and hence oldest contract returned. This can be used in `Limitation` in a subsequent request to fetch the next batch of older messages. | #### Travel agency contract | Property | Type | Contract | Description | | ---------------------------------- | ----------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the contract. | | `ServiceId` | string | required | Unique identifier of the `Service` the contract is related to. | | `CompanyId` | string | required | Unique identifier of the contracted `Company`. | | `IsActive` | boolean | required | Whether the contract is still active. | | `CommissionIncluded` | boolean | optional | Whether commission of the travel agency is included in the rate. When `CommissionIncluded` is not provided in the response, that means commission is unspecified, when set to true it means the the commission is included in the rate and false means the commission in not included in the rate. | | `Commission` | number | optional | Commission of the travel agency. | | `ChannelManagerAbsoluteAdjustment` | number | optional | Flat fee added to (or subtracted from) the reservation price when coming from Channel Managers. | | `ChannelManagerRelativeAdjustment` | number | optional | Percentage of the reservation price added to (or subtracted from) price when coming from Channel Managers. | | `Options` | [Travel agency contract options](#travel-agency-contract-options) | required | Options of the travel agency contract. | | `AccountingCode` | string | optional | Accounting code of the travel agency contract. | | `InvoiceDueInterval` | string | optional | The maximum time, when the invoice has to be be paid in ISO 8601 duration format. | | `ChannelManagerBusinessSegmentId` | string | optional | Unique identifier of the `BusinessSegment` used for incoming reservations originating from Channel Managers, for this particular contract. | | `ContactPerson` | string | optional | Contact person of the travel agency. | | `ContactEmail` | string | optional | Contact email of the travel agency. | | `AdditionalContactInfo` | string | optional | Additional contact info of the travel agency. | | `Notes` | string | optional | Additional notes of the travel agency contract. | | `CreatedUtc` | string | required | Creation date and time of the travel agency contract in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the travel agency contract in UTC timezone in ISO 8601 format. | #### Travel agency contract options | Property | Type | Contract | Description | | -------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------- | | `IncludeCancellationFeeInCommissionEstimate` | boolean | required | Cancellation fee will be considered when calculating the travel agency commission estimate. | | `SkipAutomaticSettlement` | boolean | required | Reservations from travel agencies will not be automatically charged. | ## Add company contracts Adds one or more company contracts. ### Request `[PlatformAddress]/api/connector/v1/companyContracts/add` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "TravelAgencyContracts": [ { "ServiceId": "c8f88563-dc60-47f3-aca3-af150065d951", "CompanyId": "896e9313-477d-4306-9d37-af150065f4d6", "CommissionIncluded": true, "Commission": 0.1, "ChannelManagerAbsoluteAdjustment": 10, "ChannelManagerRelativeAdjustment": 0.15, "Options": { "IncludeCancellationFeeInCommissionEstimate": false, "SkipAutomaticSettlement": false }, "AccountingCode": "P2DT23H", "InvoiceDueInterval": "P0M15DT0H0M0S", "ChannelManagerBusinessSegmentId": "1289d3c8-3c83-4169-b756-af150066bb87", "ContactPerson": "Sample person", "ContactEmail": "sample-person@email.com", "AdditionalContactInfo": null, "Notes": 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. | | `TravelAgencyContracts` | array of [Travel agency contract parameters](#travel-agency-contract-parameters) | required, max 1000 items | Information about travel agency contracts to be created. | #### Travel agency contract parameters | Property | Type | Contract | Description | | ---------------------------------- | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `ServiceId` | string | required | Unique identifier of the `Service` the travel agency contract is created to. | | `CompanyId` | string | required | Unique identifier of the `Company` the travel agency contract is issued to. | | `CommissionIncluded` | boolean | optional | Whether commission of the travel agency is included in the rate. | | `Commission` | number | optional | Commission of the travel agency. Value must be between 0 and 1. | | `ChannelManagerBusinessSegmentId` | string | optional | Unique identifier of the `BusinessSegment` used for incoming reservations originating from Channel Managers, for this particular contract. | | `ChannelManagerAbsoluteAdjustment` | number | optional | Flat fee added to (or subtracted from) the reservation price when coming from Channel Managers. | | `ChannelManagerRelativeAdjustment` | number | optional | Percentage of the reservation price added to (or subtracted from) price when coming from Channel Managers. Value must be between -1 and 1. | | `Options` | [Travel agency contract options](#travel-agency-contract-options) | required | Options of the travel agency contract. | | `AccountingCode` | string | optional | Accounting code of the travel agency contract. | | `InvoiceDueInterval` | string | optional | The maximum time, when the invoice has to be be paid in ISO 8601 duration format. | | `ContactPerson` | string | optional | Contact person of the travel agency. | | `ContactEmail` | string | optional | Contact email of the travel agency. | | `AdditionalContactInfo` | string | optional | Additional contact info of the travel agency. | | `Notes` | string | optional | Additional notes of the travel agency contract. | ### Response ```javascript { "TravelAgencyContracts": [ { "Id": "0078f370-3787-43dc-a615-af150066bb88", "ServiceId": "c8f88563-dc60-47f3-aca3-af150065d951", "CompanyId": "bfd5667b-533f-424f-860d-af150065f4d6", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z", "IsActive": true, "CommissionIncluded": true, "Commission": 0.1, "ChannelManagerAbsoluteAdjustment": 10, "ChannelManagerRelativeAdjustment": 0.15, "Options": { "IncludeCancellationFeeInCommissionEstimate": true, "SkipAutomaticSettlement": true }, "AccountingCode": "P2DT23H", "InvoiceDueInterval": "P0M15DT0H0M0S", "ChannelManagerBusinessSegmentId": "1289d3c8-3c83-4169-b756-af150066bb87", "ContactPerson": "Sample person", "ContactEmail": "sample-person@email.com", "AdditionalContactInfo": null, "Notes": null } ] } ``` | Property | Type | Contract | Description | | ----------------------- | ---------------------------------------------------------- | -------- | ---------------------------------- | | `TravelAgencyContracts` | array of [Travel agency contract](#travel-agency-contract) | required | The added travel agency contracts. | ## Update company contracts Updates one or more company contracts. ### Request `[PlatformAddress]/api/connector/v1/companyContracts/update` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "TravelAgencyContractUpdates": [ { "TravelAgencyContractId": "652d4a22-ac33-42b7-abe7-af1f00820023", "CommissionIncluded": { "Value": true }, "Commission": { "Value": 0.1 }, "ChannelManagerAbsoluteAdjustment": { "Value": 10 }, "ChannelManagerRelativeAdjustment": { "Value": 0.15 }, "Options": { "IncludeCancellationFeeInCommissionEstimate": { "Value": true }, "SkipAutomaticSettlement": { "Value": true } }, "AccountingCode": { "Value": "P2DT23H" }, "InvoiceDueInterval": { "Value": "P0M15DT0H0M0S" }, "ChannelManagerBusinessSegmentId": { "Value": "1289D3C8-3C83-4169-B756-AF150066BB87" }, "ContactPerson": { "Value": "Sample person" }, "ContactEmail": { "Value": "sample-person@email.com" }, "AdditionalContactInfo": null, "Notes": 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. | | `TravelAgencyContractUpdates` | array of [Travel agency contract update parameters](#travel-agency-contract-update-parameters) | required, max 1000 items | Information about travel agency contracts to be updated. | #### Travel agency contract update parameters | Property | Type | Contract | Description | | ---------------------------------- | ------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `TravelAgencyContractId` | string | required | Unique identifier of the Travel agency contract. | | `CommissionIncluded` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | optional | Whether commission of the travel agency is included in the rate. | | `Commission` | [Number update value](/connector-api/operations/_objects#number-update-value) | optional | Commission of the travel agency. | | `ChannelManagerBusinessSegmentId` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Unique identifier of the `BusinessSegment` used for incoming reservations originating from Channel Managers, for this particular contract. | | `ChannelManagerAbsoluteAdjustment` | [Number update value](/connector-api/operations/_objects#number-update-value) | optional | Flat fee added to (or subtracted from) the reservation price when coming from Channel Managers. | | `ChannelManagerRelativeAdjustment` | [Number update value](/connector-api/operations/_objects#number-update-value) | optional | Percentage of the reservation price added to (or subtracted from) price when coming from Channel Managers. | | `Options` | [Travel agency contract update options](#travel-agency-contract-update-options) | optional | Options of the travel agency contract. | | `AccountingCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Accounting code of the travel agency contract. | | `InvoiceDueInterval` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | The maximum time, when the invoice has to be be paid in ISO 8601 duration format. | | `ContactPerson` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Contact person of the travel agency. | | `ContactEmail` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Contact email of the travel agency. | | `AdditionalContactInfo` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Additional contact info of the travel agency. | | `Notes` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | Additional notes of the travel agency contract. | #### Travel agency contract update options | Property | Type | Contract | Description | | -------------------------------------------- | ------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | | `IncludeCancellationFeeInCommissionEstimate` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | required | Cancellation fee will be considered when calculating the travel agency commission estimate. | | `SkipAutomaticSettlement` | [Bool update value](/connector-api/operations/_objects#bool-update-value) | required | Reservations from travel agencies will not be automatically charged. | ### Response ```javascript { "TravelAgencyContracts": [ { "Id": "0078f370-3787-43dc-a615-af150066bb88", "ServiceId": "c8f88563-dc60-47f3-aca3-af150065d951", "CompanyId": "bfd5667b-533f-424f-860d-af150065f4d6", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z", "IsActive": true, "CommissionIncluded": true, "Commission": 0.1, "ChannelManagerAbsoluteAdjustment": 10, "ChannelManagerRelativeAdjustment": 0.15, "Options": { "IncludeCancellationFeeInCommissionEstimate": true, "SkipAutomaticSettlement": true }, "AccountingCode": "P2DT23H", "InvoiceDueInterval": "P0M15DT0H0M0S", "ChannelManagerBusinessSegmentId": "1289d3c8-3c83-4169-b756-af150066bb87", "ContactPerson": "Sample person", "ContactEmail": "sample-person@email.com", "AdditionalContactInfo": null, "Notes": null } ] } ``` | Property | Type | Contract | Description | | ----------------------- | ---------------------------------------------------------- | -------- | ------------------------------------ | | `TravelAgencyContracts` | array of [Travel agency contract](#travel-agency-contract) | required | The updated travel agency contracts. | ## Delete company contracts Deletes one or more company contracts. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/companyContracts/delete` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "TravelAgencyContractIds": [ "0078f370-3787-43dc-a615-af150066bb88", "652d4a22-ac33-42b7-abe7-af1f00820023" ], "ServiceIds": [ "a1d6dee8-355b-44c3-b6be-faef1a7eb6c0", "d5a2aac3-5194-479b-ba05-6c073398e0fd" ] } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `TravelAgencyContractIds` | array of string | required, max 1000 items | Unique identifiers of the Travel agency contract to delete. | | `ServiceIds` | array of string | required, max 1000 items | Unique identifiers of the `Service` the travel agency contract belongs to. | ### Response ```javascript {} ``` # Configuration ## Get configuration Returns the enterprise configuration. For single-enterprise Access Tokens, this is the enterprise associated with the token. For [Portfolio Access Tokens](/connector-api/concepts/multi-property), use the `EnterpriseId` parameter to specify which enterprise you want the configuration for. In the case of service scoped integrations, the operation returns the configuration associated with both the enterprise and the bookable service linked to the token. ### Request `[PlatformAddress]/api/connector/v1/configuration/get` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseId": "851df8c8-90f2-4c4a-8e01-a4fc46b25178" } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the [Enterprise](#enterprise), defaults to the enterprise associated with the given access token. | ### Response ```javascript { "NowUtc": "2018-01-01T14:58:02Z", "Enterprise": { "Currencies": [ { "Currency": "GBP", "IsDefault": true, "IsEnabled": true }, { "Currency": "USD", "IsDefault": false, "IsEnabled": true } ], "AccountingConfiguration": { "AdditionalTaxIdentifier": null, "CompanyName": "Connector API Hotel", "BankAccountNumber": "1234", "BankName": "Random bank", "Iban": "CZ7250517882393618329719", "Bic": "GIBACZPY", "SurchargeConfiguration": { "SurchargeFees": { "Amex": 3, "DinersClub": 4 }, "SurchargeServiceId": "2b9b0143-3135-485b-8064-76c90d1be69e", "SurchargeTaxCode": "US-HI-KA" }, "EnabledExternalPaymentTypes": [ "Invoice", "Cash", "GiftCard" ], "Options": [ "ReceivableTrackingEnabled", "GroupTaxesOnBill" ] }, "IsPortfolio": false, "Id": "851df8c8-90f2-4c4a-8e01-a4fc46b25178", "ExternalIdentifier": null, "HoldingKey": "CA123", "ChainId": "8ddea57b-6a5c-4eec-8c4c-24467dce118e", "ChainName": "Connector API Chain", "CreatedUtc": "2015-07-07T13:33:17Z", "UpdatedUtc": "2015-07-07T13:33:17Z", "Name": "Connector API Hotel", "ShortName": null, "TimeZoneIdentifier": "Europe/Budapest", "LegalEnvironmentCode": "UK", "AccommodationEnvironmentCode": null, "AccountingEnvironmentCode": null, "TaxEnvironmentCode": null, "DefaultLanguageCode": "en-US", "EditableHistoryInterval": "P0M7DT0H0M0S", "AccountingEditableHistoryInterval": "P0M7DT0H0M0S", "OperationalEditableHistoryInterval": "P0M5DT0H0M0S", "BusinessDayClosingOffset": null, "WebsiteUrl": "https://en.wikipedia.org/wiki/St._Vitus_Cathedral", "Email": "charging-api@mews.li", "Phone": "00000 123 456 789", "LogoImageId": null, "CoverImageId": null, "Pricing": "Gross", "TaxPrecision": null, "AddressId": "c556f56e-713e-4102-9de5-0e853b5a8586", "Address": { "Id": "8c2c4371-5d42-40a9-b551-ab0b00d75076", "Line1": "I.P. Pavlova 5", "Line2": null, "City": "Prague", "PostalCode": "1200", "CountryCode": "CZ", "CountrySubdivisionCode": null, "Latitude": 14.429645, "Longitude": 50.075181 }, "GroupNames": [ "Connector API Group" ], "Subscription": { "TaxIdentifier": "123456789 RC 0001" } }, "Service": { "Id": "bd26d8db-86da-4f96-9efc-e5a4654a4a94", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "IsActive": true, "Name": "Accommodation", "Names": { "en-GB": "Accommodation" }, "StartTime": "PT14H", "EndTime": "PT12H", "Options": { "BillAsPackage": false }, "Promotions": { "BeforeCheckIn": false, "AfterCheckIn": false, "DuringStay": false, "BeforeCheckOut": false, "AfterCheckOut": false, "DuringCheckOut": false }, "Type": "Reservable", "Ordering": 0, "Data": null, "ExternalIdentifier": null, "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z" }, "PaymentCardStorage": null, "IsIdentityDocumentNumberRequired": true } ``` | Property | Type | Contract | Description | | ---------------------------------- | ----------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NowUtc` | string | required | Current server date and time in UTC timezone in ISO 8601 format. | | `Enterprise` | [Enterprise](#enterprise) | required | The enterprise (e.g. hotel, hostel) associated with the access token. | | `Service` | [Service](/connector-api/operations/services#service) | optional | The reservable service (e.g. accommodation, parking) associated with the access token of the service scoped integration. | | `PaymentCardStorage` | [Payment card storage](#payment-card-storage) | optional | Contains information about payment card storage. | | `IsIdentityDocumentNumberRequired` | boolean | required | Whether the identity documents for this enterprise include the value of identity document number as required by the legal environment. When `false`, the number is not required, and an empty string can be used in write operations. In read operations, an empty string is returned when an empty string was provided for the number. | #### Enterprise | Property | Type | Contract | Description | | ------------------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the enterprise. | | `ExternalIdentifier` | string | optional, max length 255 characters | Identifier of the enterprise from external system. | | `HoldingKey` | string | optional, max length 255 characters | Identifies an enterprise in the external system of a holding company. The holding company may administer multiple portfolios. | | `ChainId` | string | required | Unique identifier of the chain to which the enterprise belongs. | | `ChainName` | string | required | Name of the `Chain` to which the enterprise belongs. | | `CreatedUtc` | string | required | Creation date and time of the enterprise in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the enterprise in UTC timezone in ISO 8601 format. | | `Name` | string | required | Name of the enterprise. | | `ShortName` | string | optional, max length 11 characters | Short name of the enterprise used in Manager Report exports. | | `TimeZoneIdentifier` | string | required | IANA timezone identifier of the enterprise. | | `LegalEnvironmentCode` | string | required | Unique identifier of the legal environment where the enterprise resides. | | `AccommodationEnvironmentCode` | string | required | Unique code of the accommodation environment where the enterprise resides. | | `AccountingEnvironmentCode` | string | required | Unique code of the accounting environment where the enterprise resides. | | `TaxEnvironmentCode` | string | required | Unique code of the tax environment where the enterprise resides. | | `DefaultLanguageCode` | string | required | Language-culture codes of the enterprise default `Language`. | | `AccountingEditableHistoryInterval` | string | required | Editable history interval for accounting data in ISO 8601 duration format. | | `OperationalEditableHistoryInterval` | string | required | Editable history interval for operational data in ISO 8601 duration format. | | `BusinessDayClosingOffset` | string | optional | The offset value for the business day closing time, in ISO 8601 duration format. | | `WebsiteUrl` | string | optional | URL of the enterprise website. | | `Email` | string | optional | Email address of the enterprise. | | `Phone` | string | optional | Phone number of the enterprise. | | `LogoImageId` | string | optional | Unique identifier of the `Image` of the enterprise logo. | | `CoverImageId` | string | optional | Unique identifier of the `Image` of the enterprise cover. | | `Pricing` | [Pricing](#pricing) | required | Pricing of the enterprise. | | `TaxPrecision` | integer | optional | Tax precision used for financial calculations in the enterprise. If `null`, `Currency` precision is used. | | `AddressId` | string | required | Unique identifier of the `Address` of the enterprise. | | `Address` | [Address](#address) | required | Address of the enterprise. | | `GroupNames` | array of string | required | A list of the group names of the enterprise. | | `Subscription` | [Enterprise subscription](/connector-api/operations/enterprises#enterprise-subscription) | required | Subscription information of the enterprise. | | `Currencies` | array of [Accepted currency](#accepted-currency) | required | Currencies accepted by the enterprise. | | `AccountingConfiguration` | [Accounting configuration](#accounting-configuration) | optional | Configuration information containing financial information about the property. | | `IsPortfolio` | boolean | required | Whether the enterprise is a Portfolio enterprise (see [Multi-property guidelines](https://github.com/MewsSystems/open-api-docs/blob/main/connector-api/guidelines/multi-property.md)). | | ~~`EditableHistoryInterval`~~ | ~~string~~ | ~~required~~ | **Deprecated!** Use `AccountingEditableHistoryInterval` and `OperationalEditableHistoryInterval` instead. | #### Pricing * `Gross` - The enterprise shows amount with gross prices. * `Net` - The enterprise shows amount with net prices. #### Address | Property | Type | Contract | Description | | ------------------------ | ------ | -------- | ------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the address. | | `Line1` | string | optional | First line of the address. | | `Line2` | string | optional | Second line of the address. | | `City` | string | optional | The city. | | `PostalCode` | string | optional | Postal code. | | `CountryCode` | string | optional | ISO 3166-1 code of the `Country`. | | `CountrySubdivisionCode` | string | optional | ISO 3166-2 code of the administrative division, e.g. `DE-BW`. | | `Latitude` | number | optional | The latitude. | | `Longitude` | number | optional | The longitude. | #### Accepted currency | Property | Type | Contract | Description | | ----------- | ------- | -------- | ------------------------------------------------------ | | `Currency` | string | required | ISO-4217 code of the `Currency`. | | `IsDefault` | boolean | required | Whether the currency is a default accounting currency. | | `IsEnabled` | boolean | required | Whether the currency is enabled for usage. | #### Accounting configuration | Property | Type | Contract | Description | | ----------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------- | | `AdditionalTaxIdentifier` | string | optional, max length 50 characters | Organization number. | | `CompanyName` | string | optional, max length 100 characters | Legal name of the company. | | `BankAccountNumber` | string | optional, max length 50 characters | Bank account number. | | `BankName` | string | optional, max length 100 characters | Name of the bank. | | `Iban` | string | optional, max length 40 characters | International Bank Account Number. | | `Bic` | string | optional, max length 11 characters | Business Identification Code. | | `SurchargeConfiguration` | [Surcharging fees configuration](#surcharging-fees-configuration) | required | Configuration for surcharging fees. | | `EnabledExternalPaymentTypes` | array of [External payment type](/connector-api/operations/payments#external-payment-type) | required | External payment types that are enabled for the enterprise and can be used in `payments/addExternal`. | | `Options` | array of [Accounting configuration option](#accounting-configuration-option) | required | Accounting configuration options. | #### Surcharging fees configuration | Property | Type | Contract | Description | | -------------------- | --------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- | | `SurchargeFees` | [Dictionary of numbers](/connector-api/operations/_objects#dictionary-of-numbers) | required | Dictionary keys are `CreditCardType` and values are surcharging fees as a percentage. | | `SurchargeServiceId` | string | optional | Unique identifier of the surcharging `Service`. | | `SurchargeTaxCode` | string | optional | Surcharging fee `TaxCode`. | #### Accounting configuration option {% hint style="info" icon="circle-ellipsis" %} **Note** the list of values is not exhaustive. The API may return additional values that are not listed here. {% endhint %} * `OptionalCreditCardPaymentDetails` - Optional credit card payment details * `ReceivableTrackingEnabled` - Receivable tracking enabled * `SeparateDepositsOnBill` - Separate deposits on bill * `AllowModifyingClosedBills` - Allow modifying closed bills * `RequireAccountingCategorySetup` - Require accounting category setup * `GroupTaxesOnBill` - Group taxes on bill * `DisplayEmployeeNameOnBill` - Display employee name on bill * `TaxDeclarationOnDeposit` - Tax declaration on deposit * `SplitVatByClassificationOnBill` - Split VAT by classification on bill * `EmailClosedBillsAfterCheckout` - Send system closed bills automatically after checkout * … #### Payment card storage | Property | Type | Contract | Description | | ----------- | ------ | -------- | ------------------------------------ | | `PublicKey` | string | required | Key for accessing PCI proxy storage. | # Counters ## Get all counters Returns all counters of an enterprise associated with the connector integration. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/counters/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "UpdatedUtc": { "StartUtc": "2023-10-01T00:00:00Z", "EndUtc": "2023-10-31T00:00:00Z" }, "Type": "Counter", "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. | | `CounterIds` | array of string | optional, max 1000 items | Unique identifiers of the counters. If not specified, the operation returns all counters. | | `Type` | [Counter type discriminator](#counter-type-discriminator) | optional | Type of the counter. If not specified, the operation returns all types. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which `Counter` was updated. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "Counters": [ { "Id": "b7e4b68a-026e-41f3-ad2f-35325aa5dcbf", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "Normal", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z", "IsDefault": false, "Value": 67, "Format": "NORMAL{0:0000}", "Type": "BillCounter" }, { "Id": "403842df-635f-4b6e-8de5-42129201235e", "EnterpriseId": "4d0201db-36f5-428b-8d11-4f0a65e960cc", "Name": "Events", "IsDefault": true, "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z", "Value": 1575, "Format": "E2018{0:0000}", "Type": "BillCounter" }, { "Id": "3362d7d5-a52f-4077-b2b4-4ec2476e6e19", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "Default", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z", "IsDefault": true, "Value": 171, "Format": "", "Type": "ProformaCounter" }, { "Id": "1162d7d5-a52f-4077-b2b4-4ec2476e6e19", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "Default", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z", "IsDefault": true, "Value": 911, "Format": "", "Type": "BillPreviewCounter" }, { "Id": "a9fd7868-1ed0-4e96-8dd9-580708c200ea", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "Default", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z", "IsDefault": true, "Value": 25797, "Format": null, "Type": "ServiceOrderCounter" } ] } ``` | Property | Type | Contract | Description | | ------------------------------ | ------------------------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Counters` | array of [Counter](#counter) | required | All types of counters. | | `Cursor` | string | optional | Unique identifier of the last returned counter in `Counters`. This can be used in Limitation in a subsequent request to fetch the next batch of counters. | | ~~`BillCounters`~~ | ~~array of~~ [~~Counter~~](#counter) | ~~required~~ | ~~The counters used to count closed `Bills`.~~ **Deprecated!** Use `Counters` instead. | | ~~`ProformaCounters`~~ | ~~array of~~ [~~Counter~~](#counter) | ~~required~~ | ~~The counters used to count Pro Forma invoices for `Bills`.~~ **Deprecated!** Use `Counters` instead. | | ~~`BillPreviewCounters`~~ | ~~array of~~ [~~Counter~~](#counter) | ~~required~~ | ~~The counters used to count bill previews for `Bills`.~~ **Deprecated!** Use `Counters` instead. | | ~~`ServiceOrderCounters`~~ | ~~array of~~ [~~Counter~~](#counter) | ~~required~~ | ~~The counters used to count service orders (for example reservations).~~ **Deprecated!** Use `Counters` instead. | | ~~`RegistrationCardCounters`~~ | ~~array of~~ [~~Counter~~](#counter) | ~~required~~ | ~~The counters used to count registration cards.~~ **Deprecated!** Use `Counters` instead. | #### Counter | Property | Type | Contract | Description | | -------------- | --------------------------------------------------------- | -------- | ---------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the counter. | | `EnterpriseId` | string | required | Unique identifier of the enterprise to which the counter belongs. | | `Name` | string | required | Name of the counter. | | `IsDefault` | boolean | required | Whether the counter is used by default. | | `Value` | integer | required | Current value of the counter. | | `Format` | string | required | Display format of the counter. | | `Type` | [Counter type discriminator](#counter-type-discriminator) | required | Type of the counter. | | `CreatedUtc` | string | required | Creation date and time of the counter in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the counter in UTC timezone in ISO 8601 format. | #### Counter type discriminator * `Counter` - Any type of counter. * `AccountingCounter` * `AvailabilityBlockCounter` * `BillCounter` * `BillPreviewCounter` * `FiscalCounter` * `ProformaCounter` * `RegistrationCardCounter` * `ServiceOrderCounter` * `CorrectionBillCounter` * `PaymentConfirmationBillCounter` * `CreditNoteBillCounter` * `PaymentSplitBillCounter` # Countries ## Get all countries Returns all countries supported by the API. ### Request `[PlatformAddress]/api/connector/v1/countries/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0" } ``` | 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. | ### Response ```javascript { "Countries": [ { "Code": "GB", "EnglishName": "United Kingdom of Great Britain and Northern Ireland" }, { "Code": "US", "EnglishName": "United States of America" } ], "CountrySubdivisions": [ { "Code": "AU-NSW", "CountryCode": "AU", "EnglishName": "New South Wales" }, { "Code": "AU-QLD", "CountryCode": "AU", "EnglishName": "Queensland" } ], "CountryAlliances": [ { "Code": "SCHENGEN", "EnglishName": "Schengen Area", "CountryCodes": [ "AT", "BE", "CZ", "..." ] } ] } ``` | Property | Type | Contract | Description | | --------------------- | ---------------------------------------------------- | -------- | ----------------------------------- | | `Countries` | array of [Country](#country) | required | The supported countries. | | `CountrySubdivisions` | array of [Country subdivision](#country-subdivision) | required | The supported country subdivisions. | | `CountryRules` | array of [Country rules](#country-rules) | required | Country-specific rules | | `CountryGroups` | array of [Country group](#country-group) | required | The supported country groups. | #### Country | Property | Type | Contract | Description | | ---------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------- | | `Code` | string | required | ISO 3166-1 alpha-2 code, e.g. `CZ` or `SK`. | | `SovereignCountryCode` | string | required | ISO 3166-1 alpha-2 code of the sovereign country. May differ from `Code` for dependent territories. | | `EnglishName` | string | required | English name of the country. | #### Country subdivision | Property | Type | Contract | Description | | ------------- | ------ | -------- | ----------------------------------------------------------- | | `Code` | string | required | ISO 3166-2 code of the administrative division, e.g AU-QLD. | | `CountryCode` | string | required | ISO 3166-1 code of the [Country](#country). | | `EnglishName` | string | required | English name of the country subdivision. | #### Country rules Country-specific rules | Property | Type | Contract | Description | | ---------------------------------------- | ------- | -------- | ------------------------------------------------------------------ | | `CountryCode` | string | required | ISO 3166-1 alpha-2 code, e.g. US or GB. | | `IdentityCardExpirationDateNotRequired` | boolean | required | Whether the country requires expiration date for identity card. | | `DriverLicenceExpirationDateNotRequired` | boolean | required | Whether the country requires expiration date for driver's license. | #### Country group | Property | Type | Contract | Description | | -------------- | --------------- | -------- | ----------------------------------------------------------------------- | | `Code` | string | required | Group code, e.g. `EU`, `SCHENGEN`, `NORDIC`... | | `EnglishName` | string | required | English name of the country group. | | `CountryCodes` | array of string | required | Codes of countries included in the group, in ISO 3166-1 alpha-2 format. | # Credit cards ## Get all credit cards Returns all credit cards, possibly filtered by identifiers, [Customers](/connector-api/operations/customers#customer) or other filters. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/creditCards/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "CreditCardIds": [ "f1d94a32-b4be-479b-9e47-a9fcb03d5196" ], "CustomerIds": [ "5cbbd97d-5f19-4010-9abf-ab0400a3366a" ], "UpdatedUtc": { "StartUtc": "2023-10-01T00:00:00Z", "EndUtc": "2023-10-31T00:00:00Z" }, "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. | | `CreditCardIds` | array of string | optional, max 1000 items | Unique identifiers of the `CreditCard`. Required if no other filter is provided. | | `CustomerIds` | array of string | optional, max 1000 items | Unique identifiers of the `Customer`. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which `CreditCard` was updated. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "CreditCards": [ { "Id": "f1d94a32-b4be-479b-9e47-a9fcb03d5196", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z", "CustomerId": "a3c90426-43f2-4b53-8482-446dfc724bd2", "Expiration": "2020-11", "Format": "Physical", "IsActive": true, "Kind": "Gateway", "ObfuscatedNumber": "************1111", "State": "Enabled", "Type": "Visa" } ], "Cursor": "f1d94a32-b4be-479b-9e47-a9fcb03d5196" } ``` | Property | Type | Contract | Description | | ------------- | ------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CreditCards` | array of [Credit card](#credit-card) | required | The credit cards. | | `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. | #### Credit card | Property | Type | Contract | Description | | ------------------ | ----------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `Id` | string | required | Unique identifier of the credit card. | | `EnterpriseId` | string | required | Unique identifier of the `Enterprise`. | | `CustomerId` | string | required | Unique identifier of the credit card owner (`Customer`). | | `IsActive` | boolean | required | Whether the credit card is still active. | | `State` | [Credit card state](#credit-card-state) | required | State of the credit card. | | `Kind` | [Credit card kind](#credit-card-kind) | required | Kind of the credit card. | | `Format` | [Credit card format](#credit-card-format) | required | Format of the credit card. | | `Type` | [Credit card type](#credit-card-type) | optional | Type of the credit card. | | `ObfuscatedNumber` | string | optional | Obfuscated credit card number. At most first six digits and last four digits can be specified, otherwise the digits are replaced with `*`. | | `Expiration` | string | optional | Expiration of the credit card in format `MM/YYYY`. | | `CreatedUtc` | string | required | Creation date and time of the credit card in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the credit card in UTC timezone in ISO 8601 format. | #### Credit card state * `Enabled` * `Disabled` #### Credit card kind * `Terminal` * `Gateway` #### Credit card format * `Physical` * `Virtual` #### Credit card type * `MasterCard` * `Visa` * `Amex` * `Discover` * `DinersClub` * `Jcb` * `Maestro` * `UnionPay` * `VPay` * `RuPay` * `Dankort` * `Mir` * `Verve` * `Troy` * `PostFinance` * `Giro` * `Bancomat` * `Bc` * `CarteBleue` * `Eftpos` * `Eps` * `Interac` * `Isracard` * `Meps` * `Nets` * `Bancontact` ## Add tokenized credit card Adds a new tokenized credit card to the specified customer. To be able to use this operation special permission has to be granted during certification. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/creditCards/addTokenized` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CustomerId": "fadd5bb6-b428-45d5-94f8-fd0d89fece6d", "CreditCardData": { "Expiration": "2025-10" }, "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `CustomerId` | string | required | Unique identifier of the `Customer`. | | `CreditCardData` | [Credit card data](#credit-card-data) | required | Credit card details provided by PCI provider. | #### Credit card data | Property | Type | Contract | Description | | ------------- | ------ | -------- | ---------------------------------------------------------------- | | `StorageData` | string | required | Identifier of credit card data in PCI storage (`transactionId`). | | `Expiration` | string | required | Expiration of the credit card in format `yyyy-MM`. | ### Response ```javascript { "CreditCardId": "e417dfe8-c813-4938-837b-36081199ce88" } ``` | Property | Type | Contract | Description | | -------------- | ------ | -------- | -------------------------------------- | | `CreditCardId` | string | required | Unique identifier of the `CreditCard`. | ## Disable gateway credit card > #### Restricted! > > This operation is currently in beta-test and as such it is subject to change. Disable an existing credit card in the system. Only gateway credit cards can be disabled. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/creditCards/disable` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CreditCardId": "f5c6b7a8-9d4f-4e2a-8a3b-2f3b8b9e6a1f", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | 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. | | `EnterpriseId` | string | optional | Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `CreditCardId` | string | required | Unique identifier of the `CreditCard` to disable. | ### Response ```javascript {} ``` ## Charge credit card Creates payment for specified customer credit card and charges the credit card via a gateway. Note that the kind of the card has to be `Gateway`. ### Request `[PlatformAddress]/api/connector/v1/creditCards/charge` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CreditCardId": "866d3f51-5b8b-4e8f-a3af-5b84768c522d", "Amount": { "GrossValue": 5, "Currency": "EUR" }, "AccountingCategoryId": null, "Notes": null, "ReceiptIdentifier": 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. | | `CreditCardId` | string | required | Unique identifier of the `CreditCard`. | | `ReceiptIdentifier` | string | optional | Identifier of the payment receipt. | | `AccountingCategoryId` | string | optional | Unique identifier of the `AccountingCategory`. | | `ReservationId` | string | optional | Unique identifier of the reservation the payment belongs to. | | `Amount` | [Amount parameters](/connector-api/operations/_objects#amount-parameters) | required | Amount of the credit card payment. | | `Notes` | string | optional | Additional payment notes. | ### Response ```javascript { "PaymentId": "98753f51-5b8b-4e8f-a3af-5b8476865983" } ``` | Property | Type | Contract | Description | | ----------- | ------ | -------- | ---------------------------------------- | | `PaymentId` | string | required | Unique identifier of the `Payment` item. | # Currencies ## Get all currencies Returns all currencies supported by the API. ### Request `[PlatformAddress]/api/connector/v1/currencies/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0" } ``` | 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. | ### Response ```javascript { "Currencies": [ { "Code": "USD", "Precision": 2 }, { "Code": "GBP", "Precision": 2 } ] } ``` | Property | Type | Contract | Description | | ------------ | ------------------------------ | -------- | ------------------------- | | `Currencies` | array of [Currency](#currency) | required | The supported currencies. | #### Currency | Property | Type | Contract | Description | | ----------- | ------- | -------- | ---------------------------------------------------- | | `Code` | string | required | ISO-4217 three-letter code, e.g. USD or GBP. | | `Precision` | integer | required | Precision of the currency (count of decimal places). | # Customers ## Get all customers Returns all customers filtered by identifiers, emails, names and other filters. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/customers/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ChainIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "5fcd1933-22f2-40b9-84da-7db04cbecec2" ], "CreatedUtc": { "StartUtc": "2018-01-01T00:00:00Z", "EndUtc": "2018-01-30T00:00:00Z" }, "UpdatedUtc": { "StartUtc": "2018-01-02T00:00:00Z", "EndUtc": "2018-01-30T00:00:00Z" }, "Extent": { "Customers": true, "Documents": false, "Addresses": false }, "ActivityStates": [ "Active" ], "CustomerIds": [ "fadd5bb6-b428-45d5-94f8-fd0d89fece6d" ], "CompanyIds": [ "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f" ], "Emails": [ "j.smith@example.com" ], "FirstNames": [ "John", "Jane" ], "LastNames": [ "Doe", "Smith" ], "LoyaltyCodes": [ "LL810213" ], "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. | | `ChainIds` | array of string | optional, max 1000 items | Unique identifiers of the chains. Required when using Portfolio Access Tokens, ignored otherwise. | | `CreatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which Customer was created. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which Customer was updated. | | `Extent` | [Customer extent](#customer-extent) | required | Extent of data to be returned. | | `DeletedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which Customer was deleted. `ActivityStates` value `Deleted` should be provided with this filter to get expected results. | | `ActivityStates` | array of [Activity state](/connector-api/operations/_objects#activity-state) | optional | Whether to return only active, only deleted or both records. | | `CustomerIds` | array of string | optional, max 1000 items | Unique identifiers of Customers. Required if no other filter is provided. | | `CompanyIds` | array of string | optional, max 1 item | Unique identifier of the Company the customer is associated with. | | `Emails` | array of string | optional, max 1000 items | Emails of the [Customers](#customer). | | `FirstNames` | array of string | optional, max 1000 items | First names of the [Customers](#customer). | | `LastNames` | array of string | optional, max 1000 items | Last names of the [Customers](#customer). | | `LoyaltyCodes` | array of string | optional, max 1000 items | Loyalty codes of the [Customers](#customer). | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned. | #### Customer extent | Property | Type | Contract | Description | | --------------- | ----------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Customers` | boolean | optional | Whether the response should contain information about customers. | | `Addresses` | boolean | optional | Whether the response should contain addresses of customers. | | ~~`Documents`~~ | ~~boolean~~ | ~~optional~~ | ~~Whether the response should contain identity documents of customers.~~ **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) instead. | ### Response ```javascript { "Customers": [ { "Id": "fadd5bb6-b428-45d5-94f8-fd0d89fece6d", "ChainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Number": "12345", "Title": "Mister", "CustomTitleName": null, "Sex": "Male", "FirstName": "John", "LastName": "Smith", "SecondLastName": "Williams", "NationalityCode": "US", "PreferredLanguageCode": "en-GB", "LanguageCode": "en-US", "BirthDate": "1983-12-31", "BirthCountryCode": null, "BirthCountrySubdivisionCode": null, "BirthPlace": "New York City, NY", "Occupation": "Carpenter", "Email": "j.smith@example.com", "HasOtaEmail": false, "Phone": "00420123456789", "TaxIdentificationNumber": "123456789", "LoyaltyCode": "LL810213", "AccountingCode": "AC123", "BillingCode": null, "Notes": "", "CarRegistrationNumber": "1A2 3456", "DietaryRequirements": null, "CreatedUtc": "2018-01-01T00:00:00Z", "UpdatedUtc": "2018-01-02T00:00:00Z", "Passport": null, "IdentityCard": null, "Visa": null, "DriversLicense": null, "Address": { "Id": "f8495413-bf49-45dd-843c-44be7f365569", "Line1": "Somerford Road Hello House/135", "Line2": null, "City": "Christchurch", "PostalCode": "BH23 3PY", "CountryCode": "GB", "CountrySubdivisionCode": "GB-ENG", "Latitude": null, "Longitude": null }, "AddressId": "f8495413-bf49-45dd-843c-44be7f365569", "Classifications": [ "Returning" ], "Options": [ "SendMarketingEmails" ], "ItalianDestinationCode": null, "ItalianFiscalCode": null, "ItalianLotteryCode": null, "CompanyId": "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f", "MergeTargetId": null, "ActivityState": "Active", "IsActive": true, "PreferredSpaceFeatures": [ "OceanView" ], "CreatorProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf", "UpdaterProfileId": "122fc063-ec6e-4198-b8db-6b168a59ffae" }, { "Id": "35d4b117-4e60-44a3-9580-c582117eff98", "ChainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Number": "573204", "Title": null, "CustomTitleName": "Lady", "Sex": "Female", "FirstName": "Eleanor", "LastName": "Windsor", "SecondLastName": null, "NationalityCode": "GB", "PreferredLanguageCode": "en-GB", "LanguageCode": null, "BirthDate": "1961-04-17", "BirthCountryCode": null, "BirthCountrySubdivisionCode": null, "BirthPlace": null, "Occupation": null, "Email": "eleanor.windsor@example.com", "HasOtaEmail": false, "Phone": "+44 20 7946 0958", "TaxIdentificationNumber": null, "LoyaltyCode": null, "AccountingCode": null, "BillingCode": null, "Notes": null, "CarRegistrationNumber": null, "DietaryRequirements": null, "CreatedUtc": "2025-11-05T10:15:00Z", "UpdatedUtc": "2026-02-20T08:30:00Z", "Passport": null, "IdentityCard": null, "Visa": null, "DriversLicense": null, "Address": null, "AddressId": null, "Classifications": [ "VeryImportant", "Returning" ], "Options": [], "ItalianDestinationCode": null, "ItalianFiscalCode": null, "ItalianLotteryCode": null, "CompanyId": null, "MergeTargetId": null, "ActivityState": "Active", "IsActive": true, "PreferredSpaceFeatures": [], "CreatorProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf", "UpdaterProfileId": "122fc063-ec6e-4198-b8db-6b168a59ffae" } ], "Documents": null, "Cursor": "35d4b117-4e60-44a3-9580-c582117eff98" } ``` | Property | Type | Contract | Description | | --------------- | -------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Customers` | array of [Customer](#customer) | required | The customers. | | `Cursor` | string | optional | Unique identifier of the last and hence oldest customer item returned. This can be used in [Limitation](/connector-api/guidelines/pagination#limitation) in a subsequent request to fetch the next batch of older customers. If [Limitation](/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. | | ~~`Documents`~~ | ~~array of~~ [~~Identity document~~](#identity-document) | ~~optional~~ | ~~The identity documents of customers.~~ **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | #### Customer | Property | Type | Contract | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the customer. | | `ChainId` | string | required | Unique identifier of the chain. | | `Number` | string | required, max length 19 characters | Unique number of the customer (max 19 digits). | | `Title` | [Title](#title) | optional | Title of the customer. Mutually exclusive with `CustomTitleName`. | | `CustomTitleName` | string | optional | Name of the customer's custom title, as configured in the chain's guest titles. Mutually exclusive with `Title` – a customer has either a standard title or a custom title. Unlike `Title`, the value is not localized; display it as returned. | | `Sex` | [Sex](#sex) | optional | Sex of the customer. | | `FirstName` | string | optional | First name of the customer. | | `LastName` | string | required | Last name of the customer. | | `SecondLastName` | string | optional | Second last name of the customer. | | `NationalityCode` | string | optional | ISO 3166-1 code of the [Country](/connector-api/operations/countries#country). | | `PreferredLanguageCode` | string | optional | Language and culture code of the customer's preferred language, according to their profile. For example: `en-GB`, `fr-CA`. | | `LanguageCode` | string | optional | Language and culture code of the customer's language, based on multiple sources. These sources include the preferred language specified in internal data based on previous bookings, and the preferred language of the customer specified in their profile. If neither of these sources are present, we use the native language based on the customer's nationality. The format is, for example, `en-US` or `fr-FR`. | | `BirthDate` | string | optional | Date of birth in ISO 8601 format. | | `BirthCountryCode` | string | optional | ISO 3166-1 alpha-2 code of the birth country. | | `BirthCountrySubdivisionCode` | string | optional | ISO 3166-2 code of the administrative division, e.g. ES-C. | | `BirthPlace` | string | optional | Place of birth. | | `Occupation` | string | optional | Occupation of the customer. | | `Email` | string | optional | Email address of the customer. | | `HasOtaEmail` | boolean | required | Whether the customer's email address is a temporary email address from an OTA. For more details, see the [product documentation](https://help.mews.com/s/article/how-to-maintain-ota-guest-profiles-with-verified-email-addresses-obtained-from-the-guest-portal). | | `Phone` | string | optional | Phone number of the customer (possibly mobile). | | `TaxIdentificationNumber` | string | optional | Tax identification number of the customer. | | `LoyaltyCode` | string | optional | Loyalty code of the customer. | | `AccountingCode` | string | optional | Accounting code of the customer. | | `BillingCode` | string | optional | Billing code of the customer. | | `Notes` | string | optional | Internal notes about the customer. | | `CarRegistrationNumber` | string | optional, max length 255 characters | Registration number of the customer's car. | | `DietaryRequirements` | string | optional, max length 255 characters | Customer's dietary requirements, e.g. Vegan, Halal. | | `CreatedUtc` | string | required | Creation date and time of the customer in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the customer in UTC timezone in ISO 8601 format. | | `AddressId` | string | optional | Unique identifier of the `Address` of the customer. | | `Classifications` | array of [Customer classification](#customer-classification) | required | Classifications of the customer. | | `Options` | array of [Customer option](#customer-option) | required | Options of the customer. | | `ItalianDestinationCode` | string | optional | Value of Italian destination code. | | `ItalianFiscalCode` | string | optional | Value of Italian fiscal code. | | `ItalianLotteryCode` | string | optional | Italian lottery code. | | `CompanyId` | string | optional | Unique identifier of [Company](/connector-api/operations/companies#company) the customer is associated with. | | `MergeTargetId` | string | optional | Unique identifier of the account ([Customer](#customer)) to which this customer is linked. | | `IsActive` | boolean | required | Whether the customer record is still active. | | `PreferredSpaceFeatures` | array of [Resource feature classification](/connector-api/operations/resourcefeatures#resource-feature-classification) | required | A list of room preferences, such as view type, bed type, and amenities. | | `CreatorProfileId` | string | required | Unique identifier of the user who created the customer. | | `UpdaterProfileId` | string | required | Unique identifier of the user who last updated the customer. | | ~~`Passport`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`IdentityCard`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`Visa`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`DriversLicense`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`Address`~~ | [~~Address~~](/connector-api/operations/configuration#address) | ~~optional~~ | **Deprecated!** Use `AddressId` instead. | | ~~`ActivityState`~~ | ~~string~~ | ~~optional~~ | [~~Activity State~~](#activity-state) ~~of customer record, i.e. whether active or deleted.~~ **Deprecated!** Use `IsActive` instead. | #### Title Type of the title prefix of the customer. Note that the value should not be used as-is, but localized. For example, the value `Misses` should be displayed as `Mrs.` in English and `Fr.` in German. * `Mister` - Mr. * `Miss` - Ms. * `Misses` - Mrs. #### Sex * `Male` * `Female` #### Identity document | Property | Type | Contract | Description | | ------------------------------- | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------ | | `Id` | string | required | Unique identifier of the document. | | `CustomerId` | string | required | Identifier of the `Customer`. | | `Type` | [Document type](/connector-api/operations/reservations#document-type) | required | Type of the document. | | `Number` | string | optional | Number of the document (e.g. passport number). | | `Expiration` | string | optional | Expiration date in ISO 8601 format. | | `Issuance` | string | optional | Date of issuance in ISO 8601 format. | | `IssuingCountryCode` | string | optional | ISO 3166-1 code of the `Country`. | | `IssuingCountrySubdivisionCode` | string | optional | Identifier of the country subdivision where the document was issued (province, state or region). | | `IssuingCity` | string | optional | City where the document was issued. | | `IdentityDocumentSupportNumber` | string | optional | Identity document support number. Only required for Spanish identity cards in Spanish hotels. | #### Customer classification * `PaymasterAccount` * `Blacklist` - Deprecated, use Blocklist instead. * `Media` * `LoyaltyProgram` * `PreviousComplaint` * `Returning` * `Staff` * `FriendOrFamily` * `TopManagement` * `Important` * `VeryImportant` * `Problematic` * `Cashlist` * `DisabledPerson` * `Military` * `Airline` * `HealthCompliant` * `InRoom` * `WaitingForRoom` * `Student` * `Blocklist` #### Customer option * `None` * `SendMarketingEmails` * `Invoiceable` * `BillAddressObjection` * `SendMarketingPostalMail` * `SendPartnerMarketingEmails` * `SendPartnerMarketingPostalMail` * `WithdrawCardConsent` * `GuestPhotoConsent` * `IdPhotosConsent` ## Get customers relationships > ### Restricted! > > This operation is currently in beta-test and as such it is subject to change. Returns relationships between customers (e.g. Spouse, Friend) for the provided unique identifiers of customers. ### Request `[PlatformAddress]/api/connector/v1/customers/getRelationships` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CustomerIds": [ "fadd5bb6-b428-45d5-94f8-fd0d89fece6d", "bccdafd1-3e44-439d-861f-341526b597a9" ], "UpdatedUtc": { "StartUtc": "2023-08-01T00:00:00Z", "EndUtc": "2023-08-30T00:00:00Z" }, "ChainIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "5fcd1933-22f2-40b9-84da-7db04cbecec2" ], "Limitation": { "Count": 100 } } ``` | 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. | | `ChainIds` | array of string | optional, max 1000 items | Unique identifiers of `Chain`. If not specified, the operation returns data for all chains within scope of the Access Token. | | `CustomerIds` | array of string | required, max 100 items | Unique identifiers of `Customer`. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which the relationship was updated. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "CustomerRelationships": [ { "CustomerId": "cbe8a32e-3eb7-4226-baf4-69455a0eeaf5", "RelatedCustomerId": "cbe8a32e-3eb7-4226-baf4-69455a0eeaf6", "Relationship": "Other", "UpdatedUtc": "2023-08-01T12:00:00Z" }, { "CustomerId": "cbe8a32e-3eb7-4226-baf4-69455a0eeaf6", "RelatedCustomerId": "cbe8a32e-3eb7-4226-baf4-69455a0eeaf5", "Relationship": "Other", "UpdatedUtc": "2023-08-01T12:00:00Z" } ], "Cursor": null } ``` | Property | Type | Contract | Description | | ----------------------- | -------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CustomerRelationships` | array of [Customer relationship](#customer-relationship) | required | The relationships for the customers. | | `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. | #### Customer relationship | Property | Type | Contract | Description | | ------------------- | --------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | `CustomerId` | string | required | Unique identifier of the customer in the relationship. | | `RelatedCustomerId` | string | required | Unique identifier of the related customer. | | `Relationship` | [Customer relationship type](#customer-relationship-type) | required | Type of relationship between the two customers (e.g. Child = the related customer is the child of this customer). | | `UpdatedUtc` | string | required | Date and time when the relationship was last updated in UTC timezone in ISO 8601 format. | #### Customer relationship type {% hint style="info" icon="circle-ellipsis" %} **Note** the list of values is not exhaustive. The API may return additional values that are not listed here. {% endhint %} * `Spouse` * `Child` * `Parent` * `OtherFamily` - Any familial relationship that doesn't fit for the options provided * `Friend` * `Colleague` * `Other` * … ## ~~Get customers open items~~ > ### Deprecated! > > This operation is [deprecated](/connector-api/deprecations). Use [Get all payments](/connector-api/operations/payments#get-all-payments) and [Get all order items](/connector-api/operations/orderitems#get-all-order-items) instead. ### Request `[PlatformAddress]/api/connector/v1/customers/getOpenItems` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CustomerIds": [ "2a1a4315-7e6f-4131-af21-402cec59b8b9" ] } ``` | 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. | | `CustomerIds` | array of string | required, max 1000 items | Unique identifiers of `Customer`. | | `Currency` | string | optional | ISO-4217 code of the [Currency](/connector-api/operations/currencies#currency) the item costs should be converted to. | ### Response ```javascript { "Customers": [ { "CustomerId": "2a1a4315-7e6f-4131-af21-402cec59b8b9", "OrderItems": [ { "Id": "35820535-b988-4d6f-80cf-ecb19cdc3e58", "AccountId": "2a1a4315-7e6f-4131-af21-402cec59b8b9", "OrderId": "6645113e-72cc-4f99-ab77-e4452911bf20", "BillId": null, "AccountingCategoryId": "d250149e-a29d-4c70-b607-a1759faf7320", "Amount": { "Currency": "GBP", "NetValue": -5, "GrossValue": -5, "TaxValues": [ { "Code": "UK-Z", "Value": 0 } ], "Breakdown": { "Items": [ { "TaxRateCode": "UK-Z", "NetValue": -5, "TaxValue": 0 } ] } }, "RevenueType": "Additional", "ConsumedUtc": "2017-04-04T15:13:39Z", "ClosedUtc": null, "AccountingState": "Open", "Data": { "Discriminator": "Rebate", "Value": { "RebatedItemId": null } } } ], "PaymentItems": [] } ] } ``` | Property | Type | Contract | Description | | ----------- | ------------------------------------------ | -------- | ------------------------------- | | `Customers` | array of [Customer items](#customer-items) | optional | The customers with their items. | #### Customer items | Property | Type | Contract | Description | | -------------- | --------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------ | | `CustomerId` | string | required | Unique identifier of the `Customer`. | | `OrderItems` | array of [Order item](/connector-api/operations/accountingitems#order-item) | required | The open order items (consumed items such as nights or products). | | `PaymentItems` | array of [Payment item](/connector-api/operations/accountingitems#payment-item) | required | The open payment items (such as cash, credit card payments or invoices). | | ~~`Items`~~ | ~~array of~~ [~~Accounting item~~](/connector-api/operations/accountingitems#accounting-item) | ~~required~~ | **Deprecated!** Use `OrderItems` and `PaymentItems` instead. | ## Add customer Adds a new customer to the system and returns details of the added customer. If a customer with the specified email already exists, and `OverwriteExisting` is set to `true`, then the existing customer profile information is overwritten and the existing customer data returned. If `OverwriteExisting` is set to `false`, an error response is returned. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/customers/add` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "Title": "Miss", "FirstName": "Thea", "LastName": "Carbone", "BirthDate": "1985-09-30", "BirthPlace": "Pescara (BI)", "Occupation": "Giornalista", "Email": "thea@quotidiano.example", "Phone": "+39 06 555 5555", "Notes": "Check-in notturno.", "CarRegistrationNumber": "AA 111AA", "TaxIdentificationNumber": "ZGNZLR17U72P554F", "Address": { "Line1": "Via Antimo 474 Piano 5", "City": "Liborio laziale", "PostalCode": "30228", "CountryCode": "IT", "CountrySubdivisionCode": "IT-65" }, "Classifications": [ "Media", "FriendOrFamily" ], "Options": [ "SendMarketingEmails" ], "ChainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "OverwriteExisting": false, "ItalianDestinationCode": "7654321", "ItalianFiscalCode": "ZGNZLR17U72P554F", "ItalianLotteryCode": "AB12345" } ``` | 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. | | `Title` | [Title](#title) | optional | Title prefix of the customer. | | `FirstName` | string | optional | First name of the customer. | | `LastName` | string | required | Last name of the customer. | | `SecondLastName` | string | optional | Second last name of the customer. | | `NationalityCode` | string | optional | ISO 3166-1 code of the `Country`. | | `PreferredLanguageCode` | string | optional | Language and culture code of the customer's preferred language, according to their profile. For example: `en-GB`, `fr-CA`. | | `Sex` | [Sex](#sex) | optional | Sex of the customer. | | `BirthDate` | string | optional | Date of birth in ISO 8601 format. | | `BirthCountryCode` | string | optional | Country of birth. | | `BirthCountrySubdivisionCode` | string | optional | Province of birth. | | `BirthPlace` | string | optional | Place of birth. | | `Occupation` | string | optional | Occupation of the customer. | | `Email` | string | optional | Email address of the customer. | | `Phone` | string | optional | Phone number of the customer (possibly mobile). | | `LoyaltyCode` | string | optional | Loyalty code of the customer. | | `Notes` | string | optional | Internal notes about the customer. | | `CarRegistrationNumber` | string | optional, max length 255 characters | Registration number of the customer's car. | | `DietaryRequirements` | string | optional, max length 255 characters | Customer's dietary requirements, e.g. Vegan, Halal. | | `TaxIdentificationNumber` | string | optional | Tax identification number of the customer. | | `CompanyId` | string | optional | Unique identifier of `Company` the customer is associated with. | | `Address` | [Address parameters](/connector-api/operations/companies#address-parameters) | optional | Address of the customer. | | `Classifications` | array of [Customer classification](#customer-classification) | optional | Classifications of the customer. | | `Options` | array of [Customer option](#customer-option) | optional | Options of the customer. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using `PortfolioAccessTokens`, ignored otherwise. | | `OverwriteExisting` | boolean | required | Whether an existing customer should be overwritten in case of duplicity. This applies only to basic personal information (`Title`, `FirstName`, `LastName`, ...). | | `ItalianDestinationCode` | string | optional | Value of Italian destination code. | | `ItalianFiscalCode` | string | optional | Value of Italian fiscal code. | | `ItalianLotteryCode` | string | optional, max length 15 characters | Value of Italian lottery code. | | ~~`IdentityCard`~~ | [~~Identity document parameters~~](#identity-document-parameters) | ~~optional~~ | ~~Identity card details of the customer.~~ **Deprecated!** Use [Add identity documents](/connector-api/operations/identitydocuments#add-identity-documents) to add document. | | ~~`Passport`~~ | [~~Identity document parameters~~](#identity-document-parameters) | ~~optional~~ | ~~Passport details of the customer.~~ **Deprecated!** Use [Add identity documents](/connector-api/operations/identitydocuments#add-identity-documents) to add document. | | ~~`Visa`~~ | [~~Identity document parameters~~](#identity-document-parameters) | ~~optional~~ | ~~Visa details of the customer.~~ **Deprecated!** Use [Add identity documents](/connector-api/operations/identitydocuments#add-identity-documents) to add document. | | ~~`DriversLicense`~~ | [~~Identity document parameters~~](#identity-document-parameters) | ~~optional~~ | ~~Drivers license details of the customer.~~ **Deprecated!** Use [Add identity documents](/connector-api/operations/identitydocuments#add-identity-documents) to add document. | #### Sex * `Male` * `Female` #### Identity document parameters | Property | Type | Contract | Description | | ------------------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------ | | `Number` | string | optional | Number of the document (e.g. passport number). | | `Expiration` | string | optional | Expiration date in ISO 8601 format. | | `Issuance` | string | optional | Date of issuance in ISO 8601 format. | | `IssuingCountryCode` | string | optional | ISO 3166-1 code of the `Country`. | | `IssuingCountrySubdivisionCode` | string | optional | Identifier of the country subdivision where the document was issued (province, state or region). | | `IssuingCity` | string | optional | City from which document issued | #### Customer option * `SendMarketingEmails` * `Invoiceable` * `BillAddressObjection` * `SendMarketingPostalMail` * `SendPartnerMarketingEmails` * `SendPartnerMarketingPostalMail` * `WithdrawCardConsent` * `GuestPhotoConsent` - Whether to ask for consent to take a guest photo. * `IdPhotosConsent` - Whether to ask for consent to take identity document photos. ### Response ```javascript { "Id": "99b4f0af-9558-463b-8452-07a9bc414708", "ChainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Number": "390881", "Title": "Miss", "CustomTitleName": null, "Sex": null, "FirstName": "Thea", "LastName": "Carbone", "SecondLastName": null, "NationalityCode": null, "PreferredLanguageCode": null, "LanguageCode": null, "BirthDate": "1985-09-30", "BirthCountryCode": null, "BirthCountrySubdivisionCode": null, "BirthPlace": "Pescara (BI)", "Occupation": "Giornalista", "Email": "thea@quotidiano.example", "HasOtaEmail": false, "Phone": "+39 06 555 5555", "TaxIdentificationNumber": "ZGNZLR17U72P554F", "LoyaltyCode": null, "AccountingCode": null, "BillingCode": null, "Notes": "Check-in notturno.", "CarRegistrationNumber": "AA 111AA", "DietaryRequirements": null, "CreatedUtc": "2024-09-17T12:22:33Z", "UpdatedUtc": "2024-10-12T09:45:00Z", "Passport": null, "IdentityCard": null, "Visa": null, "DriversLicense": null, "Address": { "Id": "81f62f08-26d5-408f-9b0d-d030957dc799", "Line1": "Via Antimo 474 Piano 5", "Line2": null, "City": "Liborio laziale", "PostalCode": "30228", "CountryCode": "IT", "CountrySubdivisionCode": "IT-65", "Latitude": 28.56333, "Longitude": -121.243143 }, "AddressId": "81f62f08-26d5-408f-9b0d-d030957dc799", "Classifications": [ "Media", "FriendOrFamily" ], "Options": [], "ItalianDestinationCode": "7654321", "ItalianFiscalCode": "ZGNZLR17U72P554F", "ItalianLotteryCode": "AB12345", "CompanyId": "f3b4f0af-9558-463b-8452-07a9bc414708", "MergeTargetId": null, "ActivityState": null, "IsActive": true, "PreferredSpaceFeatures": [ "LowerBed" ], "CreatorProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf", "UpdaterProfileId": "122fc063-ec6e-4198-b8db-6b168a59ffae" } ``` | Property | Type | Contract | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the customer. | | `ChainId` | string | required | Unique identifier of the chain. | | `Number` | string | required, max length 19 characters | Unique number of the customer (max 19 digits). | | `Title` | [Title](#title) | optional | Title of the customer. Mutually exclusive with `CustomTitleName`. | | `CustomTitleName` | string | optional | Name of the customer's custom title, as configured in the chain's guest titles. Mutually exclusive with `Title` – a customer has either a standard title or a custom title. Unlike `Title`, the value is not localized; display it as returned. | | `Sex` | [Sex](#sex) | optional | Sex of the customer. | | `FirstName` | string | optional | First name of the customer. | | `LastName` | string | required | Last name of the customer. | | `SecondLastName` | string | optional | Second last name of the customer. | | `NationalityCode` | string | optional | ISO 3166-1 code of the [Country](/connector-api/operations/countries#country). | | `PreferredLanguageCode` | string | optional | Language and culture code of the customer's preferred language, according to their profile. For example: `en-GB`, `fr-CA`. | | `LanguageCode` | string | optional | Language and culture code of the customer's language, based on multiple sources. These sources include the preferred language specified in internal data based on previous bookings, and the preferred language of the customer specified in their profile. If neither of these sources are present, we use the native language based on the customer's nationality. The format is, for example, `en-US` or `fr-FR`. | | `BirthDate` | string | optional | Date of birth in ISO 8601 format. | | `BirthCountryCode` | string | optional | ISO 3166-1 alpha-2 code of the birth country. | | `BirthCountrySubdivisionCode` | string | optional | ISO 3166-2 code of the administrative division, e.g. ES-C. | | `BirthPlace` | string | optional | Place of birth. | | `Occupation` | string | optional | Occupation of the customer. | | `Email` | string | optional | Email address of the customer. | | `HasOtaEmail` | boolean | required | Whether the customer's email address is a temporary email address from an OTA. For more details, see the [product documentation](https://help.mews.com/s/article/how-to-maintain-ota-guest-profiles-with-verified-email-addresses-obtained-from-the-guest-portal). | | `Phone` | string | optional | Phone number of the customer (possibly mobile). | | `TaxIdentificationNumber` | string | optional | Tax identification number of the customer. | | `LoyaltyCode` | string | optional | Loyalty code of the customer. | | `AccountingCode` | string | optional | Accounting code of the customer. | | `BillingCode` | string | optional | Billing code of the customer. | | `Notes` | string | optional | Internal notes about the customer. | | `CarRegistrationNumber` | string | optional, max length 255 characters | Registration number of the customer's car. | | `DietaryRequirements` | string | optional, max length 255 characters | Customer's dietary requirements, e.g. Vegan, Halal. | | `CreatedUtc` | string | required | Creation date and time of the customer in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the customer in UTC timezone in ISO 8601 format. | | `AddressId` | string | optional | Unique identifier of the `Address` of the customer. | | `Classifications` | array of [Customer classification](#customer-classification) | required | Classifications of the customer. | | `Options` | array of [Customer option](#customer-option) | required | Options of the customer. | | `ItalianDestinationCode` | string | optional | Value of Italian destination code. | | `ItalianFiscalCode` | string | optional | Value of Italian fiscal code. | | `ItalianLotteryCode` | string | optional | Italian lottery code. | | `CompanyId` | string | optional | Unique identifier of [Company](/connector-api/operations/companies#company) the customer is associated with. | | `MergeTargetId` | string | optional | Unique identifier of the account ([Customer](#customer)) to which this customer is linked. | | `IsActive` | boolean | required | Whether the customer record is still active. | | `PreferredSpaceFeatures` | array of [Resource feature classification](/connector-api/operations/resourcefeatures#resource-feature-classification) | required | A list of room preferences, such as view type, bed type, and amenities. | | `CreatorProfileId` | string | required | Unique identifier of the user who created the customer. | | `UpdaterProfileId` | string | required | Unique identifier of the user who last updated the customer. | | ~~`Passport`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`IdentityCard`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`Visa`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`DriversLicense`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`Address`~~ | [~~Address~~](/connector-api/operations/configuration#address) | ~~optional~~ | **Deprecated!** Use `AddressId` instead. | | ~~`ActivityState`~~ | ~~string~~ | ~~optional~~ | [~~Activity State~~](#activity-state) ~~of customer record, i.e. whether active or deleted.~~ **Deprecated!** Use `IsActive` instead. | ## Update customer Updates personal information of a customer. Note that if any of the fields is left blank, it won't clear the field in Mews. The field will be left intact. In case of email update, the email will change in Mews only if there is no other customer profile in the hotel with such email. Otherwise an error response is returned. Note this operation supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/customers/update` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "ChainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "CustomerId": "99b4f0af-9558-463b-8452-07a9bc414708", "Title": "Miss", "FirstName": "Thea", "LastName": "Carbone", "BirthDate": "1985-09-30", "BirthPlace": "Pescara (BI)", "Occupation": "Giornalista", "Email": "thea@quotidiano.example", "Phone": "+39 06 555 5555", "Notes": "Check-in notturno.", "CarRegistrationNumber": "AA 111AA", "TaxIdentificationNumber": "ZGNZLR17U72P554F", "CompanyId": "f3b4f0af-9558-463b-8452-07a9bc414708", "Address": { "Line1": "Via Antimo 474 Piano 5", "City": "Liborio laziale", "PostalCode": "30228", "CountryCode": "IT", "CountrySubdivisionCode": "IT-65" }, "Classifications": [ "Media", "FriendOrFamily" ], "Options": [ "SendMarketingEmails" ], "ItalianDestinationCode": { "Value": "7654321" }, "ItalianFiscalCode": { "Value": "ZGNZLR17U72P554F" }, "ItalianLotteryCode": { "Value": "AB12345" } } ``` | 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using `PortfolioAccessTokens`, ignored otherwise. | | `CustomerId` | string | required | Unique identifier of the `Customer` to be updated. | | `Title` | [Title](#title) | optional | New title. | | `FirstName` | string | optional | New first name. | | `LastName` | string | optional | New last name. | | `SecondLastName` | string | optional | New second last name. | | `NationalityCode` | string | optional | New nationality code as ISO 3166-1 code of the `Country`. | | `PreferredLanguageCode` | string | optional | Language and culture code of the customer's preferred language, according to their profile. For example: `en-GB`, `fr-CA`. | | `Sex` | [Sex](#sex) | optional | Sex of the customer. | | `BirthDate` | string | optional | New birth date in ISO 8601 format. | | `BirthCountryCode` | string | optional | Country of birth. | | `BirthCountrySubdivisionCode` | string | optional | Province of birth. | | `BirthPlace` | string | optional | New birth place. | | `Occupation` | string | optional | Occupation of the customer. | | `Email` | string | optional | New email address. | | `Phone` | string | optional | New phone number. | | `LoyaltyCode` | string | optional | Loyalty code of the customer. | | `Notes` | string | optional | Internal notes about the customer. Old value will be overwritten. | | `CarRegistrationNumber` | string | optional, max length 255 characters | New registration number of the customer's car. | | `DietaryRequirements` | string | optional, max length 255 characters | Customer's dietary requirements, e.g. Vegan, Halal. | | `TaxIdentificationNumber` | string | optional | New tax identification number of the customer. | | `CompanyId` | string | optional | Unique identifier of `Company` the customer is associated with. | | `Address` | [Address parameters](/connector-api/operations/companies#address-parameters) | optional | New address details. | | `Classifications` | array of [Customer classification](#customer-classification) | optional | New classifications of the customer. | | `Options` | array of [Customer option](#customer-option) | optional | Options of the customer. | | `ItalianDestinationCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | New Italian destination code of customer. | | `ItalianFiscalCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional | New Italian fiscal code of customer. | | `ItalianLotteryCode` | [String update value](/connector-api/operations/_objects#string-update-value) | optional, max length 15 characters | New Italian lottery code of customer. | | ~~`IdentityCard`~~ | [~~Identity document parameters~~](#identity-document-parameters) | ~~optional~~ | ~~New identity card details.~~ **Deprecated!** Use [Update identity documents](/connector-api/operations/identitydocuments#update-identity-documents) to update document. | | ~~`Passport`~~ | [~~Identity document parameters~~](#identity-document-parameters) | ~~optional~~ | ~~New passport details.~~ **Deprecated!** Use [Update identity documents](/connector-api/operations/identitydocuments#update-identity-documents) to update document. | | ~~`Visa`~~ | [~~Identity document parameters~~](#identity-document-parameters) | ~~optional~~ | ~~New visa details.~~ **Deprecated!** Use [Update identity documents](/connector-api/operations/identitydocuments#update-identity-documents) to update document. | | ~~`DriversLicense`~~ | [~~Identity document parameters~~](#identity-document-parameters) | ~~optional~~ | ~~New drivers license details.~~ **Deprecated!** Use [Update identity documents](/connector-api/operations/identitydocuments#update-identity-documents) to update document. | ### Response ```javascript { "Id": "99b4f0af-9558-463b-8452-07a9bc414708", "ChainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Number": "390881", "Title": "Miss", "CustomTitleName": null, "Sex": null, "FirstName": "Thea", "LastName": "Carbone", "SecondLastName": null, "NationalityCode": null, "PreferredLanguageCode": null, "LanguageCode": null, "BirthDate": "1985-09-30", "BirthCountryCode": null, "BirthCountrySubdivisionCode": null, "BirthPlace": "Pescara (BI)", "Occupation": "Giornalista", "Email": "thea@quotidiano.example", "HasOtaEmail": false, "Phone": "+39 06 555 5555", "TaxIdentificationNumber": "ZGNZLR17U72P554F", "LoyaltyCode": null, "AccountingCode": null, "BillingCode": null, "Notes": "Check-in notturno.", "CarRegistrationNumber": "AA 111AA", "DietaryRequirements": null, "CreatedUtc": "2024-09-17T12:22:33Z", "UpdatedUtc": "2024-10-12T09:45:00Z", "Passport": null, "IdentityCard": null, "Visa": null, "DriversLicense": null, "Address": { "Id": "81f62f08-26d5-408f-9b0d-d030957dc799", "Line1": "Via Antimo 474 Piano 5", "Line2": null, "City": "Liborio laziale", "PostalCode": "30228", "CountryCode": "IT", "CountrySubdivisionCode": "IT-65", "Latitude": 28.56333, "Longitude": -121.243143 }, "AddressId": "81f62f08-26d5-408f-9b0d-d030957dc799", "Classifications": [ "Media", "FriendOrFamily" ], "Options": [], "ItalianDestinationCode": "7654321", "ItalianFiscalCode": "ZGNZLR17U72P554F", "ItalianLotteryCode": "AB12345", "CompanyId": "f3b4f0af-9558-463b-8452-07a9bc414708", "MergeTargetId": null, "ActivityState": null, "IsActive": true, "PreferredSpaceFeatures": [ "LowerBed" ], "CreatorProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf", "UpdaterProfileId": "122fc063-ec6e-4198-b8db-6b168a59ffae" } ``` | Property | Type | Contract | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the customer. | | `ChainId` | string | required | Unique identifier of the chain. | | `Number` | string | required, max length 19 characters | Unique number of the customer (max 19 digits). | | `Title` | [Title](#title) | optional | Title of the customer. Mutually exclusive with `CustomTitleName`. | | `CustomTitleName` | string | optional | Name of the customer's custom title, as configured in the chain's guest titles. Mutually exclusive with `Title` – a customer has either a standard title or a custom title. Unlike `Title`, the value is not localized; display it as returned. | | `Sex` | [Sex](#sex) | optional | Sex of the customer. | | `FirstName` | string | optional | First name of the customer. | | `LastName` | string | required | Last name of the customer. | | `SecondLastName` | string | optional | Second last name of the customer. | | `NationalityCode` | string | optional | ISO 3166-1 code of the [Country](/connector-api/operations/countries#country). | | `PreferredLanguageCode` | string | optional | Language and culture code of the customer's preferred language, according to their profile. For example: `en-GB`, `fr-CA`. | | `LanguageCode` | string | optional | Language and culture code of the customer's language, based on multiple sources. These sources include the preferred language specified in internal data based on previous bookings, and the preferred language of the customer specified in their profile. If neither of these sources are present, we use the native language based on the customer's nationality. The format is, for example, `en-US` or `fr-FR`. | | `BirthDate` | string | optional | Date of birth in ISO 8601 format. | | `BirthCountryCode` | string | optional | ISO 3166-1 alpha-2 code of the birth country. | | `BirthCountrySubdivisionCode` | string | optional | ISO 3166-2 code of the administrative division, e.g. ES-C. | | `BirthPlace` | string | optional | Place of birth. | | `Occupation` | string | optional | Occupation of the customer. | | `Email` | string | optional | Email address of the customer. | | `HasOtaEmail` | boolean | required | Whether the customer's email address is a temporary email address from an OTA. For more details, see the [product documentation](https://help.mews.com/s/article/how-to-maintain-ota-guest-profiles-with-verified-email-addresses-obtained-from-the-guest-portal). | | `Phone` | string | optional | Phone number of the customer (possibly mobile). | | `TaxIdentificationNumber` | string | optional | Tax identification number of the customer. | | `LoyaltyCode` | string | optional | Loyalty code of the customer. | | `AccountingCode` | string | optional | Accounting code of the customer. | | `BillingCode` | string | optional | Billing code of the customer. | | `Notes` | string | optional | Internal notes about the customer. | | `CarRegistrationNumber` | string | optional, max length 255 characters | Registration number of the customer's car. | | `DietaryRequirements` | string | optional, max length 255 characters | Customer's dietary requirements, e.g. Vegan, Halal. | | `CreatedUtc` | string | required | Creation date and time of the customer in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the customer in UTC timezone in ISO 8601 format. | | `AddressId` | string | optional | Unique identifier of the `Address` of the customer. | | `Classifications` | array of [Customer classification](#customer-classification) | required | Classifications of the customer. | | `Options` | array of [Customer option](#customer-option) | required | Options of the customer. | | `ItalianDestinationCode` | string | optional | Value of Italian destination code. | | `ItalianFiscalCode` | string | optional | Value of Italian fiscal code. | | `ItalianLotteryCode` | string | optional | Italian lottery code. | | `CompanyId` | string | optional | Unique identifier of [Company](/connector-api/operations/companies#company) the customer is associated with. | | `MergeTargetId` | string | optional | Unique identifier of the account ([Customer](#customer)) to which this customer is linked. | | `IsActive` | boolean | required | Whether the customer record is still active. | | `PreferredSpaceFeatures` | array of [Resource feature classification](/connector-api/operations/resourcefeatures#resource-feature-classification) | required | A list of room preferences, such as view type, bed type, and amenities. | | `CreatorProfileId` | string | required | Unique identifier of the user who created the customer. | | `UpdaterProfileId` | string | required | Unique identifier of the user who last updated the customer. | | ~~`Passport`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`IdentityCard`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`Visa`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`DriversLicense`~~ | [~~Identity document~~](#identity-document) | ~~optional~~ | **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | | ~~`Address`~~ | [~~Address~~](/connector-api/operations/configuration#address) | ~~optional~~ | **Deprecated!** Use `AddressId` instead. | | ~~`ActivityState`~~ | ~~string~~ | ~~optional~~ | [~~Activity State~~](#activity-state) ~~of customer record, i.e. whether active or deleted.~~ **Deprecated!** Use `IsActive` instead. | ## Add customer file Attaches the specified file to the customer profile. Allowed MIME types: `application/pdf`, `image/bmp`, `image/gif`, `image/jpeg`, `image/png`, `image/tiff`. Note this operation supports [Portfolio Access Tokens](https://github.com/MewsSystems/open-api-docs/tree/main/connector-api/guidelines/multi-property.md). ### Request `[PlatformAddress]/api/connector/v1/customers/addFile` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "CustomerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Name": "document.pdf", "Type": "application/pdf", "Data": "JVBERi0xLjAKMSAwIG9iajw8L1BhZ2VzIDIgMCBSPj5lbmRvYmogMiAwIG9iajw8L0tpZHNbMyAwIFJdL0NvdW50IDE+PmVuZG9iaiAzIDAgb2JqPDwvTWVkaWFCb3hbMCAwIDMgM10+PmVuZG9iagp0cmFpbGVyPDwvUm9vdCAxIDAgUj4+Cg==", "ChainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | 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. | | `ChainId` | string | optional | Unique identifier of the chain. Required when using [Portfolio Access Tokens](/connector-api/concepts/multi-property), ignored otherwise. | | `CustomerId` | string | required | Unique identifier of the [Customer](#customer). | | `Name` | string | required | Name of the file. | | `Type` | string | required | MIME type of the file (e.g. `application/pdf`). | | `Data` | string | required | Base64-encoded data of the file. | ### Response ```javascript { "FileId": "f039f5b4-ff18-4510-9086-92b14a68ed78" } ``` | Property | Type | Contract | Description | | -------- | ------ | -------- | --------------------------------------- | | `FileId` | string | required | Unique identifier of the uploaded file. | ## Search customers Searches for customers that are active at the moment in the enterprise (e.g. companions of checked-in reservations or paymasters). ### Request `[PlatformAddress]/api/connector/v1/customers/search` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "Name": "Smith", "ResourceId": null, "Extent": { "Customers": true, "Documents": false, "Addresses": false } } ``` | 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. | | `Name` | string | optional | Name to search by (applies to first name, last name, and full name). | | `ResourceId` | string | optional | Identifier of [Resource](/connector-api/operations/resources#resource) to search by (members of reservation assigned there will be returned). | | `Extent` | [Customer extent](#customer-extent) | optional | Extent of data to be returned. | ### Response ```javascript { "Customers": [ { "Customer": { "Id": "fadd5bb6-b428-45d5-94f8-fd0d89fece6d", "ChainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "Number": "12345", "Title": "Mister", "CustomTitleName": null, "Sex": "Male", "FirstName": "John", "LastName": "Smith", "SecondLastName": "Williams", "NationalityCode": "US", "PreferredLanguageCode": "en-GB", "LanguageCode": "en-US", "BirthDate": "1983-12-31", "BirthCountryCode": null, "BirthCountrySubdivisionCode": null, "BirthPlace": "New York City, NY", "Occupation": "Carpenter", "Email": "j.smith@example.com", "HasOtaEmail": false, "Phone": "00420123456789", "TaxIdentificationNumber": "123456789", "LoyaltyCode": "LL810213", "AccountingCode": "AC123", "BillingCode": null, "Notes": "", "CarRegistrationNumber": "1A2 3456", "DietaryRequirements": null, "CreatedUtc": "2018-01-01T00:00:00Z", "UpdatedUtc": "2018-01-02T00:00:00Z", "Passport": null, "IdentityCard": null, "Visa": null, "DriversLicense": null, "Address": { "Id": "f8495413-bf49-45dd-843c-44be7f365569", "Line1": "Somerford Road Hello House/135", "Line2": null, "City": "Christchurch", "PostalCode": "BH23 3PY", "CountryCode": "GB", "CountrySubdivisionCode": "GB-ENG", "Latitude": null, "Longitude": null }, "AddressId": "f8495413-bf49-45dd-843c-44be7f365569", "Classifications": [ "Returning" ], "Options": [ "SendMarketingEmails" ], "ItalianDestinationCode": null, "ItalianFiscalCode": null, "ItalianLotteryCode": null, "CompanyId": "c6f5c82d-621a-4c8a-903b-1b0a9a23b71f", "MergeTargetId": null, "ActivityState": "Active", "IsActive": true, "PreferredSpaceFeatures": [ "OceanView" ], "CreatorProfileId": "3cd637ef-4728-47f9-8fb1-afb900c9cdcf", "UpdaterProfileId": "122fc063-ec6e-4198-b8db-6b168a59ffae" }, "Reservation": null } ], "Documents": null } ``` | Property | Type | Contract | Description | | --------------- | ---------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Customers` | array of [Customer search result](#customer-search-result) | required | The customer search results. | | ~~`Documents`~~ | ~~array of~~ [~~Identity document~~](#identity-document) | ~~optional~~ | ~~The identity documents of customers.~~ **Deprecated!** Use [Get all identity documents](/connector-api/operations/identitydocuments#get-all-identity-documents) to fetch identity documents. | #### Customer search result | Property | Type | Contract | Description | | ------------- | ------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------- | | `Customer` | [Customer](#customer) | required | The found customer. | | `Reservation` | [Reservation (ver 2017-04-12)](/connector-api/operations/reservations#reservation-ver-2017-04-12) | optional | Reservation of the customer in case they are currently staying in the property. | ## ~~Merge customers~~ > ### Deprecated! > > This operation is [deprecated](/connector-api/deprecations). Use [Merge accounts](/connector-api/operations/accounts#merge-accounts) instead. ### Request `[PlatformAddress]/api/connector/v1/customers/merge` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "SourceCustomerId": "e11801ff-4148-4010-87f3-0d111e2893e3", "TargetCustomerId": "35d4b117-4e60-44a3-9580-c582117eff98" } ``` | 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. | | `SourceCustomerId` | string | required | Unique identifier of the source [Customer](#customer). | | `TargetCustomerId` | string | required | Unique identifier of the target [Customer](#customer). | ### Response ```javascript {} ``` # Departments ## Get all departments Returns all departments of an enterprise associated with the connector integration. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/departments/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "DepartmentIds": [ "98776d06-60e4-495f-82f1-95ab2f644d63", "915fbb82-de35-48a0-9e9b-f4a7eac711bb" ], "UpdatedUtc": { "StartUtc": "2023-10-01T00:00:00Z", "EndUtc": "2023-10-31T00:00:00Z" }, "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. | | `DepartmentIds` | array of string | optional, max 1000 items | Unique identifiers of [Department](#department). | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which `Department` was updated. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned and optional Cursor for the starting point of data. | ### Response ```javascript { "Departments": [ { "Id": "98776d06-60e4-495f-82f1-95ab2f644d63", "EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "IsActive": true, "Name": "Sales", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z" }, { "Id": "915fbb82-de35-48a0-9e9b-f4a7eac711bb", "EnterpriseId": "4d0201db-36f5-428b-8d11-4f0a65e960cc", "IsActive": true, "Name": "Housekeeping", "CreatedUtc": "2023-10-01T11:48:57Z", "UpdatedUtc": "2023-10-28T11:48:57Z" } ], "Cursor": "915fbb82-de35-48a0-9e9b-f4a7eac711bb" } ``` | Property | Type | Contract | Description | | ------------- | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Departments` | array of [Department](#department) | required | The departments of 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. | #### Department | Property | Type | Contract | Description | | -------------- | ------- | -------- | ---------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the department. | | `EnterpriseId` | string | required | Unique identifier of the [Enterprise](/connector-api/operations/enterprises#enterprise). | | `IsActive` | boolean | required | Whether the department is still active. | | `Name` | string | required | Name of the department. | | `CreatedUtc` | string | required | Creation date and time of the department in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the department in UTC timezone in ISO 8601 format. | # Devices ## Get all devices Returns all devices in the enterprise. ### Request `[PlatformAddress]/api/connector/v1/devices/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0" } ``` | 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. | ### Response ```javascript { "Devices": [ { "Id": "d14efcfd-75b9-4bd3-9f10-5657a01f860a", "Name": "Key cutter 1", "Type": "KeyCutter" } ] } ``` | Property | Type | Contract | Description | | --------- | -------------------------- | -------- | ------------ | | `Devices` | array of [Device](#device) | required | The devices. | #### Device | Property | Type | Contract | Description | | ------------ | --------------------------- | -------- | ------------------------------------------ | | `Id` | string | required | Unique identifier of the device. | | `Type` | [Device type](#device-type) | required | Type of the device. | | `Name` | string | required | Name of the device. | | `Identifier` | string | optional | Device identifier (for internal purposes). | #### Device type * `Printer` - [Printer command data](/connector-api/operations/commands#printer-command-data) * `PaymentTerminal` - [Payment terminal command data](/connector-api/operations/commands#payment-terminal-command-data) * `KeyCutter` - [Key cutter command data](/connector-api/operations/commands#key-cutter-command-data) * `FiscalMachine` - [Fiscal machine command data](/connector-api/operations/commands#fiscal-machine-command-data) * `PassportScanner` - [Passport scanner command data](/connector-api/operations/commands#passport-scanner-command-data) # Enterprises ## Get all enterprises Returns all enterprises within scope of the `Access Token`, optionally filtered by enterprise identifiers and external identifiers. Note this operation uses [Pagination](/connector-api/guidelines/pagination) and supports [Portfolio Access Tokens](/connector-api/concepts/multi-property). ### Request `[PlatformAddress]/api/connector/v1/enterprises/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0", "EnterpriseIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "4d0201db-36f5-428b-8d11-4f0a65e960cc" ], "ExternalIdentifiers": [ "Enterprise2023" ], "LinkedUtc": { "StartUtc": "2023-06-01T00:00:00Z", "EndUtc": "2023-06-06T00:00:00Z" }, "UpdatedUtc": { "StartUtc": "2023-10-01T00:00:00Z", "EndUtc": "2023-10-31T00:00:00Z" }, "Limitation": { "Count": 100, "Cursor": "4d0201db-36f5-428b-8d11-4f0a65e960cc" } } ``` | 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](#enterprise). If not specified, all enterprises within scope of the Access Token are returned. | | `ExternalIdentifiers` | array of string | optional, max 1000 items | Identifiers of the [Enterprise](#enterprise) from external system. | | `LinkedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which enterprises were linked. | | `UpdatedUtc` | [Time interval](/connector-api/operations/_objects#time-interval) | optional, max length 3 months | Interval in which enterprises were updated. | | `Limitation` | [Limitation](/connector-api/guidelines/pagination#limitation) | required | Limitation on the quantity of data returned. | ### Response ```javascript { "Enterprises": [ { "LinkedUtc": "2023-06-01T00:00:00Z", "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "ExternalIdentifier": "Enterprise2023", "HoldingKey": "CA123", "ChainId": "2f6be44e-9881-4b12-aefe-afce011a9d67", "ChainName": "Connector API Chain", "CreatedUtc": "2022-03-23T17:12:06Z", "UpdatedUtc": "2022-03-23T17:12:06Z", "Name": "Sample Portfolio Hotel", "ShortName": null, "TimeZoneIdentifier": "Europe/Budapest", "LegalEnvironmentCode": "DE-2020-1", "AccommodationEnvironmentCode": "DE", "AccountingEnvironmentCode": "DE", "TaxEnvironmentCode": "DE-2020-1", "DefaultLanguageCode": "en-US", "EditableHistoryInterval": null, "AccountingEditableHistoryInterval": "P0M7DT0H0M0S", "OperationalEditableHistoryInterval": "P0M5DT0H0M0S", "BusinessDayClosingOffset": null, "WebsiteUrl": "https://www.sample-portfolio-hotel-10004.com/", "Email": "email@sample-portfolio-hotel.com", "Phone": "(555) 555-1234", "LogoImageId": null, "CoverImageId": null, "Pricing": "Gross", "TaxPrecision": 2, "AddressId": "31c505e9-9858-4d2f-9eab-afce011c4f47", "Address": { "Id": "8c2c4371-5d42-40a9-b551-ab0b00d75076", "Line1": "I.P. Pavlova 5", "Line2": null, "City": "Prague", "PostalCode": "1200", "CountryCode": "CZ", "CountrySubdivisionCode": null, "Latitude": 14.429645, "Longitude": 50.075181 }, "GroupNames": [ "Sample Group Name" ], "Subscription": { "TaxIdentifier": "123456789 RC 0001" } } ], "Cursor": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` | Property | Type | Contract | Description | | ------------- | ---------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Enterprises` | array of [Enterprise](#enterprise) | required | The filtered enterprises. | | `Cursor` | string | optional | Unique identifier of the last and hence oldest enterprise returned. This can be used in [Limitation](/connector-api/guidelines/pagination#limitation) in a subsequent request to fetch the next batch of older enterprises. | #### Enterprise | Property | Type | Contract | Description | | ------------------------------------ | ---------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the enterprise. | | `ExternalIdentifier` | string | optional, max length 255 characters | Identifier of the enterprise from external system. | | `HoldingKey` | string | optional, max length 255 characters | Identifies an enterprise in the external system of a holding company. The holding company may administer multiple portfolios. | | `ChainId` | string | required | Unique identifier of the chain to which the enterprise belongs. | | `ChainName` | string | required | Name of the `Chain` to which the enterprise belongs. | | `CreatedUtc` | string | required | Creation date and time of the enterprise in UTC timezone in ISO 8601 format. | | `UpdatedUtc` | string | required | Last update date and time of the enterprise in UTC timezone in ISO 8601 format. | | `Name` | string | required | Name of the enterprise. | | `ShortName` | string | optional, max length 11 characters | Short name of the enterprise used in Manager Report exports. | | `TimeZoneIdentifier` | string | required | IANA timezone identifier of the enterprise. | | `LegalEnvironmentCode` | string | required | Unique identifier of the legal environment where the enterprise resides. | | `AccommodationEnvironmentCode` | string | required | Unique code of the accommodation environment where the enterprise resides. | | `AccountingEnvironmentCode` | string | required | Unique code of the accounting environment where the enterprise resides. | | `TaxEnvironmentCode` | string | required | Unique code of the tax environment where the enterprise resides. | | `DefaultLanguageCode` | string | required | Language-culture codes of the enterprise default `Language`. | | `AccountingEditableHistoryInterval` | string | required | Editable history interval for accounting data in ISO 8601 duration format. | | `OperationalEditableHistoryInterval` | string | required | Editable history interval for operational data in ISO 8601 duration format. | | `BusinessDayClosingOffset` | string | optional | The offset value for the business day closing time, in ISO 8601 duration format. | | `WebsiteUrl` | string | optional | URL of the enterprise website. | | `Email` | string | optional | Email address of the enterprise. | | `Phone` | string | optional | Phone number of the enterprise. | | `LogoImageId` | string | optional | Unique identifier of the `Image` of the enterprise logo. | | `CoverImageId` | string | optional | Unique identifier of the `Image` of the enterprise cover. | | `Pricing` | [Pricing](/connector-api/operations/configuration#pricing) | required | Pricing of the enterprise. | | `TaxPrecision` | integer | optional | Tax precision used for financial calculations in the enterprise. If `null`, `Currency` precision is used. | | `AddressId` | string | required | Unique identifier of the `Address` of the enterprise. | | `Address` | [Address](/connector-api/operations/configuration#address) | required | Address of the enterprise. | | `GroupNames` | array of string | required | A list of the group names of the enterprise. | | `Subscription` | [Enterprise subscription](#enterprise-subscription) | required | Subscription information of the enterprise. | | `LinkedUtc` | string | required | Date and time when enterprise was added to the portfolio in UTC timezone in ISO 8601 format. | | ~~`EditableHistoryInterval`~~ | ~~string~~ | ~~required~~ | **Deprecated!** Use `AccountingEditableHistoryInterval` and `OperationalEditableHistoryInterval` instead. | #### Enterprise subscription | Property | Type | Contract | Description | | --------------- | ------ | -------- | ----------------------------------- | | `TaxIdentifier` | string | optional | Tax identifier of the `Enterprise`. | # Exchange rates ## Get all exchange rates Returns all available exchange rates among currencies of the [Enterprise](/connector-api/operations/configuration#enterprise). ### Request `[PlatformAddress]/api/connector/v1/exchangeRates/getAll` ```javascript { "ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D", "AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D", "Client": "Sample Client 1.0.0" } ``` | 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. | | `Ids` | array of string | optional | Unique identifiers of the Exchange Rates. If not specified, the operation returns all exchange rates. | | `EnterpriseIds` | array of string | optional | Unique identifiers of the [Enterprises](/connector-api/operations/configuration#enterprise). If not specified, the operation returns the exchange rates for all enterprises within scope of the Access Token. | ### Response ```javascript { "ExchangeRates": [ { "SourceCurrency": "EUR", "TargetCurrency": "GBP", "Value": 0.8505342 }, { "SourceCurrency": "GBP", "TargetCurrency": "EUR", "Value": 1.1757317 } ] } ``` | Property | Type | Contract | Description | | --------------- | ---------------------------------------- | -------- | ----------------------------- | | `ExchangeRates` | array of [Exchange rate](#exchange-rate) | required | The available exchange rates. | #### Exchange rate | Property | Type | Contract | Description | | ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `Id` | string | required | Unique identifier of the Exchange Rate. | | `EnterpriseId` | string | required | Unique identifier of the [Enterprise](/connector-api/operations/configuration#enterprise) to which the Exchange Rate belongs. | | `SourceCurrency` | string | required | ISO-4217 code of the source [Currency](/connector-api/operations/currencies#currency). | | `TargetCurrency` | string | required | ISO-4217 code of the target [Currency](/connector-api/operations/currencies#currency). | | `Value` | number | required | The exchange rate from the source currency to the target currency. | --- [Next Page](/llms-full.txt/1)