Vacatia API Catalog
/
Cloudbeds API
/
Item

Cloudbeds API (v1.2)

Welcome to the documentation for Cloudbeds API Version v1.2! If you are looking to learn how to use the Cloudbeds API to access guest information, reservations, or similar data for your Cloudbeds customers, then you've come to the right place.

In this document you will find all the API methods we provide along with explanations for parameters and response examples.

If you have questions about different implementation steps (e.g. how to implement OAuth 2.0), please refer to our Integrations Portal.

Be sure to subscribe to the monthly Cloudbeds API announcement mailing list to receive information on new additions and improvements to the Cloudbeds API and related developer tools.

Endpoint: https://api.cloudbeds.com/api/v1.2/{method}

HTTPS: Our API requires HTTPS. We'll respond with an appropriate error if you're not using it.

Request Format: HTTP GET, POST and PUT (Content-Type: application/x-www-form-urlencoded)

Response Format: JSON

Response Header: X-Request-ID is added to response headers in all calls to help accelerate support and troubleshooting.

Run in Postman use this link to access our Public collection in Postman.

Download OpenAPI description
cloudbeds.json
cloudbeds.yaml
Languages
Servers
Mock server
https://tbg-api-docs.vacatia.com/_mock/cloudbeds/
https://api.cloudbeds.com/api/v1.2/

Authentication

Operations

Adjustment

Operations

AllotmentBlocks

Operations

AppSettings

Operations

Currency

Operations

CustomFields

Operations

Dashboard

Operations

Emails

Operations

Groups

Operations

Guest

Operations

Hotel

Operations

HouseAccount

Operations

Housekeeping

Operations

Integration

Operations

Invoices

Operations

Item

Operations

getItem

Request

Gets the details for the one itemID
1 only if data.stockInventory = true
2 Taxes, fees and totals will show up only if an item has assigned tax or fee.

Query
propertyIDstring

Property ID

itemIDstringrequired

Item identifier

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getItem?itemID=string&propertyID=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataobject

Item details

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": {
    "itemID": "string",
    "itemType": "product",
    "sku": "string",
    "itemCode": "string",
    "name": "string",
    "categoryID": "string",
    "categoryName": "string",
    "description": "string",
    "price": 0,
    "stockInventory": true,
    "itemQuantity": 0,
    "reorderThreshold": 0,
    "reorderNeeded": true,
    "stopSell": 0,
    "stopSellMet": true,
    "taxes": [ … ],
    "totalTaxes": 0,
    "fees": [ … ],
    "totalFees": 0,
    "priceWithoutFeesAndTaxes": 0,
    "grandTotal": 0
  },
  "message": "string"
}

putItemToInventory

Request

Updates an item with information provided
¹ only if item.stockInventory = true

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

itemIDstring

Item identifier

itemNamestring or null

Item name

itemTypestring or null

Item type

Enum"product""service"
itemSKUstring or null

Item SKU. Will be generated if not set

itemCodestring or null

Item code

itemDescriptionstring or null

Item description

itemPricenumber or null

Item price

stockInventoryboolean or null

Track stock inventory for this item

itemQuantityinteger or null

¹ Current amount of item available

reorderThresholdinteger or null

¹ Quantity at which to reorder item

stopSellMetboolean or null

¹ true - Whether item is at or below value set for stop-sell threshold.

stopSellinteger or null

¹ Quantity at which to stop selling product.

curl -i -X PUT \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/putItemToInventory \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d itemID=string \
  -d itemName=string \
  -d itemType=product \
  -d itemSKU=string \
  -d itemCode=string \
  -d itemDescription=string \
  -d itemPrice=0 \
  -d stockInventory=true \
  -d itemQuantity=0 \
  -d reorderThreshold=0 \
  -d stopSellMet=true \
  -d stopSell=0

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "message": "string"
}

getItems

Request

Gets all the items and their prices the hotel has created in myfrontdesk
1 only if data.stockInventory = true
2 Taxes, fees and totals will show up only if an item has assigned tax or fee.

Query
propertyIDstring

Property ID

itemCategoryIDstring

Category identifier

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getItems?itemCategoryID=string&propertyID=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects

Item details

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "message": "string"
}

getItemCategories

Request

Gets the item category list

Query
propertyIDstring

Property ID

curl -i -X GET \
  'https://tbg-api-docs.vacatia.com/_mock/cloudbeds/getItemCategories?propertyID=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects

Categories details

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "message": "string"
}

postItemCategory

Request

Adds new items category

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

categoryNamestring

Category name

categoryCodestring or null

Category code

itemIDArray of integers or null

Existing ItemIDs to reassign to new category

categoryColorstring or null

Category color (like #3b7be7)

Default "#ccc"
curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postItemCategory \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d categoryName=string \
  -d categoryCode=string \
  -d itemID=0 \
  -d 'categoryColor=#ccc'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

categoryIDstring or null

Category unique identifier (if success = true)

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "categoryID": "string",
  "message": "string"
}

postItemsToInventory

Request

Adds new items batch
¹ only if item.stockInventory = true

Bodyapplication/x-www-form-urlencoded
itemobject

Items

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postItemsToInventory \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d 'item[propertyID]=string' \
  -d 'item[itemName]=string' \
  -d 'item[categoryID]=string' \
  -d 'item[itemType]=product' \
  -d 'item[itemSKU]=string' \
  -d 'item[itemCode]=string' \
  -d 'item[itemDescription]=string' \
  -d 'item[itemPrice]=0' \
  -d 'item[stockInventory]=false' \
  -d 'item[itemQuantity]=0' \
  -d 'item[reorderThreshold]=0' \
  -d 'item[stopSellMet]=false' \
  -d 'item[stopSell]=0'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataArray of objects

