---
schema_version: "1"
id: cbcca125a8cc06971f443c563dcf6c8cec82da1dddd6b040187a132039cec9c8
title: Inventory Lists
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/inventory-lists.md
canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/inventory-lists
source_site: developer.salesforce.com
content_type: documentation
content_hash: 51310546b5b7d556f316181a8d348433063693f794fb5a3cebd89e6ff8ea8ef6
products:
  - B2C Commerce API
  - Salesforce APIs
---
Inventory Lists

# Inventory Lists

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/inventory-lists/inventory-lists-oas-v1-public.yaml)

## API Overview

The Inventory Lists API provides comprehensive management capabilities for product inventory records within inventory lists. Use this API to:

*   Retrieve current inventory information for products.
*   Create and update inventory records with allocation and availability data.
*   Manage pre-order and backorder configurations.
*   Track stock levels, turnover, and available-to-sell (ATS) quantities.
*   Configure perpetual stock for always-available products.
*   Handle custom inventory attributes.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

The API client must also have at least one of the following OAuth scopes: `sfcc.inventory-lists` scope for read-only operations and `sfcc.inventory-lists.rw` for modifications.

You must include the relevant scope(s) in the client ID used to generate the token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)

### Key Concepts

#### Product Inventory Record

A product inventory record represents the inventory information for a specific product within an inventory list. Each record contains:

*   Product identification: Product ID and name
*   Stock information: Current stock level, ATS quantity, turnover
*   Allocation: Quantity allocated for sale and reset date
*   Availability dates: Expected in-stock dates
*   Pre-order/backorder handling: Configuration for products not currently in stock
*   Custom attributes: Extensible with custom properties (c\_\* fields)

#### Inventory List

An inventory list is a container for product inventory records. Each inventory list is identified by a unique ID and can contain multiple product inventory records.

#### Available to Sell (ATS)

ATS represents the quantity of items available for purchase. It is calculated as:

```
ATS = Allocation + PreOrderBackOrderAllocation - InventoryTurnover
```

#### Stock Level

Stock level represents the current physical inventory. It is calculated as:

```
Stock Level = Allocation - InventoryTurnover
```

#### Inventory Turnover

Inventory turnover is the sum of all inventory transactions (both increments and decrements) recorded since the allocation reset date. This value can be negative if there are more decrements than increments.

#### Perpetual Stock

Products with the perpetual flag set to `true` are treated as always available, regardless of actual stock levels. This is useful for:

*   Digital products
*   Made-to-order items
*   Products with unlimited availability

#### Pre-order and Backorder Handling

This API supports three modes for handling products that are not currently in stock:

*   **none**: No pre-order or backorder capability
*   **preorder**: Product can be ordered before it becomes available
*   **backorder**: Product can be ordered when temporarily out of stock

### Use Cases

#### Availability & Monitoring

*   Verify product stock status and calculated fields (such as ATS) before displaying items to shoppers.
*   Monitor current stock levels, allocation, and turnover history to determine replenishment needs.

#### Lifecycle Management

*   Perform the first-time setup for new products or execute a complete inventory reset/replacement.
*   Modify specific fields—such as in-stock dates, pre-order/backorder settings, or perpetual stock flags—without affecting the rest of the record.
*   Adjust specific allocation amounts dynamically as stock moves.
*   Permanently remove records for discontinued products or obsolete entries during list reorganization.

### Best Practices

#### Inventory Updates

1.  Use PATCH for partial updates: When only updating specific fields, use PATCH to avoid accidentally clearing other data.
2.  Monitor concurrent updates: Handle 409 Conflict responses appropriately when multiple systems update the same record.
3.  Validate allocations: Ensure allocation amounts are non-negative.
4.  Reset dates: Update the allocation reset date when resetting inventory to accurately track turnover.

#### Stock Management

1.  Regular synchronization: Keep inventory records synchronized with your inventory management system.
2.  ATS monitoring: Monitor ATS values to ensure products don't oversell.
3.  Turnover tracking: Use turnover data to understand inventory movement patterns.
4.  Perpetual stock usage: Use perpetual stock flag only for appropriate product types.

#### Pre-order and Backorder

1.  Clear handling mode: Set appropriate pre-order/backorder handling based on product availability strategy.
2.  Allocation planning: Use preOrderBackOrderAllocation to control how many pre-orders or backorders are accepted.
3.  In-stock dates: Provide accurate in-stock dates for pre-order items to set customer expectations.

#### Security and Access Control

