Post charges to a guest reservation

POS are owned by either hotels or they are third-party POS. If the hotel owns the POS then the charges and tips are posted to the guest reservation. For third-party POS transitory charges and tips are posted to the guest reservation. POS app fetches checked-in reservation of the guest and posts revenue or transitory charges to the guest folio.

The hotel decides how charges to the guest reservation should be reflected. If a revenue charge is posted on the room, then it is excluded on the PO external folio. If POS takes care of the POS revenue independently, then transitory charge is posted on the guest reservation.

Search the room

To find the room where charges should be added, access the Booking API.

GET /booking/v1/reservations

There are a variety of filters and which ones you use depends on you. Most likely, you will want to limit the reservation to be in-house and then search for room number or guest name (full-text search). You might get more than one reservation as a response; you must pick the relevant reservation.

Search the folio

The Finance API lets you access folios, invoices, and accounting. The first one you’ll need is:

GET /finance/v1/folios

Add the reservationIds as a query parameter and type as Guest, and either get the main folio or use any custom logic to find the folio you want to add the charges or payments to.

You must get the first folio that contains AddCharge in allowedActions. If no such folio exists, then you’ll have to create a new folio.

POST /finance/v1/folios

Once you identified the folio to use, you can perform different actions. The most useful being:

POST /finance/v1/folio-actions/{folioId}/charges

Check pre-existing services on the folio

You can check if the breakfast or any other service is already booked by the guest by simply calling the following API endpoint:

GET /finance/v1/folios

Move charges and allowances between folios

If you post a charge or allowance to an incorrect folio by mistake, then you can move them to the correct folio by using the following API endpoint:

POST /finance/v1/folio-actions/{folioId}/move-charges

Example

{
  "targetFolioId": "KFCSQUID-1",
  "reason": "Incorrect posting",
  "chargeIds": [
    "KFCSQUID-1-C-1",
    "KFCSQUID-1-C-5"
  ],
  "allowanceIds": [
    "KFCSQUID-1-A-1",
    "KFCSQUID-1-A-2"
  ],
  "transitoryChargeIds": [
    "KFCSQUID-1-TC-1",
    "KFCSQUID-1-TC-2"
  ]
}

Posting charges when the hotel owns the POS

When the POS is owned and operated by the hotel, you post the revenue charge by using the following API endpoint:

POST /finance/v1/folio-actions/{folioId}/charges

Example

{
   "serviceType":"FoodAndBeverages",
   "vatType":"NormalCovid19",
   "subAccountId":"BER-BRKF",
   "name":"Breakfast",
   "amount":{
      "amount":23.0,
      "currency":"EUR"
   },
   "receipt":"BSPHEDWU-1-1",
   "businessDate":"2021-02-22"
}

By default, the current date is the business date. In some cases, you might want to post the charges to the previous business date; this is only possible until 6 AM of the present day.

Posting tips

If tip is paid by the guest and the charge and tip are posted to the reservation, then tip needs to be booked as transitory item. You post the tips by using the following API endpoint:

POST /finance/v1/folio-actions/{folioId}/transitory-charges

Example

{
   "name":"TIP Restaurant:1637",
   "amount":{
      "amount":3.0,
      "currency":"EUR"
   },
   "receipt":"1637",
   "businessDate":"2021-02-22"
}

Third-party POS

When the hotel does not own the POS outlet, and the guest wants to add the charge to the room, you post a single transitory charge with the correct amount, receipt, and name using the following API endpoint:

POST /finance/v1/folio-actions/{folioId}/transitory-charges

Transitory charges never have VAT. VAT is collected by the company that is offering the service, and it also needs to provide detailed receipts and invoices to the guests. The value of receipt should be the receipt or bon number from the POS. You must post the charge to the current or previous business date. You cannot add charges to future dates.

Example

{
   "name":"FlowersAndYou",
   "amount":{
      "amount":13.0,
      "currency":"EUR"
   },
   "receipt":"R23412",
   "businessDate":"2021-02-22"
}

By default, the current date is the business date. In some cases, you might want to post the charges to the previous business date; this is only possible until 6 AM of the present day.

You can also refund a transitory charge if there was some error. For example, if you posted 50 EUR transitory charge for an excursion and want to delete it, add the same charge but insert -50 EUR.