--- title: "Post one or more guest tips to a folio, house account, or group profile" method: POST path: "/folio/v1/gratuities" tags: ["Gratuities"] --- # Post one or more guest tips to a folio, house account, or group profile `POST /folio/v1/gratuities` ## Request - Base URL: `https://api.cloudbeds.com` - URL: `https://api.cloudbeds.com/folio/v1/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) 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. ## Headers - `x-property-id` string, required - `Idempotency-Key` string, required ## Request body - union: Request body for the standalone postGratuity endpoint (a tip with no check). Exactly one of reservationId / houseAccountId / eventCode must be provided. Sub-reservation routing is per-gratuity via GratuitySchema.subReservationId. To link tips to a check, use POST /folio/v1/checks/{checkId}/gratuities instead — checkId / checkNumber / POS context are check attributes and are not accepted here. - object - `reservationId` string, nullable, required: Reservation identifier. Required if houseAccountId and eventCode are not provided. - `houseAccountId` string, nullable: House account identifier. Required if reservationId and eventCode are not provided. - `eventCode` string, nullable: Event code. Required if reservationId and houseAccountId are not provided. - `folioId` string, nullable: 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` GratuitySchema[], required: Gratuity entries to post. 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}). - object - `reservationId` string, nullable: Reservation identifier. Required if houseAccountId and eventCode are not provided. - `houseAccountId` string, nullable, required: House account identifier. Required if reservationId and eventCode are not provided. - `eventCode` string, nullable: Event code. Required if reservationId and houseAccountId are not provided. - `folioId` string, nullable: 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` GratuitySchema[], required: Gratuity entries to post. 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}). - object - `reservationId` string, nullable: Reservation identifier. Required if houseAccountId and eventCode are not provided. - `houseAccountId` string, nullable: House account identifier. Required if reservationId and eventCode are not provided. - `eventCode` string, nullable, required: Event code. Required if reservationId and houseAccountId are not provided. - `folioId` string, nullable: 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` GratuitySchema[], required: Gratuity entries to post. 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 an unresolvable folio target. See GratuityErrorCodeEnumSchema for structured error codes. - `403`: Forbidden — insufficient permissions on the requested property. - `409`: Conflict — 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). - `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)