CLcloudbeds
Checks

Post 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). Items posted via this endpoint are recorded as regular folio items, not Custom Items, and are tagged as POS-originated for UI differentiation.

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

Headers

x-property-idstring required
Example:1,2,3

A numeric, comma-separated string representing the property IDs, sent in the header.

Idempotency-Keystring required
Example:req-2026-05-05-2047-9b3f

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, which means a check under this key is already stored. The account target is validated before the replay, so a retry whose target has since become invalid (e.g. RESERVATION_CHECKED_OUT) gets that error rather than the original posting. Absent, empty, or whitespace-only → 400.

Request body

OR
OR

Example request

{
  "checkNumber": "2047",
  "checkId": "8f2c1e3a-9b6d-4f1e-9d2a-3b6c0a1f7e51",
  "reservationId": "RES123456",
  "houseAccountId": "HA-99812",
  "eventCode": "GRP2026",
  "folioId": "12345",
  "roomId": "ROOM-204",
  "guestId": "GST-77123",
  "guestName": "Jane Smith",
  "saleDate": "2026-05-05T20:30:00-04:00",
  "posContext": {
    "restaurantName": "Sunset Grill",
    "revenueCenter": "BAR",
    "mealPeriod": "dinner",
    "staffReference": "server-014"
  },
  "coverCount": 4,
  "totals": {
    "totalItems": "24.30",
    "totalServiceCharge": "24.30",
    "totalGratuity": "24.30",
    "totalDiscount": "24.30",
    "totalTax": "24.30",
    "totalFee": "24.30"
  },
  "items": [
    {
      "type": "PRODUCT",
      "name": "Cheeseburger",
      "externalLineId": "ABC8903421",
      "quantity": 2,
      "price": "20.00",
      "amount": "20.00",
      "note": "No onions",
      "customTransactionCode": "FOOD-REVENUE",
      "generalLedgerCustomCode": "GL-4100",
      "taxes": [
        {
          "externalId": "tax_state_va_8",
          "taxId": "29486",
          "amount": "1.60"
        }
      ],
      "fees": [
        {
          "externalId": "fee_resort_daily",
          "feeId": "9804",
          "amount": "2.50",
          "taxes": [
            {
              "externalId": "tax_state_va_8",
              "taxId": "29486",
              "amount": "1.60"
            }
          ]
        }
      ],
      "discounts": [
        {
          "amount": "5.00",
          "name": "Happy Hour 20%",
          "code": "HAPPY_HOUR",
          "note": "Manager comp"
        }
      ],
      "modifiers": [
        {
          "modifierOptionId": "970011",
          "quantity": 1
        }
      ],
      "details": {
        "sku": "SKU-CHEESE-001",
        "categoryName": "Food",
        "subReservationId": "SUB123"
      }
    }
  ],
  "gratuities": [
    {
      "amount": "8.00",
      "taxes": [
        {
          "externalId": "tax_state_va_8",
          "taxId": "29486",
          "amount": "1.60"
        }
      ],
      "note": "Tip for Maria",
      "customTransactionCode": "GRT-VIP",
      "generalLedgerCustomCode": "GL-2410",
      "subReservationId": "SUB123",
      "recipient": {
        "userId": "usr_4821",
        "email": "maria.santos@cloudbeds.com",
        "name": "Maria Santos"
      },
      "gratuityId": "partner-grat-7a3f"
    }
  ],
  "serviceCharge": {
    "amount": "5.40",
    "taxes": [
      {
        "externalId": "tax_state_va_8",
        "taxId": "29486",
        "amount": "1.60"
      }
    ],
    "customTransactionCode": "SVC-CHRG-VIP",
    "generalLedgerCustomCode": "GL-2410",
    "note": "20% mandatory service charge"
  },
  "discounts": [
    {
      "amount": "5.00",
      "name": "Happy Hour 20%",
      "code": "HAPPY_HOUR",
      "note": "Manager comp"
    }
  ],
  "payments": [
    {
      "paymentType": "cash",
      "amount": "24.30",
      "cardType": "visa",
      "note": "Paid at checkout"
    }
  ]
}

Response

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

Example response

{
  "data": {
    "checkNumber": "2047",
    "checkId": "CHK-9911283",
    "items": [
      {
        "externalLineId": "ABC8903421"
      }
    ],
    "notice": "Duplicate Idempotency-Key — returning original posting."
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.