Post a completed POS check (e.g., F&B) to a guest folio, house account, or group profile

post

https://api.cloudbeds.com/folio/v1/checks

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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Check details: account target, line items, optional gratuities, service charge, discounts and payments.

checkNumber

string | null

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 | null

Partner-assigned durable external reference for the check (UUID or opaque string). Distinct from referenceID — used to correlate the check across systems regardless of retries. Letters, digits, and . _ ~ - only (addressed as a URL path segment for void).

reservationId

string | null

required

Reservation identifier. Required if houseAccountId and groupCode are not provided. Per-item sub-reservation targeting is expressed via items[].subReservationId.

houseAccountId

string | null

House account identifier. Required if reservationId and groupCode are not provided.

groupCode

string | null

Group code. Required if reservationId and houseAccountId are not provided.

folioId

string | null

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 | null

Room identifier where the charge originated, when applicable.

guestId

string | null

Guest identifier. Optional — used for guest-attributed POS reporting.

guestName

string | null

Guest name as captured at the POS. Used when no guestId is provided.

saleDate

string | null

Sale date in RFC 3339 format. If not provided, the current timestamp is used. A future saleDate produces a 'pending' transaction.

posContext

Optional POS source metadata for the check (restaurant, revenue center, meal period, staff reference). Inherited by every gratuity, item, and service charge posted as part of this request — embedded gratuities therefore omit their own posContext.

coverCount

integer | null

Number of guests on the check. Used for per-cover F&B reporting.

totals

Optional partner-supplied totals. Required when items[] is empty (totals-only posting). When supplied alongside items[], the server validates itemsSubtotal against the computed sum and rejects with INVALID_TOTAL_MISMATCH if they disagree (tolerance: 1 minor unit per currency).

items

array of objects

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.itemsSubtotal.

items

gratuities

array of objects

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.

gratuities

serviceCharge

Optional service charge for the check. Posted as a separate folio line item, distinct from gratuity.

discounts

array of objects

Optional discounts applied to the check. Each entry becomes a distinct (negative) folio line item.

discounts

payments

array of objects

Optional payments to register against the check at posting time. If provided, itemPaid is ignored.

payments

itemPaid

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.

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

Language

Credentials

OAuth2

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Check successfully posted. The response includes the public checkId (for downstream void/reversal) and the resolved checkNumber.

400Bad 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.

403Forbidden — insufficient permissions on the requested property.

404Not found — reservation, house account, group, or folio not found.

409Conflict — see CheckErrorCodeEnumSchema for the structured codes: IDEMPOTENCY_KEY_REUSED (Idempotency-Key header reused with a different payload), PRODUCT_NAME_CONFLICT (line's name collides with an existing active product that has a different SKU).

500Internal server error.