Point of Sale

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).

(Mandatory) 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 Cloudbeds. Potential 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 number, strongly recommended to allow cross-referencing.

Cloudbeds users can see all posted items and transactions in reservation folio. User can't delete the items from the 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.

(Optional) Sync all other transactions with Cloudbeds

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 (Recommended to implement, and if so it must be optional per property).

• To do that, POS app uses postNewHouseAccount to create a house account on the scheduled basis e.g. daily, monthly.
• POS app uses /postCustomItem 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.

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.

(Optional) POS Integration with Stock Inventory sync and block room charge

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 getItemCategoriesand getItems for retrieving items from Cloudbeds;
• uses methods postItemCategory and postItemsToInventory for posting items to Cloudbeds, item can be updated with putItemToInventory.

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

• 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.

• 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"
}

FAQ

How to post items for multiple guests on a reservation?

At the moment, multiple guests and even multiple rooms can be under 1 reservation number. This means that you will always post all transactions under the main guest name and the reservationID they have.
Going forward we will support multiple folios for group reservations via the API (meaning each guest will be able to have their own bill).

If the reservation has two (or more) rooms, an item can be added to separate rooms, but as stated above it all goes into the same guest's folio. To use this feature you may use the subReservationID or roomID fields.

Which payment methods exist in Cloudbeds?

Allowed payment types depend on the property. They are configured in myfrontdesk Payment Options settings page. Basic methods are cash, check and cash.

• Use getPaymentMethods to see which methods are available in the Cloudbeds account
• If payment method is not enabled or doesn't exist in myfrontdesk account create it using postCustomPaymentMethod

In case you'd like to leave the charge to the room you just need to leave out the payment. This will post a debit in Cloudbeds folio and reception staff will see it prior to check out.

Note that if you're using itemPaid parameter with postCustomItem, payment type will always be cash.

How to modify items?

Currently posting updates with put are not enabled for this method. This will be coming in the future.
At the moment you should delete/void the item and post a new one. To void, use postVoidItem.

How to post the same item multiple times?

• Even though referenceID and saleDate are optional you should be using them for each transaction. referenceID is your POS transaction reference. If it exists, then Cloudbeds will prevent adding of duplicates.
• Basically, if you post one Coca Cola item (with no referenceID) and then post another Coca Cola item (with or without referenceID), the second one will be treated as a new item.
• If you send same referenceID, the initial post will be maintained and the 2nd will not be treated as an update.

How to void only 1 custom item from the array?

/postVoidItem only accepts soldProductID. This information is equivalent to the value returned in /postCustomItem. At the moment, the only solution to would be to use /postCustomItem once per item, and when necessary, you can use /postVoidItem for that one item.

We should be revisiting this in the future and we'll have this use case in mind when proposing a better solution.

How to add discounts?

Use /postAdjustment to discount the amount charged. Adjustment can be applied to room revenue, items, taxes and fees.

Note that adjustments result in a negative value in Cloudbeds system. E.g. Posting 5 will discount the charge by 5. Posting -5 will add an additional charge of 5.

Do cash payments integrate with the Cash Drawers?

Posting cash payments in Cash Drawers is not supported via the API.