CLcloudbeds
Gratuities

Post one or more guest tips to a folio, house account, or group profile

Posts one or more tips (ITC 8995) as first-class folio transactions. Recipient attribution and POS context are stored MFD-side only; the Accounting Service Transaction carries the accounting state alone. Idempotent via the required Idempotency-Key header.

post/folio/v1/gratuities

Request

  • Base URL
    https://api.cloudbeds.com
  • URL
    https://api.cloudbeds.com/folio/v1/gratuities
  • Auth
    OAuth 2
    Authorization code: https://api.cloudbeds.com/auth/oauth/authorize
    Token URL: https://api.cloudbeds.com/auth/oauth/token scopes: write:item

Headers

x-property-idstring required
Example:1,2,3

A numeric, comma-separated string representing the property IDs, sent in the header.

Idempotency-Keystring required
Example:req-2026-05-05-2047-9b3f

Required per-request idempotency key and the sole dedup key for this endpoint: a retry carrying the same key and the same payload replays the original posting (notice populated); the same key with a different payload is rejected with IDEMPOTENCY_KEY_REUSED. Absent, empty, or whitespace-only → 400.

Request body

OR
OR

Example request

{
  "reservationId": "RES123456",
  "houseAccountId": "123456",
  "eventCode": "GRP2025",
  "folioId": "12345",
  "gratuities": [
    {
      "amount": "8.00",
      "taxes": [
        {
          "externalId": "tax_state_va_8",
          "taxId": "29486",
          "amount": "1.60"
        }
      ],
      "note": "Tip for Maria",
      "customTransactionCode": "GRT-VIP",
      "generalLedgerCustomCode": "GL-2410",
      "subReservationId": "SUB123",
      "recipient": {
        "userId": "usr_4821",
        "email": "maria.santos@cloudbeds.com",
        "name": "Maria Santos"
      },
      "gratuityId": "partner-grat-7a3f"
    }
  ]
}

Response

Gratuity successfully posted. Returns the Cloudbeds-assigned gratuityId for each posted gratuity and notice=null.

Example response

{
  "data": {
    "gratuityIds": [
      "9911283",
      "9911284"
    ],
    "notice": "Duplicate Idempotency-Key — returning original posting."
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.