Post one or more guest tips linked to an existing check

post

https://api.cloudbeds.com/folio/v1/checks/{checkId}/gratuities

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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

checkId

string

required

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

Body Params

Gratuity entries to link to the check.

Request body for posting tips onto an existing check. The check is identified by the checkId path parameter, so the body carries only the gratuity entries — a checkId sent in the body is ignored. The tips inherit the check's folio target and check number; POS context stays an attribute of the check and is not copied onto them. Retry-safety is the required Idempotency-Key header. For a tip with no associated check, use POST /folio/v1/gratuities.

gratuities

array of objects

required

Gratuity entries to post to the check. 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 tax externalId, unknown recipient userId, or the resolved check carries no folio target. See GratuityErrorCodeEnumSchema.

403Forbidden — insufficient permissions on the requested property.

404Not found — no check matches {checkId} on this property (CHECK_NOT_FOUND).

409Conflict — 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.