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 the nested create endpoint POST /folio/v1/checks/{checkId}/gratuities.

Linkage is expressed by the URL: checkId is the path parameter (documented on the
controller operation, bound by name — NOT a body field), so the body carries only the
gratuity entries. Retry-safety is the required Idempotency-Key header (referenceId retired).
If a client also sends checkId in the JSON body, the URL segment wins —
ApiControllerArgumentsResolver merges path params last, so the body value is silently overridden.
The gratuities inherit the linked check's folio target and checkNumber; POS context stays an
attribute of the check (it is not copied onto the gratuity). Contrast the standalone
POST /folio/v1/gratuities request body.

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 taxId, 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.