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

## Request

- Base URL: `https://api.cloudbeds.com`
- URL: `https://api.cloudbeds.com/item/v1/items`
- Auth: OAuth 2
  - Authorization code: `https://api.cloudbeds.com/auth/oauth/authorize`
  - Token URL: `https://api.cloudbeds.com/auth/oauth/token` scopes: `write:item`

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 eventCode are not provided.
    - `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.
    - `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 plus selected modifier options 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.
      - `modifiers` ItemModifierRequestSchema[]: Modifier options selected for this item.
        - `modifierOptionId` string, required: Modifier option identifier
        - `quantity` integer: How many times the option is applied per item unit
  - object
    - `reservationId` string, nullable: Reservation identifier. Required if houseAccountId and eventCode are not provided.
    - `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.
    - `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 plus selected modifier options 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.
      - `modifiers` ItemModifierRequestSchema[]: Modifier options selected for this item.
        - `modifierOptionId` string, required: Modifier option identifier
        - `quantity` integer: How many times the option is applied per item unit
  - object
    - `reservationId` string, nullable: Reservation identifier. Required if houseAccountId and eventCode are not provided.
    - `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.
    - `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 plus selected modifier options 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.
      - `modifiers` ItemModifierRequestSchema[]: Modifier options selected for this item.
        - `modifierOptionId` string, required: Modifier option identifier
        - `quantity` integer: How many times the option is applied per item unit

## 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.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)