---
title: "Post one or more items to a reservation, house account, or group profile"
method: POST
path: "/item/v1/items"
tags: ["Items"]
---

# Post one or more items to a reservation, house account, or group profile

`POST /item/v1/items`

Adds items to a reservation, house account, or group profile. This endpoint supports batch operations, allowing multiple items to be posted in a single request. Each item can have associated payments and custom pricing.

## Headers

- `x-property-id` string, required

## Request body

- union
  - object
    - `reservationId` string, nullable, required — Reservation identifier. Required if houseAccountId and groupCode are not provided.
    - `houseAccountId` string, nullable — House account identifier. Required if reservationId and groupCode are not provided.
    - `groupCode` string, nullable — Group code. Required if reservationId and houseAccountId are not provided.
    - `saleDate` string, nullable — Sale date in RFC 3339 format. If not provided, current timestamp will be used.
    - `items` ItemRequestSchema[], required — Array of items to post (minimum 1 item required)
      - `itemId` string, required — Item identifier
      - `itemQuantity` integer, required — Item quantity (must be greater than 0)
      - `itemPrice` string, nullable — Custom item price in the smallest currency unit (e.g., cents for USD). If not provided, the item's registered price will be used. For example, $10.50 should be sent as '1050'.
      - `itemNote` string, nullable — Optional item note
      - `subReservationId` string, nullable — Sub-reservation identifier (optional)
      - `payments` PaymentRequestSchema[] — Optional list of payments for this item. If provided, itemPaid is ignored.
        - `paymentType` string, required — Payment method type. Use getPaymentMethods API to retrieve available payment methods for the property.
        - `amount` string, required — Payment amount in the smallest currency unit (e.g., cents for USD). For example, $10.50 should be sent as '1050'.
        - `notes` string, nullable — Optional payment notes
      - `itemPaid` boolean — If true, a cash payment will be automatically registered for the total value of the item including taxes and fees. Ignored if payments array is provided.
  - object
    - `reservationId` string, nullable — Reservation identifier. Required if houseAccountId and groupCode are not provided.
    - `houseAccountId` string, nullable, required — House account identifier. Required if reservationId and groupCode are not provided.
    - `groupCode` string, nullable — Group code. Required if reservationId and houseAccountId are not provided.
    - `saleDate` string, nullable — Sale date in RFC 3339 format. If not provided, current timestamp will be used.
    - `items` ItemRequestSchema[], required — Array of items to post (minimum 1 item required)
      - `itemId` string, required — Item identifier
      - `itemQuantity` integer, required — Item quantity (must be greater than 0)
      - `itemPrice` string, nullable — Custom item price in the smallest currency unit (e.g., cents for USD). If not provided, the item's registered price will be used. For example, $10.50 should be sent as '1050'.
      - `itemNote` string, nullable — Optional item note
      - `subReservationId` string, nullable — Sub-reservation identifier (optional)
      - `payments` PaymentRequestSchema[] — Optional list of payments for this item. If provided, itemPaid is ignored.
        - `paymentType` string, required — Payment method type. Use getPaymentMethods API to retrieve available payment methods for the property.
        - `amount` string, required — Payment amount in the smallest currency unit (e.g., cents for USD). For example, $10.50 should be sent as '1050'.
        - `notes` string, nullable — Optional payment notes
      - `itemPaid` boolean — If true, a cash payment will be automatically registered for the total value of the item including taxes and fees. Ignored if payments array is provided.
  - object
    - `reservationId` string, nullable — Reservation identifier. Required if houseAccountId and groupCode are not provided.
    - `houseAccountId` string, nullable — House account identifier. Required if reservationId and groupCode are not provided.
    - `groupCode` string, nullable, required — Group code. Required if reservationId and houseAccountId are not provided.
    - `saleDate` string, nullable — Sale date in RFC 3339 format. If not provided, current timestamp will be used.
    - `items` ItemRequestSchema[], required — Array of items to post (minimum 1 item required)
      - `itemId` string, required — Item identifier
      - `itemQuantity` integer, required — Item quantity (must be greater than 0)
      - `itemPrice` string, nullable — Custom item price in the smallest currency unit (e.g., cents for USD). If not provided, the item's registered price will be used. For example, $10.50 should be sent as '1050'.
      - `itemNote` string, nullable — Optional item note
      - `subReservationId` string, nullable — Sub-reservation identifier (optional)
      - `payments` PaymentRequestSchema[] — Optional list of payments for this item. If provided, itemPaid is ignored.
        - `paymentType` string, required — Payment method type. Use getPaymentMethods API to retrieve available payment methods for the property.
        - `amount` string, required — Payment amount in the smallest currency unit (e.g., cents for USD). For example, $10.50 should be sent as '1050'.
        - `notes` string, nullable — Optional payment notes
      - `itemPaid` boolean — If true, a cash payment will be automatically registered for the total value of the item including taxes and fees. Ignored if payments array is provided.

## Response `201`

Items successfully posted

- PostItemsResponseSchema
  - `data` PostedItemResponseSchema[], required — Array of posted item results, one for each item in the request
    - `soldProductId` string, required — Sold product identifier (can be used to void this product in the future)
    - `externalRelationId` string, required — External relation ID (same as sold product ID). Together with external relation kind (ITEM) it can be used to get transaction from Accounting API
    - `transactionStatus` 'pending' | 'completed', nullable — Transaction status. Returns 'pending' when sale date is in the future, 'completed' otherwise.
    - `remainingItemQuantity` integer, nullable — Remaining number of items in stock (only returned if item has stock inventory tracking enabled)
    - `reorderNeeded` boolean, nullable — Whether item is at or below the reorder threshold (only returned if item has stock inventory tracking enabled)
    - `stopSellMet` boolean, nullable — Whether item is at or below the stop-sell threshold (only returned if item has stock inventory tracking enabled)

## Other responses

- `400` — Bad request - invalid parameters or validation errors
- `403` — Forbidden - insufficient permissions
- `404` — Not found - reservation, house account, or group not found
- `500` — Internal server error

---

[API](https://skmtc.net/cloudbeds/apis/cloudbeds-api.md) · [All operations](https://skmtc.net/cloudbeds/apis/cloudbeds-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cloudbeds/cloudbeds-api/revisions/2faa857793e8/schema)