Gratuities

Post one or more guest tips linked to an existing check

Posts one or more tips (ITC 8995) linked to the check identified by the path {checkId}. The gratuities inherit the check's folio target and checkNumber; POS context stays an attribute of the linked check (not copied onto the gratuity). The body carries only the gratuity entries. A check may carry many gratuities. Idempotent via the required Idempotency-Key header.

post/folio/v1/checks/{checkId}/gratuities

Request

Base URL
https://api.cloudbeds.com
URL
https://api.cloudbeds.com/folio/v1/checks/{checkId}/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

Path parameters

checkIdstring required

The partner checkId of the check to link these gratuities to.

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

Example request

{
  "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.