--- title: "Post a completed POS check (e.g., F&B) to a guest folio, house account, or group profile" method: POST path: "/folio/v1/checks" tags: ["Checks"] --- # Post a completed POS check (e.g., F&B) to a guest folio, house account, or group profile `POST /folio/v1/checks` ## Request - Base URL: `https://api.cloudbeds.com` - URL: `https://api.cloudbeds.com/folio/v1/checks` - Auth: OAuth 2 - Authorization code: `https://api.cloudbeds.com/auth/oauth/authorize` - Token URL: `https://api.cloudbeds.com/auth/oauth/token` scopes: `write:item` Replaces postCustomItem with first-class folio transactions enriched with hospitality POS context (check identity, revenue center, meal period, gratuity, service charge). Items posted via this endpoint are recorded as regular folio items, not Custom Items, and are tagged as POS-originated for UI differentiation. ## Headers - `x-property-id` string, required - `Idempotency-Key` string, required ## Request body - union: Posts a completed POS check (e.g., F&B) to a guest folio, house account, or group profile. Replaces postCustomItem with first-class folio transactions enriched with hospitality POS context (check identity, revenue center, meal period, gratuity, service charge). All items, taxes, fees, gratuities, service charge, discounts, and payments in this request belong to the single check identified by checkNumber/checkId. Multi-check batching is not supported — issue a separate postCheck call per check. - object - `checkNumber` string, nullable: Partner-assigned check number visible on the customer receipt (e.g., POS terminal display number). Stored on each posted folio line and visible in the folio UI. Optional — when omitted, the server mints a Cloudbeds reference (cb-) and returns it in the response so the partner can echo it back. - `checkId` string, nullable: Partner-assigned durable external reference for the check (UUID or opaque string). Optional — when omitted, Cloudbeds generates one and returns it. Echoed on the response and used to void the check later. Must be unique among the property's active checks; a value released by a void can be reused. Letters, digits, and . _ ~ - only (addressed as a URL path segment for void). - `reservationId` string, nullable, required: Reservation identifier. Required if houseAccountId and eventCode are not provided. Per-item sub-reservation targeting is expressed via items[].subReservationId. - `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. - `roomId` string, nullable: Room identifier where the charge originated, when applicable. - `guestId` string, nullable: Guest identifier. Optional — used for guest-attributed POS reporting. - `guestName` string, nullable: Guest name as captured at the POS. Used when no guestId is provided. - `saleDate` string, nullable: Sale date in RFC 3339 format. If not provided, the current timestamp is used. A future saleDate produces a 'pending' transaction. - `posContext` PosContextSchema: POS source metadata for the request. restaurantName / revenueCenter / mealPeriod / staffReference describe the POS session that produced the request as a whole; they apply uniformly to every item (postCheck) or gratuity entry (postGratuity) in the same POST. - `restaurantName` string, nullable: Restaurant or outlet name. - `revenueCenter` string, nullable: Revenue center identifier. - `mealPeriod` string, nullable: Meal period (e.g., breakfast, lunch, dinner). - `staffReference` string, nullable: Free-text reference to a staff member or terminal in the source POS. - `coverCount` integer, nullable: Number of guests on the check. Used for per-cover F&B reporting. - `totals` CheckTotalsSchema: Partner-supplied check totals broken out by component. Used for two purposes: (1) totals-only postings — when items[] is empty, totalItems carries the items subtotal and the server posts a single synthetic items folio line; inline serviceCharge / discounts[] continue to write their own rows; (2) cross-validation — when items[] is also supplied, each total field cross-validates against the corresponding server-computed sum (items / SC / gratuity / discount / tax / fees). Mismatches surface as INVALID_TOTAL_MISMATCH with the failing component identified. totalTax / totalFee are cross-cutting aggregates: in items mode they cross-validate the sum across the whole check; in totals-only mode the partner amount routes to the per-property "Default POS tax" / "Default POS fee" catch-all catalog records (lazy-created), keeping the ledger invariant that every tax_id / fee_id reference resolves to a real row. - `totalItems` string, nullable, required: Items subtotal. Per item: amount + its taxes[] + its fees[] + the taxes on those fees — the nested fee-tax term is the one most often left out. When items[] is supplied alongside, this value must equal the server-computed subtotal within 1 minor unit per currency; a larger difference is rejected with INVALID_TOTAL_MISMATCH. When an item carries a discount this figure is the amount BEFORE that discount — the comparison runs on the items as sent, and the discount is applied afterwards, so a 20.00 item with a 5.00 discount is declared as 20.00 and posts 15.00. When items[] is empty, this is the gross figure the single synthesised line carries. Not a grand total — service charge, gratuity and discount have their own fields below. - `totalServiceCharge` string, nullable: Service-charge subtotal — serviceCharge.amount + sum(serviceCharge.taxes). Optional; cross-validates against the inline serviceCharge data ONLY when both are supplied. In totals-only mode without inline serviceCharge, this value is the partner-declared SC aggregate (validation deferred to the persistence layer). - `totalGratuity` string, nullable: Gratuity subtotal — sum(gratuities[].amount + gratuities[].taxes). Optional; accepted on the wire but server-side validation is deferred until the embedded-gratuity domain handling lands (today gratuities are accepted but not mapped to the domain payload). - `totalDiscount` string, nullable: Discount subtotal — sum(discounts[].amount), partner-supplied as a positive value. Optional; cross-validates against the inline discounts[] ONLY when both are supplied. In totals-only mode without inline discounts, this value is the partner-declared discount aggregate. - `totalTax` string, nullable: Total tax across the check — sum of every tax line (items[].taxes, items[].fees[].taxes, serviceCharge.taxes, gratuities[].taxes). Optional. When items[] is supplied, the partner value cross-validates against the server-computed sum (INVALID_TOTAL_MISMATCH on drift). In totals-only mode (items[] empty), the partner value is persisted as a single tax line on the synthetic POS-sale item, linked to the property's lazily-created "Default POS tax" catalog record. Zero or omitted skips the synthesis. - `totalFee` string, nullable: Total fees across the check — sum of items[].fees[].amount. Fees only attach to items in the postCheck data model, so the sum is items-scoped. Optional. Same items-mode cross-validation and totals-only synthesis semantics as totalTax, routed through the property's "Default POS fee" catalog record. Zero or omitted skips the synthesis. - `items` CheckItemRequestSchema[]: Line items on the check. Each line is posted as a regular folio item, not a Custom Item. At least one of items[] or totals must be supplied — when items[] is empty, totals is required, and the server posts a single folio line carrying totals.totalItems. - `type` 'PRODUCT', required: Discriminator selecting the kind of line — see CheckItemTypeEnum. - `name` string, required: Human-readable line name displayed on the folio (dish or beverage name). - `externalLineId` string, nullable: Optional partner-supplied identifier for this line occurrence on the check (the POS system's own line reference — e.g., Clover lineItem.id, Toast Selection.guid, Square line uid, or a per-check line sequence). Per line, not per unit: a quantity-2 line carries one reference. When provided, must be unique within this check's items[]; a duplicate is rejected with DUPLICATE_EXTERNAL_LINE_ID. When omitted, the line is stored with no reference — Cloudbeds does not generate one. Supplied values are echoed back on the response and on line events so the partner can correlate the posted line without storing any Cloudbeds identifier. - `quantity` integer, required: Number of units. Informational metadata only — not used for accounting math (amount is the line total, not price * quantity). - `price` string, nullable: Per-unit price. Optional informational metadata — recorded on the folio for display and reporting; not used for accounting math. amount is the financial source of truth for this line; when price is omitted, amount is used as the per-unit price on the folio row. Decimal string in major units of the property currency. - `amount` string, nullable, required: Total line amount — the financial source of truth for this line. The server posts this value to the folio without recomputing it from price * quantity. Decimal string in major units of the property currency. - `note` string, nullable: Optional free-text note for this line (modifier, allergen, special request). - `customTransactionCode` string, nullable: Custom Transaction Code (chart-of-accounts mapping) snapshotted onto the folio transaction at posting time. If omitted, the property's default mapping is applied. - `generalLedgerCustomCode` string, nullable: General Ledger custom code, snapshotted onto the folio transaction at posting time. If omitted, the property's default mapping is applied. - `taxes` TaxSchema[]: Tax rows for this line. Each row identifies a configured tax by exactly one of `externalId` / `taxId`; unmatched values are rejected. - `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. - `fees` FeeSchema[]: Fee amounts for this line. Each row identifies a configured fee by exactly one of `externalId` / `feeId`; unmatched values are rejected. - `externalId` string, nullable: The partner-owned identifier configured on the fee under the property's fee settings (a 3rd-party reference the property has associated with one of its Cloudbeds fees). Required unless `feeId` is sent. Must resolve to an active fee on the property; unknown or inactive values are rejected with FEE_NOT_FOUND. - `feeId` string, nullable, required: Cloudbeds identifier of the fee, as returned in `feeID` by getTaxesAndFees. Required unless `externalId` is sent. This identifier is not permanent: when the property edits the fee, Cloudbeds replaces it with a new identifier. A previous identifier is still accepted and is recorded as sent, against the version of the fee it names. A deleted fee is rejected with FEE_NOT_FOUND. Use `externalId` when you need a reference that stays the same across edits. - `amount` string, nullable, required: Fee amount applied to this item. Decimal string in major units of the property currency. - `taxes` TaxSchema[]: Taxes applied to this fee (tax-on-fee). Each row identifies a configured tax by exactly one of `externalId` / `taxId`; unmatched values are rejected with 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. - `discounts` CheckItemDiscountRequestSchema[]: Discounts applied to this line. The line's amount is reduced by their total and each is appended to the line's note; they do not post separate negative lines. A discount covering the whole check belongs in the check-level `discounts[]`. - `amount` string, nullable, required: Discount amount as a positive value in the property currency. It is subtracted from the line's amount. The combined discounts on a line may not exceed that line's amount. - `name` string, required: Human-readable label. Appended to the line's note so the reduction is explained on the folio. - `code` string, required: Partner-supplied code identifying the discount (e.g. promotion or coupon code). - `note` string, nullable: Optional free-text note. - `modifiers` CheckItemModifierRequestSchema[]: Modifier options selected for this product line. - `modifierOptionId` string, required: Modifier option identifier - `quantity` integer: How many times the option is applied per item unit - `details` ProductDetailsSchema, required: Marker base for the polymorphic `details` block on a check item. Concrete shape is selected by the sibling `type` field — see CheckItemRequestSchema.details. - `sku` string, nullable, required: Partner-supplied SKU for the item. Required — used as the catalog dedup key and recorded on the folio line for cross-reference. - `categoryName` string, nullable: Category name as classified by the POS (e.g., 'Food', 'Beverage', 'Alcohol'). Used for reporting and item classification. - `subReservationId` string, nullable: Sub-reservation identifier. If provided, this item 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 item in the request carries a subReservationId, the item 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 items, need an explicit identifier on each item for room attribution. Has no effect when the request-level target is houseAccountId or eventCode. - `gratuities` GratuitySchema[]: Optional list of gratuities on the check. Each entry becomes its own folio line item and its own Accounting Service transaction. Use multiple entries when both AUTO_GRATUITY (system-applied) and TIP (voluntary) are present, or when several servers each receive a tip. Embedded gratuities use GratuitySchema (without posContext) — POS context (checkNumber, restaurantName, revenueCenter, mealPeriod, staffReference) is inherited from this parent check. - `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}). - `serviceCharge` CheckServiceChargeRequestSchema: Service charge associated with the check. Posted as a distinct folio line item, separate from items[] and gratuity. Reported and routed independently from food/beverage revenue. - `amount` string, nullable, required: Service charge amount in the property currency. - `taxes` TaxSchema[]: Tax rows applied to the service charge. Each row references a property-configured tax by ID. Schema reused from the Gratuity domain. - `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. - `customTransactionCode` string, nullable: Override the property's default service-charge Custom Transaction Code for this posting. If omitted, the property's configured default applies. - `generalLedgerCustomCode` string, nullable: Override the property's default service-charge General Ledger code for this posting. If omitted, the property's configured default applies. - `note` string, nullable: Optional free-text note attached to the service charge line item. - `discounts` CheckDiscountRequestSchema[]: Optional discounts applied to the check. Each entry becomes a distinct (negative) folio line item. - `amount` string, nullable, required: Discount amount as a positive value in the property currency. Cloudbeds posts it as a negative folio line. - `name` string, required: Human-readable label displayed on the folio line. - `code` string, required: Partner-supplied code identifying the discount (e.g., promotion or coupon code). - `note` string, nullable: Optional free-text note attached to the discount line item. - `payments` CheckPaymentRequestSchema[]: Optional payments to register against the check at posting time. If provided, payFullBalance is ignored. - `paymentType` string, required: Payment method type. Use the getPaymentMethods API to retrieve available payment methods for the property. - `amount` string, nullable, required: Payment amount in the property currency. - `cardType` string, nullable: Card type, when paymentType is a card. Optional. - `note` string, nullable: Optional payment note - `payFullBalance` boolean: If true, a cash payment is automatically registered for the full check total (items + taxes + fees + gratuity + service charge - discounts). Ignored when payments[] is provided. - object - `checkNumber` string, nullable: Partner-assigned check number visible on the customer receipt (e.g., POS terminal display number). Stored on each posted folio line and visible in the folio UI. Optional — when omitted, the server mints a Cloudbeds reference (cb-) and returns it in the response so the partner can echo it back. - `checkId` string, nullable: Partner-assigned durable external reference for the check (UUID or opaque string). Optional — when omitted, Cloudbeds generates one and returns it. Echoed on the response and used to void the check later. Must be unique among the property's active checks; a value released by a void can be reused. Letters, digits, and . _ ~ - only (addressed as a URL path segment for void). - `reservationId` string, nullable: Reservation identifier. Required if houseAccountId and eventCode are not provided. Per-item sub-reservation targeting is expressed via items[].subReservationId. - `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. - `roomId` string, nullable: Room identifier where the charge originated, when applicable. - `guestId` string, nullable: Guest identifier. Optional — used for guest-attributed POS reporting. - `guestName` string, nullable: Guest name as captured at the POS. Used when no guestId is provided. - `saleDate` string, nullable: Sale date in RFC 3339 format. If not provided, the current timestamp is used. A future saleDate produces a 'pending' transaction. - `posContext` PosContextSchema: POS source metadata for the request. restaurantName / revenueCenter / mealPeriod / staffReference describe the POS session that produced the request as a whole; they apply uniformly to every item (postCheck) or gratuity entry (postGratuity) in the same POST. - `restaurantName` string, nullable: Restaurant or outlet name. - `revenueCenter` string, nullable: Revenue center identifier. - `mealPeriod` string, nullable: Meal period (e.g., breakfast, lunch, dinner). - `staffReference` string, nullable: Free-text reference to a staff member or terminal in the source POS. - `coverCount` integer, nullable: Number of guests on the check. Used for per-cover F&B reporting. - `totals` CheckTotalsSchema: Partner-supplied check totals broken out by component. Used for two purposes: (1) totals-only postings — when items[] is empty, totalItems carries the items subtotal and the server posts a single synthetic items folio line; inline serviceCharge / discounts[] continue to write their own rows; (2) cross-validation — when items[] is also supplied, each total field cross-validates against the corresponding server-computed sum (items / SC / gratuity / discount / tax / fees). Mismatches surface as INVALID_TOTAL_MISMATCH with the failing component identified. totalTax / totalFee are cross-cutting aggregates: in items mode they cross-validate the sum across the whole check; in totals-only mode the partner amount routes to the per-property "Default POS tax" / "Default POS fee" catch-all catalog records (lazy-created), keeping the ledger invariant that every tax_id / fee_id reference resolves to a real row. - `totalItems` string, nullable, required: Items subtotal. Per item: amount + its taxes[] + its fees[] + the taxes on those fees — the nested fee-tax term is the one most often left out. When items[] is supplied alongside, this value must equal the server-computed subtotal within 1 minor unit per currency; a larger difference is rejected with INVALID_TOTAL_MISMATCH. When an item carries a discount this figure is the amount BEFORE that discount — the comparison runs on the items as sent, and the discount is applied afterwards, so a 20.00 item with a 5.00 discount is declared as 20.00 and posts 15.00. When items[] is empty, this is the gross figure the single synthesised line carries. Not a grand total — service charge, gratuity and discount have their own fields below. - `totalServiceCharge` string, nullable: Service-charge subtotal — serviceCharge.amount + sum(serviceCharge.taxes). Optional; cross-validates against the inline serviceCharge data ONLY when both are supplied. In totals-only mode without inline serviceCharge, this value is the partner-declared SC aggregate (validation deferred to the persistence layer). - `totalGratuity` string, nullable: Gratuity subtotal — sum(gratuities[].amount + gratuities[].taxes). Optional; accepted on the wire but server-side validation is deferred until the embedded-gratuity domain handling lands (today gratuities are accepted but not mapped to the domain payload). - `totalDiscount` string, nullable: Discount subtotal — sum(discounts[].amount), partner-supplied as a positive value. Optional; cross-validates against the inline discounts[] ONLY when both are supplied. In totals-only mode without inline discounts, this value is the partner-declared discount aggregate. - `totalTax` string, nullable: Total tax across the check — sum of every tax line (items[].taxes, items[].fees[].taxes, serviceCharge.taxes, gratuities[].taxes). Optional. When items[] is supplied, the partner value cross-validates against the server-computed sum (INVALID_TOTAL_MISMATCH on drift). In totals-only mode (items[] empty), the partner value is persisted as a single tax line on the synthetic POS-sale item, linked to the property's lazily-created "Default POS tax" catalog record. Zero or omitted skips the synthesis. - `totalFee` string, nullable: Total fees across the check — sum of items[].fees[].amount. Fees only attach to items in the postCheck data model, so the sum is items-scoped. Optional. Same items-mode cross-validation and totals-only synthesis semantics as totalTax, routed through the property's "Default POS fee" catalog record. Zero or omitted skips the synthesis. - `items` CheckItemRequestSchema[]: Line items on the check. Each line is posted as a regular folio item, not a Custom Item. At least one of items[] or totals must be supplied — when items[] is empty, totals is required, and the server posts a single folio line carrying totals.totalItems. - `type` 'PRODUCT', required: Discriminator selecting the kind of line — see CheckItemTypeEnum. - `name` string, required: Human-readable line name displayed on the folio (dish or beverage name). - `externalLineId` string, nullable: Optional partner-supplied identifier for this line occurrence on the check (the POS system's own line reference — e.g., Clover lineItem.id, Toast Selection.guid, Square line uid, or a per-check line sequence). Per line, not per unit: a quantity-2 line carries one reference. When provided, must be unique within this check's items[]; a duplicate is rejected with DUPLICATE_EXTERNAL_LINE_ID. When omitted, the line is stored with no reference — Cloudbeds does not generate one. Supplied values are echoed back on the response and on line events so the partner can correlate the posted line without storing any Cloudbeds identifier. - `quantity` integer, required: Number of units. Informational metadata only — not used for accounting math (amount is the line total, not price * quantity). - `price` string, nullable: Per-unit price. Optional informational metadata — recorded on the folio for display and reporting; not used for accounting math. amount is the financial source of truth for this line; when price is omitted, amount is used as the per-unit price on the folio row. Decimal string in major units of the property currency. - `amount` string, nullable, required: Total line amount — the financial source of truth for this line. The server posts this value to the folio without recomputing it from price * quantity. Decimal string in major units of the property currency. - `note` string, nullable: Optional free-text note for this line (modifier, allergen, special request). - `customTransactionCode` string, nullable: Custom Transaction Code (chart-of-accounts mapping) snapshotted onto the folio transaction at posting time. If omitted, the property's default mapping is applied. - `generalLedgerCustomCode` string, nullable: General Ledger custom code, snapshotted onto the folio transaction at posting time. If omitted, the property's default mapping is applied. - `taxes` TaxSchema[]: Tax rows for this line. Each row identifies a configured tax by exactly one of `externalId` / `taxId`; unmatched values are rejected. - `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. - `fees` FeeSchema[]: Fee amounts for this line. Each row identifies a configured fee by exactly one of `externalId` / `feeId`; unmatched values are rejected. - `externalId` string, nullable: The partner-owned identifier configured on the fee under the property's fee settings (a 3rd-party reference the property has associated with one of its Cloudbeds fees). Required unless `feeId` is sent. Must resolve to an active fee on the property; unknown or inactive values are rejected with FEE_NOT_FOUND. - `feeId` string, nullable, required: Cloudbeds identifier of the fee, as returned in `feeID` by getTaxesAndFees. Required unless `externalId` is sent. This identifier is not permanent: when the property edits the fee, Cloudbeds replaces it with a new identifier. A previous identifier is still accepted and is recorded as sent, against the version of the fee it names. A deleted fee is rejected with FEE_NOT_FOUND. Use `externalId` when you need a reference that stays the same across edits. - `amount` string, nullable, required: Fee amount applied to this item. Decimal string in major units of the property currency. - `taxes` TaxSchema[]: Taxes applied to this fee (tax-on-fee). Each row identifies a configured tax by exactly one of `externalId` / `taxId`; unmatched values are rejected with 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. - `discounts` CheckItemDiscountRequestSchema[]: Discounts applied to this line. The line's amount is reduced by their total and each is appended to the line's note; they do not post separate negative lines. A discount covering the whole check belongs in the check-level `discounts[]`. - `amount` string, nullable, required: Discount amount as a positive value in the property currency. It is subtracted from the line's amount. The combined discounts on a line may not exceed that line's amount. - `name` string, required: Human-readable label. Appended to the line's note so the reduction is explained on the folio. - `code` string, required: Partner-supplied code identifying the discount (e.g. promotion or coupon code). - `note` string, nullable: Optional free-text note. - `modifiers` CheckItemModifierRequestSchema[]: Modifier options selected for this product line. - `modifierOptionId` string, required: Modifier option identifier - `quantity` integer: How many times the option is applied per item unit - `details` ProductDetailsSchema, required: Marker base for the polymorphic `details` block on a check item. Concrete shape is selected by the sibling `type` field — see CheckItemRequestSchema.details. - `sku` string, nullable, required: Partner-supplied SKU for the item. Required — used as the catalog dedup key and recorded on the folio line for cross-reference. - `categoryName` string, nullable: Category name as classified by the POS (e.g., 'Food', 'Beverage', 'Alcohol'). Used for reporting and item classification. - `subReservationId` string, nullable: Sub-reservation identifier. If provided, this item 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 item in the request carries a subReservationId, the item 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 items, need an explicit identifier on each item for room attribution. Has no effect when the request-level target is houseAccountId or eventCode. - `gratuities` GratuitySchema[]: Optional list of gratuities on the check. Each entry becomes its own folio line item and its own Accounting Service transaction. Use multiple entries when both AUTO_GRATUITY (system-applied) and TIP (voluntary) are present, or when several servers each receive a tip. Embedded gratuities use GratuitySchema (without posContext) — POS context (checkNumber, restaurantName, revenueCenter, mealPeriod, staffReference) is inherited from this parent check. - `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}). - `serviceCharge` CheckServiceChargeRequestSchema: Service charge associated with the check. Posted as a distinct folio line item, separate from items[] and gratuity. Reported and routed independently from food/beverage revenue. - `amount` string, nullable, required: Service charge amount in the property currency. - `taxes` TaxSchema[]: Tax rows applied to the service charge. Each row references a property-configured tax by ID. Schema reused from the Gratuity domain. - `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. - `customTransactionCode` string, nullable: Override the property's default service-charge Custom Transaction Code for this posting. If omitted, the property's configured default applies. - `generalLedgerCustomCode` string, nullable: Override the property's default service-charge General Ledger code for this posting. If omitted, the property's configured default applies. - `note` string, nullable: Optional free-text note attached to the service charge line item. - `discounts` CheckDiscountRequestSchema[]: Optional discounts applied to the check. Each entry becomes a distinct (negative) folio line item. - `amount` string, nullable, required: Discount amount as a positive value in the property currency. Cloudbeds posts it as a negative folio line. - `name` string, required: Human-readable label displayed on the folio line. - `code` string, required: Partner-supplied code identifying the discount (e.g., promotion or coupon code). - `note` string, nullable: Optional free-text note attached to the discount line item. - `payments` CheckPaymentRequestSchema[]: Optional payments to register against the check at posting time. If provided, payFullBalance is ignored. - `paymentType` string, required: Payment method type. Use the getPaymentMethods API to retrieve available payment methods for the property. - `amount` string, nullable, required: Payment amount in the property currency. - `cardType` string, nullable: Card type, when paymentType is a card. Optional. - `note` string, nullable: Optional payment note - `payFullBalance` boolean: If true, a cash payment is automatically registered for the full check total (items + taxes + fees + gratuity + service charge - discounts). Ignored when payments[] is provided. - object - `checkNumber` string, nullable: Partner-assigned check number visible on the customer receipt (e.g., POS terminal display number). Stored on each posted folio line and visible in the folio UI. Optional — when omitted, the server mints a Cloudbeds reference (cb-) and returns it in the response so the partner can echo it back. - `checkId` string, nullable: Partner-assigned durable external reference for the check (UUID or opaque string). Optional — when omitted, Cloudbeds generates one and returns it. Echoed on the response and used to void the check later. Must be unique among the property's active checks; a value released by a void can be reused. Letters, digits, and . _ ~ - only (addressed as a URL path segment for void). - `reservationId` string, nullable: Reservation identifier. Required if houseAccountId and eventCode are not provided. Per-item sub-reservation targeting is expressed via items[].subReservationId. - `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. - `roomId` string, nullable: Room identifier where the charge originated, when applicable. - `guestId` string, nullable: Guest identifier. Optional — used for guest-attributed POS reporting. - `guestName` string, nullable: Guest name as captured at the POS. Used when no guestId is provided. - `saleDate` string, nullable: Sale date in RFC 3339 format. If not provided, the current timestamp is used. A future saleDate produces a 'pending' transaction. - `posContext` PosContextSchema: POS source metadata for the request. restaurantName / revenueCenter / mealPeriod / staffReference describe the POS session that produced the request as a whole; they apply uniformly to every item (postCheck) or gratuity entry (postGratuity) in the same POST. - `restaurantName` string, nullable: Restaurant or outlet name. - `revenueCenter` string, nullable: Revenue center identifier. - `mealPeriod` string, nullable: Meal period (e.g., breakfast, lunch, dinner). - `staffReference` string, nullable: Free-text reference to a staff member or terminal in the source POS. - `coverCount` integer, nullable: Number of guests on the check. Used for per-cover F&B reporting. - `totals` CheckTotalsSchema: Partner-supplied check totals broken out by component. Used for two purposes: (1) totals-only postings — when items[] is empty, totalItems carries the items subtotal and the server posts a single synthetic items folio line; inline serviceCharge / discounts[] continue to write their own rows; (2) cross-validation — when items[] is also supplied, each total field cross-validates against the corresponding server-computed sum (items / SC / gratuity / discount / tax / fees). Mismatches surface as INVALID_TOTAL_MISMATCH with the failing component identified. totalTax / totalFee are cross-cutting aggregates: in items mode they cross-validate the sum across the whole check; in totals-only mode the partner amount routes to the per-property "Default POS tax" / "Default POS fee" catch-all catalog records (lazy-created), keeping the ledger invariant that every tax_id / fee_id reference resolves to a real row. - `totalItems` string, nullable, required: Items subtotal. Per item: amount + its taxes[] + its fees[] + the taxes on those fees — the nested fee-tax term is the one most often left out. When items[] is supplied alongside, this value must equal the server-computed subtotal within 1 minor unit per currency; a larger difference is rejected with INVALID_TOTAL_MISMATCH. When an item carries a discount this figure is the amount BEFORE that discount — the comparison runs on the items as sent, and the discount is applied afterwards, so a 20.00 item with a 5.00 discount is declared as 20.00 and posts 15.00. When items[] is empty, this is the gross figure the single synthesised line carries. Not a grand total — service charge, gratuity and discount have their own fields below. - `totalServiceCharge` string, nullable: Service-charge subtotal — serviceCharge.amount + sum(serviceCharge.taxes). Optional; cross-validates against the inline serviceCharge data ONLY when both are supplied. In totals-only mode without inline serviceCharge, this value is the partner-declared SC aggregate (validation deferred to the persistence layer). - `totalGratuity` string, nullable: Gratuity subtotal — sum(gratuities[].amount + gratuities[].taxes). Optional; accepted on the wire but server-side validation is deferred until the embedded-gratuity domain handling lands (today gratuities are accepted but not mapped to the domain payload). - `totalDiscount` string, nullable: Discount subtotal — sum(discounts[].amount), partner-supplied as a positive value. Optional; cross-validates against the inline discounts[] ONLY when both are supplied. In totals-only mode without inline discounts, this value is the partner-declared discount aggregate. - `totalTax` string, nullable: Total tax across the check — sum of every tax line (items[].taxes, items[].fees[].taxes, serviceCharge.taxes, gratuities[].taxes). Optional. When items[] is supplied, the partner value cross-validates against the server-computed sum (INVALID_TOTAL_MISMATCH on drift). In totals-only mode (items[] empty), the partner value is persisted as a single tax line on the synthetic POS-sale item, linked to the property's lazily-created "Default POS tax" catalog record. Zero or omitted skips the synthesis. - `totalFee` string, nullable: Total fees across the check — sum of items[].fees[].amount. Fees only attach to items in the postCheck data model, so the sum is items-scoped. Optional. Same items-mode cross-validation and totals-only synthesis semantics as totalTax, routed through the property's "Default POS fee" catalog record. Zero or omitted skips the synthesis. - `items` CheckItemRequestSchema[]: Line items on the check. Each line is posted as a regular folio item, not a Custom Item. At least one of items[] or totals must be supplied — when items[] is empty, totals is required, and the server posts a single folio line carrying totals.totalItems. - `type` 'PRODUCT', required: Discriminator selecting the kind of line — see CheckItemTypeEnum. - `name` string, required: Human-readable line name displayed on the folio (dish or beverage name). - `externalLineId` string, nullable: Optional partner-supplied identifier for this line occurrence on the check (the POS system's own line reference — e.g., Clover lineItem.id, Toast Selection.guid, Square line uid, or a per-check line sequence). Per line, not per unit: a quantity-2 line carries one reference. When provided, must be unique within this check's items[]; a duplicate is rejected with DUPLICATE_EXTERNAL_LINE_ID. When omitted, the line is stored with no reference — Cloudbeds does not generate one. Supplied values are echoed back on the response and on line events so the partner can correlate the posted line without storing any Cloudbeds identifier. - `quantity` integer, required: Number of units. Informational metadata only — not used for accounting math (amount is the line total, not price * quantity). - `price` string, nullable: Per-unit price. Optional informational metadata — recorded on the folio for display and reporting; not used for accounting math. amount is the financial source of truth for this line; when price is omitted, amount is used as the per-unit price on the folio row. Decimal string in major units of the property currency. - `amount` string, nullable, required: Total line amount — the financial source of truth for this line. The server posts this value to the folio without recomputing it from price * quantity. Decimal string in major units of the property currency. - `note` string, nullable: Optional free-text note for this line (modifier, allergen, special request). - `customTransactionCode` string, nullable: Custom Transaction Code (chart-of-accounts mapping) snapshotted onto the folio transaction at posting time. If omitted, the property's default mapping is applied. - `generalLedgerCustomCode` string, nullable: General Ledger custom code, snapshotted onto the folio transaction at posting time. If omitted, the property's default mapping is applied. - `taxes` TaxSchema[]: Tax rows for this line. Each row identifies a configured tax by exactly one of `externalId` / `taxId`; unmatched values are rejected. - `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. - `fees` FeeSchema[]: Fee amounts for this line. Each row identifies a configured fee by exactly one of `externalId` / `feeId`; unmatched values are rejected. - `externalId` string, nullable: The partner-owned identifier configured on the fee under the property's fee settings (a 3rd-party reference the property has associated with one of its Cloudbeds fees). Required unless `feeId` is sent. Must resolve to an active fee on the property; unknown or inactive values are rejected with FEE_NOT_FOUND. - `feeId` string, nullable, required: Cloudbeds identifier of the fee, as returned in `feeID` by getTaxesAndFees. Required unless `externalId` is sent. This identifier is not permanent: when the property edits the fee, Cloudbeds replaces it with a new identifier. A previous identifier is still accepted and is recorded as sent, against the version of the fee it names. A deleted fee is rejected with FEE_NOT_FOUND. Use `externalId` when you need a reference that stays the same across edits. - `amount` string, nullable, required: Fee amount applied to this item. Decimal string in major units of the property currency. - `taxes` TaxSchema[]: Taxes applied to this fee (tax-on-fee). Each row identifies a configured tax by exactly one of `externalId` / `taxId`; unmatched values are rejected with 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. - `discounts` CheckItemDiscountRequestSchema[]: Discounts applied to this line. The line's amount is reduced by their total and each is appended to the line's note; they do not post separate negative lines. A discount covering the whole check belongs in the check-level `discounts[]`. - `amount` string, nullable, required: Discount amount as a positive value in the property currency. It is subtracted from the line's amount. The combined discounts on a line may not exceed that line's amount. - `name` string, required: Human-readable label. Appended to the line's note so the reduction is explained on the folio. - `code` string, required: Partner-supplied code identifying the discount (e.g. promotion or coupon code). - `note` string, nullable: Optional free-text note. - `modifiers` CheckItemModifierRequestSchema[]: Modifier options selected for this product line. - `modifierOptionId` string, required: Modifier option identifier - `quantity` integer: How many times the option is applied per item unit - `details` ProductDetailsSchema, required: Marker base for the polymorphic `details` block on a check item. Concrete shape is selected by the sibling `type` field — see CheckItemRequestSchema.details. - `sku` string, nullable, required: Partner-supplied SKU for the item. Required — used as the catalog dedup key and recorded on the folio line for cross-reference. - `categoryName` string, nullable: Category name as classified by the POS (e.g., 'Food', 'Beverage', 'Alcohol'). Used for reporting and item classification. - `subReservationId` string, nullable: Sub-reservation identifier. If provided, this item 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 item in the request carries a subReservationId, the item 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 items, need an explicit identifier on each item for room attribution. Has no effect when the request-level target is houseAccountId or eventCode. - `gratuities` GratuitySchema[]: Optional list of gratuities on the check. Each entry becomes its own folio line item and its own Accounting Service transaction. Use multiple entries when both AUTO_GRATUITY (system-applied) and TIP (voluntary) are present, or when several servers each receive a tip. Embedded gratuities use GratuitySchema (without posContext) — POS context (checkNumber, restaurantName, revenueCenter, mealPeriod, staffReference) is inherited from this parent check. - `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}). - `serviceCharge` CheckServiceChargeRequestSchema: Service charge associated with the check. Posted as a distinct folio line item, separate from items[] and gratuity. Reported and routed independently from food/beverage revenue. - `amount` string, nullable, required: Service charge amount in the property currency. - `taxes` TaxSchema[]: Tax rows applied to the service charge. Each row references a property-configured tax by ID. Schema reused from the Gratuity domain. - `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. - `customTransactionCode` string, nullable: Override the property's default service-charge Custom Transaction Code for this posting. If omitted, the property's configured default applies. - `generalLedgerCustomCode` string, nullable: Override the property's default service-charge General Ledger code for this posting. If omitted, the property's configured default applies. - `note` string, nullable: Optional free-text note attached to the service charge line item. - `discounts` CheckDiscountRequestSchema[]: Optional discounts applied to the check. Each entry becomes a distinct (negative) folio line item. - `amount` string, nullable, required: Discount amount as a positive value in the property currency. Cloudbeds posts it as a negative folio line. - `name` string, required: Human-readable label displayed on the folio line. - `code` string, required: Partner-supplied code identifying the discount (e.g., promotion or coupon code). - `note` string, nullable: Optional free-text note attached to the discount line item. - `payments` CheckPaymentRequestSchema[]: Optional payments to register against the check at posting time. If provided, payFullBalance is ignored. - `paymentType` string, required: Payment method type. Use the getPaymentMethods API to retrieve available payment methods for the property. - `amount` string, nullable, required: Payment amount in the property currency. - `cardType` string, nullable: Card type, when paymentType is a card. Optional. - `note` string, nullable: Optional payment note - `payFullBalance` boolean: If true, a cash payment is automatically registered for the full check total (items + taxes + fees + gratuity + service charge - discounts). Ignored when payments[] is provided. ## Response `201` Check successfully posted. The response includes the public checkId (for downstream void/reversal) and the resolved checkNumber. - PostCheckResponseSchema - `data` PostedCheckResponseSchema, required: Result of a postCheck call. checkId is the public, partner-addressable handle for the posted check — use it for downstream void/reversal. - `checkNumber` string, required: Resolved receipt-visible check number — either the partner-supplied value from the request, or a server-minted Cloudbeds reference (cb-) when the partner omitted it. Always returned so the partner can echo it back. - `checkId` string, required: Public, partner-addressable check identifier (accept-or-generate): the value the partner supplied, or a Cloudbeds-generated handle when omitted. Use it to address the check for void via DELETE /folio/v1/checks/{checkId}. Always returned. - `items` PostedCheckItemResponseSchema[], required: Per-line echo of the accepted items[], position-matched to the request items[] (entry i describes request line i) — each entry carries back the partner-supplied externalLineId, or null where the line supplied none, so the caller can correlate posted lines to its own POS line ids without storing any Cloudbeds identifier. Empty for totals-only postings. - `externalLineId` string, nullable, required: The partner-supplied line reference accepted on items[].externalLineId, echoed verbatim — null when the line was posted without one. Address this value (with the check's checkId) in any future line-scoped operation such as a partial refund or partial void. - `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, invalid parameters, validation failures, or unmatched tax/fee IDs. See CheckErrorCodeEnumSchema for the structured error codes returned in the body. - `403`: Forbidden — insufficient permissions on the requested property. - `404`: Not found — reservation, house account, group, or folio not found. - `409`: Conflict — see CheckErrorCodeEnumSchema for the structured codes: IDEMPOTENCY_KEY_REUSED (Idempotency-Key header reused with a different payload), DUPLICATE_CHECK_ID (an active check on the property already has this checkId), PRODUCT_NAME_CONFLICT (line's name collides with an existing active product that has a different SKU). - `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)