This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Gratuity

If configured, the Toast platform prompts the restaurant employee for a gratuity after the Toast platform receives a response from the PMS provider about the discounts and payments redemption.

Note

Gratuity functionality is configurable through the Toast administration back-end. Toast recommends that partners utilize the gratuity transaction to consume all tips related to tender payments. Partners that do so should ignore non-zero values in the tipAmount field contained within the redeem transaction.

Gratuity workflow

  1. After an employee enters a gratuity amount, the Toast POS system sends a TENDER_GRATUITY request that specifies a gratuity amount to add to a TENDER_REDEEM transaction. The Toast-Transaction-GUID of TENDER_REDEEM to add the gratuity amount is provided in the transactionToUpdate value in the body of the TENDER_GRATUITY request.

  2. The PMS provider responds to the Toast platform with a gratuityResponse value in the TransactionResponseGratuity object, which contains the value of gratuity that the guest added.

Gratuity request body

{
   "discountsTransactionInformation":null,
   "paymentsTransactionInformation":null,
   "redeemTransactionInformation":null,
   "gratuityTransactionInformation":{
      "transactionToUpdate":"73885a84-59c3-44b6-a4c7-45ea23892c56",
      "additionalGratuity":3.00
   },
   "reverseTransactionInformation":null
}

Successful gratuity response body

{
  gratuityResponse: {
    account: {
      tenderIdentifier: '2',
      properties: [
        { key: 'Room Number', value: '406' },
        { key: 'Name', value: 'john adams' },
        { key: 'Reservation Number', value: '7492936' },
        { key: 'Company Name', value: 'Apple, Inc.' },
        { key: 'Guest Status', value: 'Active' },
        { key: 'Charge Limit', value: '$120.00' }
      ],
      additionalProperties: [ { key: 'storedValue', value: 51.88 } ]
    },
    tenderPayments: [
      {
        name: 'Tender Payment',
        identifier: 'f4a3e9f0-bc3b-4d7f-ad40-a071d2217861',
        type: 'STORED_VALUE',
        amount: 2.12,
        tipAmount: 6
      }
    ]
  },
  transactionStatus: 'ACCEPT'
}
}