1.  Read vs. Write access: Use `sfcc.inventory-lists` scope for read-only operations and `sfcc.inventory-lists.rw` for modifications.
2.  Organization context: Scope all operations to an organization to ensure proper data isolation.
3.  Global scope: Perform inventory operations at the global level, not site level.

### Custom Attributes

The Product Inventory Record schema supports custom attributes using the `c_*` naming convention. These attributes allow you to extend the standard inventory model with custom business logic and data.

**Example custom attributes:**

*   `c_supplierCode`: Track supplier information.
*   `c_warehouseLocation`: Store warehouse location data.
*   `c_minimumOrderQuantity`: Define minimum order quantities.
*   `c_leadTime`: Track expected lead times.

### Rate Limiting

For load shedding and rate limiting information, see [Load Shedding and Rate Limiting.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/throttle-rates.html)

### Related APIs

*   Products API: Manage product catalog information.
*   Inventory Availability API: Query real-time inventory availability across locations.
*   Inventory Reservation API: Reserve inventory for orders.
*   Orders API: Process orders with inventory allocation.

**Version:** 1.1.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/product/inventory-lists/v1`
    *   `shortCode (default shortCode)`

## Security

*   `AmOAuth2` (oauth2)
    
    Account Manager OAuth 2.0 security scheme for admin APIs.
    
    Use the Account Manager to obtain access tokens for making API calls. The scope determines the level of access to inventory list resources.
    
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dw/oauth2/access\_token)
    *   Scope sfcc.inventory-lists: \[object Object\]
    *   Scope sfcc.inventory-lists.rw: \[object Object\]

## Operations

### GET Get a product inventory record.

`GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId}`

Operation ID: `getProductInventoryRecord`. Security: AmOAuth2 (sfcc.inventory-lists, sfcc.inventory-lists.rw).

Get a product inventory record by product ID and inventory list ID.

Only product inventory records that exist are returned. The response includes:

*   Current stock levels and availability (ATS)
*   Allocation information
*   Pre-order and backorder handling configuration
*   Custom attributes

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.
*   `productId` (path, ProductId, required) The product ID
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    

#### Responses

*   **200** Product inventory record retrieved successfully.
    
    Media type: `application/json`. Schema: `ProductInventoryRecord`.
    
    _Example: ProductInventoryRecordResponse_ Product inventory record retrieved successfully.
    
    Example of a successful product inventory record retrieval
    
    ```
    {
      "productId": "P1234567890",
      "productName": "Sample Product",
      "inventoryListId": "inventory-list-001",
      "perpetualFlag": false,
      "allocation": {
        "amount": 100,
        "resetDate": "2024-01-15T10:00:00.000Z"
      },
      "inStockDate": "2024-02-01T00:00:00.000Z",
      "ats": 95,
      "stockLevel": 95,
      "quantityOnOrder": 5,
      "inventoryTurnover": 5,
      "preOrderBackOrderHandling": "none",
      "preOrderBackOrderAllocation": 0,
      "c_customField": "custom value"
    }
    ```
    
    _Example: ProductInventoryRecordPerpetual_ Product inventory record with perpetual stock
    
    Example of a product inventory record set to always be in stock
    
    ```
    {
      "productId": "P9999999999",
      "productName": "Always Available Product",
      "inventoryListId": "inventory-list-001",
      "perpetualFlag": true,
      "ats": 999999,
      "stockLevel": 999999,
      "quantityOnOrder": 0,
      "inventoryTurnover": 0,
      "preOrderBackOrderHandling": "none",
      "preOrderBackOrderAllocation": 0
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Your access token is invalid or expired and can’t be used to identify a user."
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Your access token is valid, but you don’t have the required permissions to access the resource."
    }
    ```
    
*   **404** Not Found. The specified product inventory record or inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ProductInventoryRecordNotFound_ Product Inventory Record Not Found
    
    The specified product inventory record does not exist.
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-inventory-record-not-found",
      "title": "Product Inventory Record Not Found",
      "detail": "Product inventory record with product ID 'P1234567890' in inventory list 'inventory-list-001' was not found.",
      "productId": "P1234567890",
      "inventoryListId": "inventory-list-001"
    }
    ```
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/inventory-list-not-found",
      "title": "Inventory List Not Found",
      "detail": "Inventory list with ID 'inventory-list-001' was not found.",
      "inventoryListId": "inventory-list-001"
    }
    ```
    

### PUT Create or replace a product inventory record.

`PUT /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId}`

Operation ID: `createOrUpdateProductInventoryRecord`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Create a new product inventory record or replace an existing one using the information provided.

When replacing an existing record, the record is replaced with the information provided in the request.

The `preOrderBackOrderHandling` parameter defaults to "none" if not specified.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.
*   `productId` (path, ProductId, required) The product ID

#### Request body (required)

The product inventory record

Media type: `application/json`. Schema: `ProductInventoryRecord`.

_Example: CreateProductInventoryRecordRequest_ Create a new product inventory record.

Example of creating a new product inventory record with allocation

```
{
  "productId": "P1234567890",
  "inventoryListId": "inventory-list-001",
  "perpetualFlag": false,
  "allocation": {
    "amount": 100,
    "resetDate": "2024-01-15T10:00:00.000Z"
  },
  "inStockDate": "2024-02-01T00:00:00.000Z",
  "preOrderBackOrderHandling": "none",
  "preOrderBackOrderAllocation": 0
}
```

_Example: EnablePerpetualStock_ Enable perpetual stock.

Example of setting a product to always be in stock

```
{
  "productId": "P1234567890",
  "perpetualFlag": true
}
```

#### Responses

*   **200** Product inventory record updated successfully.
    
    Media type: `application/json`. Schema: `ProductInventoryRecord`.
    
    _Example: ProductInventoryRecordUpdated_ Product inventory record updated successfully.
    
    Example of a successfully updated product inventory record
    
    ```
    {
      "productId": "P1234567890",
      "productName": "Sample Product",
      "inventoryListId": "inventory-list-001",
      "perpetualFlag": false,
      "allocation": {
        "amount": 150,
        "resetDate": "2024-01-20T10:00:00.000Z"
      },
      "inStockDate": "2024-02-15T00:00:00.000Z",
      "ats": 145,
      "stockLevel": 145,
      "quantityOnOrder": 5,
      "inventoryTurnover": 5,
      "preOrderBackOrderHandling": "preorder",
      "preOrderBackOrderAllocation": 50
    }
    ```
    
*   **201** Product inventory record created successfully.
    
    Media type: `application/json`. Schema: `ProductInventoryRecord`.
    
    _Example: ProductInventoryRecordCreated_ Product inventory record created successfully.
    
    Example of a successfully created product inventory record
    
    ```
    {
      "productId": "P1234567890",
      "productName": "New Product",
      "inventoryListId": "inventory-list-001",
      "perpetualFlag": false,
      "allocation": {
        "amount": 100,
        "resetDate": "2024-01-15T10:00:00.000Z"
      },
      "inStockDate": "2024-02-01T00:00:00.000Z",
      "ats": 100,
      "stockLevel": 100,
      "quantityOnOrder": 0,
      "inventoryTurnover": 0,
      "preOrderBackOrderHandling": "none",
      "preOrderBackOrderAllocation": 0
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

### DELETE Delete a product inventory record.

`DELETE /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId}`

Operation ID: `deleteProductInventoryRecord`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Delete a product inventory record by product ID and inventory list ID.

This operation permanently removes the inventory record. Once deleted, the record cannot be recovered unless recreated using the PUT operation.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.
*   `productId` (path, ProductId, required) The product ID

#### Responses

*   **204** Product inventory record deleted successfully. No content returned.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified product inventory record or inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ProductInventoryRecordNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Product Inventory Record Not Found
    
    The specified product inventory record does not exist.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: ProductInventoryRecordNotFound_ Product Inventory Record Not Found
    
    The specified product inventory record does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

### PATCH Update a product inventory record.

`PATCH /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId}`

Operation ID: `updateProductInventoryRecord`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Update the product inventory record with the specified information.

Only the fields provided in the request body are updated. All other fields are unchanged. This is useful for partial updates such as adjusting allocation or changing pre-order/backorder handling.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.
*   `productId` (path, ProductId, required) The product ID

#### Request body (required)

The product inventory record to be updated and the fields to update

Media type: `application/json`. Schema: `ProductInventoryRecord`.

_Example: UpdateProductInventoryRecordRequest_ Update an existing product inventory record.

Example of updating allocation and stock information

```
{
  "productId": "P1234567890",
  "allocation": {
    "amount": 150,
    "resetDate": "2024-01-20T10:00:00.000Z"
  },
  "perpetualFlag": false,
  "inStockDate": "2024-02-15T00:00:00.000Z",
  "preOrderBackOrderHandling": "preorder",
  "preOrderBackOrderAllocation": 50
}
```

_Example: UpdateAllocationOnly_ Update only the allocation information.

Example of updating only the allocation amount

```
{
  "productId": "P1234567890",
  "allocation": {
    "amount": 200
  }
}
```

#### Responses

*   **200** Product inventory record updated successfully.
    
    Media type: `application/json`. Schema: `ProductInventoryRecord`.
    
    _Example ProductInventoryRecordUpdated: same as PUT /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 200 response._ Product inventory record updated successfully.
    
    Example of a successfully updated product inventory record
    
    _Example: ProductInventoryRecordUpdated_ Product inventory record updated successfully.
    
    Example of a successfully updated product inventory record
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified product inventory record or inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ProductInventoryRecordNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Product Inventory Record Not Found
    
    The specified product inventory record does not exist.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: ProductInventoryRecordNotFound_ Product Inventory Record Not Found
    
    The specified product inventory record does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

### GET Get an inventory list.

`GET /organizations/{organizationId}/inventory-lists/{inventoryListId}`

Operation ID: `getInventoryList`. Security: AmOAuth2 (sfcc.inventory-lists, sfcc.inventory-lists.rw).

Get an inventory list by ID.

Returns the inventory list configuration including:

*   Description
*   Default in-stock behavior
*   Bundle inventory settings
*   On-order inventory settings
*   Creation and last modified dates
*   Assigned sites (computed)

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    

#### Responses

*   **200** Inventory list retrieved successfully.
    
    Media type: `application/json`. Schema: `InventoryList`.
    
    _Example: InventoryListResponse_ Inventory list retrieved successfully.
    
    Example of a successful inventory list retrieval
    
    ```
    {
      "id": "inventory-list-001",
      "description": "Main inventory list for warehouse A",
      "defaultInStock": false,
      "useBundleInventoryOnly": false,
      "onOrderInventoryEnabled": false,
      "creationDate": "2024-01-10T08:00:00.000Z",
      "lastModified": "2024-01-15T10:30:00.000Z",
      "assignedSites": [
        "SiteGenesis",
        "SiteGenesis US"
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

### PUT Create or replace an inventory list.

`PUT /organizations/{organizationId}/inventory-lists/{inventoryListId}`

Operation ID: `createOrUpdateInventoryList`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Create a new inventory list or replace an existing one using the information provided.

When replacing an existing list, the list is replaced with the information provided in the request.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.

#### Request body (required)

The inventory list

Media type: `application/json`. Schema: `InventoryList`.

_Example: CreateInventoryListRequest_ Create a new inventory list.

Example of creating a new inventory list with configuration

```
{
  "id": "inventory-list-001",
  "description": "Main inventory list for warehouse A",
  "defaultInStock": false,
  "useBundleInventoryOnly": false,
  "onOrderInventoryEnabled": false
}
```

#### Responses

*   **200** Inventory list updated successfully.
    
    Media type: `application/json`. Schema: `InventoryList`.
    
    _Example: InventoryListUpdated_ Inventory list updated successfully.
    
    Example of a successfully updated inventory list
    
    ```
    {
      "id": "inventory-list-001",
      "description": "Updated inventory list for warehouse A",
      "defaultInStock": true,
      "useBundleInventoryOnly": false,
      "onOrderInventoryEnabled": true,
      "creationDate": "2024-01-10T08:00:00.000Z",
      "lastModified": "2024-02-01T14:00:00.000Z",
      "assignedSites": [
        "SiteGenesis",
        "SiteGenesis US"
      ]
    }
    ```
    
*   **201** Inventory list created successfully.
    
    Media type: `application/json`. Schema: `InventoryList`.
    
    _Example: InventoryListCreated_ Inventory list created successfully.
    
    Example of a successfully created inventory list
    
    ```
    {
      "id": "inventory-list-001",
      "description": "Main inventory list for warehouse A",
      "defaultInStock": false,
      "useBundleInventoryOnly": false,
      "onOrderInventoryEnabled": false,
      "creationDate": "2024-01-10T08:00:00.000Z",
      "lastModified": "2024-01-10T08:00:00.000Z",
      "assignedSites": []
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    

### DELETE Delete an inventory list.

`DELETE /organizations/{organizationId}/inventory-lists/{inventoryListId}`

Operation ID: `deleteInventoryList`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Delete an inventory list by ID.

This operation permanently removes the inventory list. Once deleted, the list cannot be recovered unless recreated using the PUT operation.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.

#### Responses

*   **204** Inventory list deleted successfully. No content returned.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

### PATCH Update an inventory list.

`PATCH /organizations/{organizationId}/inventory-lists/{inventoryListId}`

Operation ID: `updateInventoryList`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Update the inventory list with the specified information.

Only the fields provided in the request body are updated. All other fields are unchanged. This is useful for partial updates such as changing default in-stock behavior or enabling on-order inventory.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.

#### Request body (required)

The inventory list fields to update

Media type: `application/json`. Schema: `InventoryList`.

_Example: UpdateInventoryListRequest_ Update an existing inventory list.

Example of updating inventory list configuration

```
{
  "id": "inventory-list-001",
  "description": "Updated inventory list for warehouse A",
  "defaultInStock": true,
  "onOrderInventoryEnabled": true
}
```

#### Responses

*   **200** Inventory list updated successfully.
    
    Media type: `application/json`. Schema: `InventoryList`.
    
    _Example InventoryListUpdated: same as PUT /organizations/{organizationId}/inventory-lists/{inventoryListId} 200 response._ Inventory list updated successfully.
    
    Example of a successfully updated inventory list
    
    _Example: InventoryListUpdated_ Inventory list updated successfully.
    
    Example of a successfully updated inventory list
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### Select

The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).

Type: `string`.

Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`.

### ProductInventoryRecord

Product inventory record

*   `productId` (_ProductId_, required)
*   `productName` (_string_) The name of the product  
    Maximum length: 256. Example: `Sample Product`.
*   `inventoryListId` (_string_) The user-supplied ID of the inventory list.  
    Maximum length: 256. Example: `inventory-list-001`.
*   `perpetualFlag` (_boolean_) The flag that determines if the product is perpetually in stock.  
    Example: `false`.
*   `allocation` (_ProductInventoryRecordAllocation_)
*   `inStockDate` (_string (date-time)_) The date that the item is expected to be in stock.  
    Example: `2024-02-01T00:00:00.000Z`.
*   `ats` (_number (double)_, read-only) The quantity of items available to sell (ATS). This is calculated as the allocation plus the preorderBackorderAllocation minus the turnover.  
    Example: `95`.
*   `stockLevel` (_number (double)_, read-only) The current stock level. This is calculated as the allocation minus the turnover.  
    Example: `95`.
*   `quantityOnOrder` (_number (double)_, read-only) The on order quantity, which is the quantity of all transactions for this record since the allocation reset date.  
    Example: `5`.
*   `inventoryTurnover` (_number (double)_, read-only) The sum of all inventory transactions (decrements and increments) that have been recorded subsequent to the allocation reset date. The value can be negative in the case of a higher quantity of inventory decrements than increments.  
    Example: `5`.
*   `preOrderBackOrderHandling` (_PreorderBackorderHandling_)
*   `preOrderBackOrderAllocation` (_number (double)_) The quantity of items that are allocated for sale, beyond the initial stock allocation.  
    Example: `0`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### InventoryList

Inventory list resource

*   `id` (_string_, required) The user-supplied ID of the inventory list.  
    Maximum length: 256. Example: `inventory-list-001`.
*   `description` (_string_) The user-supplied description of this inventory list.  
    Maximum length: 4000. Example: `Main inventory list for warehouse A`.
*   `defaultInStock` (_boolean_) True if the default for products in the inventory list is to be in stock. The default value is false if not specified.  
    Example: `false`.
*   `useBundleInventoryOnly` (_boolean_) True if the inventory list is used in bundle inventory only. The default value is false if not specified.  
    Example: `false`.
*   `onOrderInventoryEnabled` (_boolean_) True if the on-order flag is enabled. The default value is false if not specified.  
    Example: `false`.
*   `creationDate` (_string (date-time)_, read-only) The date and time the inventory list was created.  
    Example: `2024-01-10T08:00:00.000Z`.
*   `lastModified` (_string (date-time)_, read-only) The date and time the inventory list was last modified.  
    Example: `2024-01-15T10:30:00.000Z`.
*   `assignedSites` (_array of string_, read-only) The list of site display names or site Ids this inventory list is assigned to. This is a computed attribute and cannot be directly modified.  
    Items: Maximum length: 256. Example: `SiteGenesis`.
    
    _Example_
    
    ```
    [
      "SiteGenesis",
      "SiteGenesis US"
    ]
    ```
    

### ProductInventoryRecordAllocation

Product inventory record allocation

*   `amount` (_number (double)_) The allocation quantity that is currently set. The quantity unit matches the product unit.  
    Minimum: 0. Example: `100`.
*   `resetDate` (_string (date-time)_) The date the allocation quantity was initialized or reset.  
    Example: `2024-01-15T10:00:00.000Z`.

### PreorderBackorderHandling

The enum holding the records' configuration before backorder handling. Possible values are:

*   `none` - No pre-order or backorder handling
*   `preorder` - Product available for pre-order
*   `backorder` - Product available for backorder

Type: `string`.

Allowed values: `none`, `preorder`, `backorder`. Example: `none`.