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

post

https://api.cloudbeds.com/folio/v1/gratuities

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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Gratuity posting request: folio target and one or more gratuity entries.

reservationId

string | null

required

Reservation identifier. Required if houseAccountId and groupCode are not provided.

houseAccountId

string | null

House account identifier. Required if reservationId and groupCode are not provided.

groupCode

string | null

Group code. Required if reservationId and houseAccountId are not provided.

folioId

string | null

Folio identifier within the chosen account target. Numeric string (the underlying folio_id is a 64-bit unsigned integer). Optional — when omitted, the default folio for the target is used.

gratuities

array of objects

required

Gratuity entries to post. At least one entry required. Each entry becomes its own folio line item and its own Accounting Service transaction.

gratuities*

Headers

x-property-id

string

required

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

Idempotency-Key

string

required

length ≤ 255

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.

Responses

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

400Bad request — missing/oversized Idempotency-Key header, validation failure, unmatched taxId, unknown recipient userId, or an unresolvable folio target. See GratuityErrorCodeEnumSchema for structured error codes.

403Forbidden — insufficient permissions on the requested property.

409Conflict — see GratuityErrorCodeEnumSchema for the structured codes: IDEMPOTENCY_KEY_REUSED (Idempotency-Key reused with a different payload) or DUPLICATE_GRATUITY_ID (a partner-supplied gratuityId collides with an active gratuity).

500Internal server error.