Skip to main content

Service Charge Feature

Introduction​

The optional SERVICE_CHARGE feature can be specified on creation or update of an existing PMS provider. When this feature is activated, the payloads sent to the PMS will have fields that contain the following:

  • The service charge for each item in the order
  • The total service charge amount for the transaction
  • The service charge tax type, which can be untaxed or tax-apportioned
Info

See the Definition and Tax Calculation Table for more details on service charges and their tax calculations.

Enabling the Service Charge Feature​

For a New PMS Provider​

To create a new PMS Provider with the SERVICE_CHARGE feature enabled, follow the instructions in Configuring the PMS. Make sure to include the SERVICE_CHARGE option in your PMS Provider creation request.

For a PMS Provider Already in Use​

To enable the SERVICE_CHARGE feature for a PMS Provider that is already being used on an account, you must do the following:

Step 1​

Use the Get PMS Provider endpoint to retrieve the Business Location's PMS provider details. Copy the provider id.

Step 1

Step 2​

Use the id retrieved in the previous request to update the existing PMS provider with the new SERVICE_CHARGE feature included in the request.

Step 2

Step 3​

In the Back Office, open the payment method created for making room charges and change the PMS Server from "Other" to a different option and save.

Step 3

Step 4​

Reopen the Payment method and change the PMS Server back to "Other" and save.

Step 4

Example Payloads - PMS API​

{
    "name": "Table 1",
    "openDate": "2023-06-30T10:10:25.366Z",
    "closeDate": "2023-06-30T10:16:37.959Z",
    "covers": 2,
    "ownerId": 188481,
    "ownerName": "Manager",
    "deviceId": 74695,
    "transactions": [
        {
            "unitAmount": 20.0000,
            "quantity": 1.00000,
            "amount": 20.0000,
            "description": "Vin BT",
            "staffId": 188481,
            "staffName": "Manager",
            "groupId": 1093180845981751,
            "groupName": "Vin BT",
            "taxId": 1093180845981704,
            "taxName": "TVA 7.7%",
            "taxRate": 1.0770,
            "taxIncluded": true,
            "sku": "OI6",
            "serviceChargeContribution": 2.0000
        },
        {
            "unitAmount": 7.0000,
            "quantity": 1.00000,
            "amount": 7.0000,
            "description": "Glaces",
            "staffId": 188481,
            "staffName": "Manager",
            "groupId": 1093180845981755,
            "groupName": "Glaces",
            "taxId": 1093180845981704,
            "taxName": "TVA 7.7%",
            "taxRate": 1.0770,
            "taxIncluded": true,
            "sku": "OI10",
            "serviceChargeContribution": 0.7000
        }
    ],
    "payments": [
        {
            "paymentDate": "2023-06-30T10:16:37.946Z",
            "staffId": 188481,
            "staffName": "Manager",
            "gratuity": 0.0000,
            "amount": 29.7000,
            "methodName": "Room charge",
            "reservationId": "001",
            "methodCode": "IKPMS"
        }
    ],
    "receiptId": "R74695.1",
    "receipt": null,
    "uuid": "fNv70P91RceulwPknQltYQ==",
    "id": null,
    "initialAccountId": "A74695.1",
    "fiscId": "A74695.1",
    "revenueCenterId": 1093180845981719,
    "revenueCenterName": "Poste fixe",
    "serviceCharge": {
        "amount": 2.7000,
        "type": "UNTAXED"
    }
}

Example Data - Financial API​

{
        "accountReference": "DnxmZU38RY28dHgy4W__Qw==",
        "accountFiscId": "A75074.8",
        "receiptId": "R75074.8",
        "source": {
            "initialAccountId": "A75074.8"
        },
        "salesLines": [
            {
                "id": "S75074.15",
                "totalNetAmountWithTax": "11.00",
                "totalNetAmountWithoutTax": "8.33",
                "menuListPrice": "10.00",
                "unitCostPrice": "0.00",
                "serviceCharge": "1.00",
                "serviceChargeRate": "10.00",
                "discountAmount": "0.00",
                "taxAmount": "1.6667",
                "taxCode": "VAT20",
                "taxRatePercentage": "20.00",
                "taxLines": [
                    {
                        "taxId": "41910290874374",
                        "taxCode": "VAT20",
                        "taxRate": "1.2",
                        "taxAmount": "1.666667",
                        "taxIncluded": true
                    }
                ],
                "accountDiscountAmount": "0.00",
                "totalDiscountAmount": "0.00",
                "sku": "13",
                "name": "Burger",
                "statisticGroup": "Food",
                "quantity": "1.000",
                "accountingGroup": {
                    "accountingGroupId": 41910290874411,
                    "name": "Food"
                },
                "currency": "GBP",
                "tags": [],
                "categories": [
                    {
                        "category": "default",
                        "value": "Food"
                    }
                ],
                "timeOfSale": "2023-07-07T15:37:52.326Z",
                "deviceId": 75074,
                "deviceName": "iPad1"
            },
            {
                "id": "S75074.16",
                "totalNetAmountWithTax": "5.50",
                "totalNetAmountWithoutTax": "4.17",
                "menuListPrice": "5.00",
                "unitCostPrice": "0.00",
                "serviceCharge": "0.50",
                "serviceChargeRate": "10.00",
                "discountAmount": "0.00",
                "taxAmount": "0.8333",
                "taxCode": "VAT20",
                "taxRatePercentage": "20.00",
                "taxLines": [
                    {
                        "taxId": "41910290874374",
                        "taxCode": "VAT20",
                        "taxRate": "1.2",
                        "taxAmount": "0.833333",
                        "taxIncluded": true
                    }
                ],
                "accountDiscountAmount": "0.00",
                "totalDiscountAmount": "0.00",
                "sku": "14",
                "name": "Bagel",
                "statisticGroup": "Food",
                "quantity": "1.000",
                "accountingGroup": {
                    "accountingGroupId": 41910290874411,
                    "name": "Food"
                },
                "currency": "GBP",
                "tags": [],
                "categories": [
                    {
                        "category": "default",
                        "value": "Food"
                    }
                ],
                "timeOfSale": "2023-07-07T15:37:53.464Z",
                "deviceId": 75074,
                "deviceName": "iPad1"
            }
        ],
        "payments": [
            {
                "code": "CASH",
                "description": "Cash",
                "paymentMethodId": 41910290874392,
                "netAmountWithTax": "16.50",
                "currency": "GBP",
                "tip": "0.00",
                "type": "NORMAL",
                "deviceId": 75074,
                "deviceName": "iPad1",
                "fiscId": "T75074.8",
                "uuid": "fryjerL6QAKwrkUcyMenmg==",
                "fiscDate": "2023-07-07T15:38:02.841Z"
            }
        ],
        "timeOfOpening": "2023-07-07T15:37:49.468Z",
        "timeOfCloseAndPaid": "2023-07-07T15:38:02.862Z",
        "tableName": "",
        "type": "SALE",
        "nbCovers": 0.0,
        "dineIn": true,
        "deviceId": 75074,
        "deviceName": "iPad1"
}
NOTE

See the table for more details on Service Charge tax calculations.