Sold product details

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": [
    { … }
  ],
  "message": "string"
}

postItem

Request

Adds an item either to a reservation or to a house account.

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

reservationIDstring or null

Reservation identifier. Required if no houseAccountID or groupCode is provided.

houseAccountIDstring or null

House account identifier. Required if no reservationID or groupCode is provided.

groupCodestring or null

Group identifier. Required if no reservationID or houseAccountID is provided.

subReservationIDstring or null

Sub Reservation identifier.

itemIDstring

Item identifier

itemQuantityinteger

Items quantity

itemPricestring or null

Item price, if not sent, items registered price will be used

itemNotestring or null

Item note

itemPaidboolean or null

If the item is already paid. Note: If set to true, a payment in cash will be registered for the total value of the item, taxes and fees. If this is not the expected behavior, set to false, and register the operation manually. If payments is set, itemPaid is ignored.

Default false
saleDatestring or null(date-time)

posting date

Default "current_timestamp"
paymentsArray of objects or null

list of payments If the item is already paid

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postItem \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d houseAccountID=string \
  -d groupCode=string \
  -d subReservationID=string \
  -d itemID=string \
  -d itemQuantity=0 \
  -d itemPrice=string \
  -d itemNote=string \
  -d itemPaid=false \
  -d saleDate=current_timestamp \
  -d 'payments=[object Object]'

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataobject

Sold product details

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "data": {
    "soldProductID": "string",
    "transactionID": "string",
    "transactionStatus": "string",
    "remainingItemQuantity": 0,
    "reorderNeeded": true,
    "stopSellMet": true
  },
  "message": "string"
}

postCustomItem

Request

Adds single, or multiple, custom items and their associated payments to a Reservation or House Account as a single transaction.

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

reservationIDstring or null

Reservation identifier. Required if no houseAccountID or groupCode is provided.

houseAccountIDstring or null

House account identifier. Required if no reservationID or groupCode is provided.

groupCodestring or null

Group identifier. Required if no reservationID or houseAccountID is provided.

referenceIDstring or null

partner's transaction reference. If exist then Cloudbeds will prevent adding of duplicates

subReservationIDstring or null

Sub Reservation identifier

roomIDstring or null

Room identifier (Ignored if subReservationID exist)

itemsArray of objects

list of items will be posted

saleDatestring or null(date-time)

posting date

Default "current_timestamp"
guestIDstring or null

Guest identifier

guestNamestring or null

(Ignored if guestID exist)

paymentsArray of objects or null

list of payments If the item is already paid

itemPaidboolean or null

If the item is already paid. Note: If set to true, a payment in cash will be registered for the total value of the item, taxes and fees. If this is not the expected behavior, set to false, and register the operation manually. (Ignored if payments array exist)

Default false
curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postCustomItem \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d houseAccountID=string \
  -d groupCode=string \
  -d referenceID=string \
  -d subReservationID=string \
  -d roomID=string \
  -d 'items=[object Object]' \
  -d saleDate=current_timestamp \
  -d guestID=string \
  -d guestName=string \
  -d 'payments=[object Object]' \
  -d itemPaid=false

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataobject

Sold product details

Response
application/json
{
  "success": true,
  "data": {
    "soldProductID": "string",
    "transactionID": "string",
    "notice": "string"
  }
}

appendCustomItem

Request

Append single, or multiple, custom items and their associated payments to a existing one in a Reservation.

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

reservationIDstring

Reservation identifier. Required if no houseAccountID is provided.

referenceIDstring

partner's transaction reference. If exist then Cloudbeds will prevent adding of duplicates

subReservationIDstring or null

Sub Reservation identifier

roomIDstring or null

Room identifier (Ignored if subReservationID exist)

itemsArray of objects

list of items will be posted

saleDatestring or null(date-time)

posting date

Default "current_timestamp"
guestIDstring or null

Guest identifier

guestNamestring or null

(Ignored if guestID exist)

paymentsArray of objects or null

list of payments If the item is already paid

itemPaidboolean or null

If the item is already paid. Note: If set to true, a payment in cash will be registered for the total value of the item, taxes and fees. If this is not the expected behavior, set to false, and register the operation manually. (Ignored if payments array exist)

Default false
curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/appendCustomItem \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d referenceID=string \
  -d subReservationID=string \
  -d roomID=string \
  -d 'items=[object Object]' \
  -d saleDate=current_timestamp \
  -d guestID=string \
  -d guestName=string \
  -d 'payments=[object Object]' \
  -d itemPaid=false

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

dataobject

Sold product details

Response
application/json
{
  "success": true,
  "data": {
    "soldProductID": "string",
    "transactionID": "string"
  }
}

postVoidItem

Request

Voids the itemID transaction on the specified Reservation ID or House Account ID. If payments were sent in calls postItem or postCustomItem, they will be deleted too.

Bodyapplication/x-www-form-urlencoded
propertyIDstring or null

Property ID

reservationIDstring

Reservation identifier. reservationID or houseAccountID are necessary.

houseAccountIDstring

House Account identifier. reservationID or houseAccountID are necessary.

soldProductIDstring

Item identifier

curl -i -X POST \
  https://tbg-api-docs.vacatia.com/_mock/cloudbeds/postVoidItem \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d propertyID=string \
  -d reservationID=string \
  -d houseAccountID=string \
  -d soldProductID=string

Responses

200 Response

Bodyapplication/json
successboolean

Returns if the request could be completed

messagestring or null

To be used in case any error occurs (if success = false). If success = true, it does not exist.

Response
application/json
{
  "success": true,
  "message": "string"
}

Package

Operations

Payment

Operations

Rate

Operations

Reservation

Operations

Room

Operations

Taxes and Fees

Operations

User

Operations