--- title: "Post one or more guest tips linked to an existing check" method: POST path: "/folio/v1/checks/{checkId}/gratuities" tags: ["Gratuities"] --- # Post one or more guest tips linked to an existing check `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` 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. ## Path parameters - `checkId` string, required ## Headers - `x-property-id` string, required - `Idempotency-Key` string, required ## Request body - PostCheckGratuityRequestSchema: 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` GratuitySchema[], 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. - `amount` string, nullable, required: Gratuity amount in the property currency. Must be > 0; corrections require void + repost (negative amounts rejected). - `taxes` TaxSchema[]: Optional tax rows applied to this gratuity. Each tax follows the item-tax pattern — identify the tax by exactly one of `externalId` / `taxId`; an unmatched value returns TAX_NOT_FOUND. - `externalId` string, nullable: The partner-owned identifier configured on the tax under the property's tax settings (a 3rd-party reference the property has associated with one of its Cloudbeds taxes). Required unless `taxId` is sent. Must resolve to an active tax on the property; unknown or inactive values are rejected with TAX_NOT_FOUND. - `taxId` string, nullable, required: Cloudbeds identifier of the tax, as returned in `taxID` by getTaxesAndFees. Required unless `externalId` is sent. This identifier is not permanent: when the property edits the tax, Cloudbeds replaces it with a new identifier. A previous identifier is still accepted and is recorded as sent, against the version of the tax it names. A deleted tax is rejected with TAX_NOT_FOUND. Use `externalId` when you need a reference that stays the same across edits. - `amount` string, nullable, required: Tax amount applied to the parent object — item, fee, service charge or gratuity, whichever this row is nested under. Decimal string in major units of the property currency. - `note` string, nullable: Free-text label displayed on the folio line item. - `customTransactionCode` string, nullable: Override the property default Custom Transaction Code for this posting. - `generalLedgerCustomCode` string, nullable: Override the property default GL custom code for this posting. - `subReservationId` string, nullable: Sub-reservation identifier. If provided, this gratuity entry is routed to the specified sub-reservation within the parent reservation (request-level reservationId). If omitted on a reservation with a single stay and no gratuity entry in the request carries a subReservationId, the gratuity is attributed to the room assigned to that stay; when the stay is split across rooms because of an in-stay move, the room assigned on the sale date is used. Multi-stay reservations, and requests that set subReservationId on only some gratuities, need an explicit identifier on each gratuity for room attribution. Has no effect when the request-level target is houseAccountId or eventCode. - `recipient` RecipientSchema: Recipient attribution for a gratuity. All three fields are optional and independent. When more than one is provided, resolution priority is: userId > email > name. - `userId` string, nullable: Cloudbeds user ID; must reference a valid user on the property or RECIPIENT_USER_NOT_FOUND is returned. - `email` string, nullable: Recipient email; resolved to a user record if userId not provided. - `name` string, nullable: Free-text recipient name; always stored as a display string regardless of whether a user record is resolved. - `gratuityId` string, nullable: Optional partner-supplied public handle for this gratuity (accept-or-generate). When omitted, Cloudbeds generates one and returns it. Must be a non-empty string containing only letters, digits, and . _ ~ -, unique among active (non-voided) gratuities on the property; reusable after this gratuity is voided. Used to address the gratuity for void (DELETE /folio/v1/gratuities/{gratuityId}). ## Response `201` Gratuity successfully posted. Returns the Cloudbeds-assigned gratuityId for each posted gratuity and notice=null. - PostGratuityResponseSchema - `data` PostedGratuityResponseSchema, required: Result of a postGratuity call. gratuityIds are the Cloudbeds-assigned public handles of the posted gratuities — one per gratuities[] entry — each addressable for void via DELETE /folio/v1/gratuities/{gratuityId}. - `gratuityIds` string[], required: Public handles of the posted gratuities, one per gratuities[] entry. Each is addressable for void via DELETE /folio/v1/gratuities/{gratuityId}. - `notice` string, nullable: Set when this request replayed an earlier one: the same Idempotency-Key was sent with the same body. When present, no new posting was created and the original response is returned. ## Other responses - `400`: Bad request — missing/oversized Idempotency-Key header, validation failure, unmatched tax externalId/taxId, unknown recipient userId, or the resolved check carries no folio target. See GratuityErrorCodeEnumSchema. - `403`: Forbidden — insufficient permissions on the requested property. - `404`: Not found — no check matches {checkId} on this property (CHECK_NOT_FOUND). - `409`: Conflict — IDEMPOTENCY_KEY_REUSED (Idempotency-Key reused with a different payload) or DUPLICATE_GRATUITY_ID (a partner-supplied gratuityId collides with an active gratuity). - `500`: Internal server error. --- [API](https://skmtc.dev/cloudbeds/apis/cloudbeds-api-v2.md) - [All operations](https://skmtc.dev/cloudbeds/apis/cloudbeds-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudbeds/apis/cloudbeds-api-v2/revisions/69bffac143cc?raw)