Point of Sale integrations allow apps to post charges to the Cloudbeds guest folios or house accounts. While intended to cater to Restaurant/Retail POS platforms, this guide can be useful for other applications that must post charges (e.g., upsell platforms, self service apps, etc).
Using this guide and the Cloudbeds API, you will be able to develop a comprehensive POS integration.
Things to know before getting started
- Guest Folio -> where charges are typically posted. Note that a reservation can have multiple guests and multiple folios but currently charges can only be posted to the primary guest/folio.
- House Account -> used in Cloudbeds to track non-room related revenue. When syncing all transactions (not just guest charges) this is a good place to start.
- Stock Inventory -> Cloudbeds has basic ability to manage items & inventory. This can be synced with the POS app (see below Integration with Stock Inventory Sync) or completely managed by the POS app (Basic POS Integration).
In this use case property user can manage items only via POS app. Items can be added to myfrontdesk reservations in read-only mode.
(*) Mandatory requirements for POS category Certification.
(Mandatory) Reservation pull
POS app fetches occupied rooms and checked-in reservations with getReservations (or any other available query method). Only checked-in guests should be listed in the POS. (*)
POS app may subscribe to the reservation status_changed webhook. This way new reservations that have a status in-house/checked-in will trigger a webhook. See more about this in the Webhook guide.
(Mandatory - Option 1) Sync guest items and payments with Cloudbeds folio
POS app sends items via method postCustomItem and includes itemCategoryName e.g. Food / Drinks (*)
POS app must handle and specify taxes, both inclusive versus exclusive, according to the customer setup or preference (*)
You can use getTaxesAndFees to check the property tax configuration in myfrontdesk. Pontential taxes scenarios:
- Taxes Inclusive option 1) Net item + taxes breadkdown are sent.
- Taxes Inclusive option 2) Gross Item is sent (without tax breadown).
- Taxes Exclusive - Only net items are sent and taxes are managed manually by the property.
- Include the payment when item was paid for at the POS. If payment is cash parameter itemPaid=true may be used
- Use getPaymentMethods to see which methods are available
- If payment method is not enabled or doesn't exist in myfrontdesk account create it using postCustomPaymentMethod
- Leave out the payment when item is not paid for at the POS and should be paid for at the reception desk.
- Use postAdjustment to add a discount to a room rate, item, tax or fee.
- Include ItemCategoryName name via postCustomItem as highly useful if the property uses an Accounting integration.
- Include itemNote parameter to indicate the POS Receipt, strongly recommended to allow cross-referencing.
Myfrontdesk user can see all posted items and transactions in reservation folio. User can't delete the items from myfrontdesk folio.
(Mandatory - Option 2) Sync items in a single line
An alternative option to posting all items as described above is to consolidate items in one single line. This use case is valid if you do not follow the recommended 'Full Revenue Sync' covered below involving syncing all transactions to the house account. If you only post products to the guest reservation folio you can follow these guidelines:
- postCustomItem to post overall charges in one single line related to a guest reservation. (*)
- Tips should be posted separately in a separate line for correct reporting. (*)
- Handle and specify taxes, both inclusive versus exclusive, according to the customer setup You can use getTaxesAndFees to check the property tax configuration. (*)
- Include the payment when the full bill was paid for at the POS. If payment is cash parameter itemPaid=true may be used.
- Leave out the payment when the item is not paid for at the POS and should be paid for at the reception desk.
- Use postAdjustment to add a discount to a room rate, item, tax or fee.
Void items
POS app uses method /postVoidItem for voiding items already added to the reservation folio or a house account and /postVoidPayment for payments that should be voided. (*)
At the moment a refund can't be posted via API.
Use Cases
- Restaurant Point of Sale
- General Point of sale
- Wristbands
appItemID
is an identifier for each item in your application's inventory. Don't use a unique ID for each item you post to a reservation or house account. This will create numerous items Cloudbeds reports as Cloudbeds will expect they are different inventory items.
For example, Coca Cola should always have the same appItemID
.
Future calls using the same appItemID
will use the previously sent item name and description. Item name/description sent in a new request will be ignored. Ensure your users don't rename the item from e.g. Coca Cola to T-shirt and expect the new item to appear in Cloudbeds. We will keep the Coca Cola name and description unless the appItemID
changes.
In this use case property users have to manage items via myfrontdesk Inventory page. POS pulls myfrontdesk inventory and uses this information to post items into myfrontdesk folio.
Reservation pull
POS app fetches occupied rooms and checked-in reservations with getReservations (or any other available query method). Only checked-in guests should be listed in the POS.
POS app may subscribe to the reservation status_changed webhook. This way new reservations that have a status in-house/checked-in will be trigger a webhook. See more about this in the Webhook guide.
Sync myfrontdesk inventory
POS app synchronizes items with myfrontdesk:
- uses methods getItemCategories and getItems for retrieving items from myfrontdesk;
- uses methods postItemCategory and postItemsToInvetory for posting items to myfrontdesk, item can be updated with putItemsToInventory
Sync guest items and payments with myfrontdesk folio
POS app adds items via method postItem
POS app adds payment with postPayment
- Use getPaymentMethods to see which methods are available in myfrontdesk account
- If payment method is not enabled or doesn't exist in myfrontdesk account create it using postCustomPaymentMethod
- When item is not paid for and should be paid for at the reception desk leave out the payment.
- Use postAdjustment to add a discount to a room rate, item, tax or fee.
Sync all other transactions with myfrontdesk
Cloudbeds customers like to have a central place to view all of the transactions that happen in their property. If a guest that doesn't stay at the hotel is still having a drink at the bar, this transaction can be synced into the myfrontdesk House Account functionality.
POS app uses /postNewHouseAccount to create a house account on a scheduled basis e.g. daily, monthly.
POS app uses /postItem with parameter houseAccountID
to post an item into a myfrontdesk house account. Use payments
parameter to add payments for the item.
Void items
POS app uses method /postVoidItem for voiding items already added to the reservation folio or a house account and /postVoidPayment for payments that should be voided.
At the moment a refund can't be posted via API.
Block room charge on reservations
There is a need to block a POS from charging to specific reservations that are checked into a property. This needs to be controllable through a setting on the reservation in Cloudbeds. Based on the property rules, the user will determine whether the guest checking in can charge incidentals back to their reservation folio. When this flag is set to “No”, Cloudbeds will not allow a charge from the POS to be posted to the reservation.
Custom Fields
A custom field will be added to the property named “POS Room Charge” with a Shortcode of “pos-room-charge”, configured to apply to a Reservation.
The POS Room Charge custom field will be visible on the Reservation in the “Show More” section.
When the POS Room Charge custom field is set to “n”, “N”, “no”, “No”, or “NO” the system will not allow a room charge to occur (see more details below). When the POS Room Charge is set to anything else the system will allow a room charge to occur. This means that by default a reservation will allow a POS room charge to be posted and this only needs to be updated when it should be blocked.
Interaction with APIs and POS
The flow to post a room charge to a POS starts with a room lookup using the /getReservations API. The POS Room Charge custom field will be included in the response, letting the POS know whether any reservations match the search criteria, and if there are matches whether they are allowed to do a room charge or not. The POS will then show the reservations that match the search criteria, and if a reservation is marked as not allowing a POS room charge it will display an indicator that the reservation does not allow room charges.
The next step in the flow is sending the actual charge to one of the reservations found during the lookup, this charge is sent through the /postCustomItem API. This API will check the POS Room Charge custom field, and if it is marked as No it will not let the posting occur, replying to the POS with that information so that it can be displayed to the user.
This will provide double protection against a POS room charge being applied to the reservation, both by displaying information to the user, and by not allowing the charge to go through if there is some kind of override done in the POS.
Technical Implementation
/getReservations
The /getReservations endpoint that is used for room/guest search by the POS will return the following when a room charge is not allowed and should be blocked.
...
"data": [
{
...
"customFields": [
{
"customFieldName": "pos-room-charge",
"customFieldValue": "No"
}
...
Any other value returned for a customFieldName pos-room-charge should be treated as a “Yes”, the room is allowed to be charged to.
/postCustomItem
If a room charge attempt is made for a reservation marked as room charge not allowed, the /postCustomItem endpoint will respond with a success = false and an error message explaining why.
{
"success": false,
"message": "Room charge is prohibited on this reservation"
}
Comments
0 comments
Please sign in to leave a comment.