--- schema_version: "1" id: 8f3657b2b17cb5d54a89fa78873480f2fcb6574d0db3381f2c70da35d5618208 title: Inventory Management API collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/inventory-management-api.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/inventory-management-api source_site: developer.salesforce.com content_type: documentation content_hash: 2b8af85206e4e6d77fac419500491e9634b253299683bf6dd45fe6992e1bc44b products: - Point of Sale for Developers - Salesforce APIs --- Inventory Management API # Inventory Management API [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-management-api/inventory-management-api-oas-public.yaml) Merchant API to manage inventory in the POS system. **Version:** 2.3.4 ## Tags ### Inventory Management API [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-management-api/inventory-management-api-oas-public.yaml) Merchant API to manage inventory in the POS system. ## Operations ### PUT Cancel cycle count. `PUT /merchant/{version}/ims/inventory/cyclecount/cancel` Operation ID: `cancelCycleCount`. Tags: Inventory Management API. Cancel the specified cycle count. **Note:** Provide version as v1. #### Parameters * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `CycleCountCancelRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `CycleCountCancelResponse`. ### POST Create IMS ASN. `POST /merchant/{version}/ims/inventory/asn` Operation ID: `createASN`. Tags: Inventory Management API. Create an ASN in the IMS system. #### Parameters * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `AdvanceShippingNotice`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `PSResponse`. ### POST Create full cycle count. `POST /merchant/{version}/ims/inventory/cyclecount/full` Operation ID: `createFullCycleCount`. Tags: Inventory Management API. Create a full cycle count. The complete inventory of products in a store can only be counted through a full cycle count. **Note:** Provide version as v1. #### Parameters * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `FullCycleCountRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `CycleCountResponse`. ### POST Create manual cycle count. `POST /merchant/{version}/ims/inventory/cyclecount/manual` Operation ID: `createManualCycleCount`. Tags: Inventory Management API. Create a manual cycle count. The manual cycle count allows counting of a specific set of products. **Note:** Provide version as v1. #### Parameters * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `ManualCycleCountRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `CycleCountResponse`. ### POST Create partial cycle count. `POST /merchant/{version}/ims/inventory/cyclecount/partial` Operation ID: `createPartialCycleCount`. Tags: Inventory Management API. Create a partial cycle count. Cycle count for a particular group of products that fall within a selected category, brand, or any other product attribute that is provided in the request. **Note:** Provide version as v1. #### Parameters * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `PartialCycleCountRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `CycleCountResponse`. ## Schemas ### CycleCountCancelRequest * `cycleCountId` (_integer (int64)_) Cycle count ID which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel. Example: `10001`. * `externalReferenceId` (_string_) External cycle count which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel. Example: `spring-2023`. * `storeId` (_string_, required) Store ID corresponding to cycle count being canceled. Example: `001`. ### CycleCountCancelResponse * `cycleCountId` (_integer (int64)_) Cycle count ID which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel. Example: `10001`. * `externalReferenceId` (_string_) External cycle count which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel. Example: `spring-2023`. * `storeId` (_string_, required) Store ID corresponding to cycle count being canceled. Example: `001`. * `errorMessage` (_string_, read-only) If the cycle count request fails, a detailed error message is provided. * `errorCode` (_string_, read-only) If the cycle count request fails, an error code is provided. Allowed values: `CYCLE_COUNT_ERROR`. ### AdvanceShippingNotice * `id` (_string_, required) ID of the entity being transferred. * `status` (_string_) Transfer status. Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`. * `description` (_string_) Transfer description. * `processedBy` (_string_) Processed by ID. * `receivedBy` (_string_) Received by ID. * `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch. * `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch. * `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet). * `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer. * `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer. * `trackingNumber` (_string_, nullable) Item level tracking number. * `asnType` (_string_) ASN Type. Allowed values: `ORIGINAL`, `CANCELLATION`, `CANCEL_REISSUE`, `UNKNOWN`. * `shipmentId` (_string_) An identifier for the shipment referenced in the ASN. * `shippedTimestamp` (_integer (int64)_) The time that the shipment was shipped represented as milliseconds since epoch. * `shipment` (_Shipment_, required) * `lastProcessedById` (_string_, required) ID for the person or entity who processed this inventory transfer. * `lastProcessedByName` (_string_, required) Name for the person/entity who processed this inventory transfer. * `createdOn` (_string_) Inventory transfer created date. ### PSResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `error` (_boolean_) ### FullCycleCountRequest * `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed. Example: `001`. * `name` (_string_, required) Logical name for this cycle count. Example: `Spring 2020 cycle count`. * `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC. Example: `2011-12-18T10:15:30+01:00`. * `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself. Allowed values: `CORPORATE`, `STORE`. * `description` (_string_) Detailed description for the cycle count. Example: `Spring 2020 cycle count to be completed before 4/30`. * `cycleCountStatus` (_string_, required, read-only) 1. **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress. Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`. * `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created. Example: `10001`. * `externalReferenceId` (_string_) External cycle count or batch ID. Example: `spring-2023`. ### CycleCountResponse * `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed. Example: `001`. * `name` (_string_, required) Logical name for this cycle count. Example: `Spring 2020 cycle count`. * `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC. Example: `2011-12-18T10:15:30+01:00`. * `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself. Allowed values: `CORPORATE`, `STORE`. * `description` (_string_) Detailed description for the cycle count. Example: `Spring 2020 cycle count to be completed before 4/30`. * `cycleCountStatus` (_string_, required, read-only) 1. **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress. Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`. * `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created. Example: `10001`. * `externalReferenceId` (_string_) External cycle count or batch ID. Example: `spring-2023`. * `errorMessage` (_string_, read-only) If the cycle count request fails, a detailed error message is provided. * `errorCode` (_string_, read-only) If the cycle count request fails, an error code is provided. Allowed values: `CYCLE_COUNT_ERROR`. ### ManualCycleCountRequest * `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed. Example: `001`. * `name` (_string_, required) Logical name for this cycle count. Example: `Spring 2020 cycle count`. * `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC. Example: `2011-12-18T10:15:30+01:00`. * `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself. Allowed values: `CORPORATE`, `STORE`. * `description` (_string_) Detailed description for the cycle count. Example: `Spring 2020 cycle count to be completed before 4/30`. * `cycleCountStatus` (_string_, required, read-only) 1. **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress. Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`. * `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created. Example: `10001`. * `externalReferenceId` (_string_) External cycle count or batch ID. Example: `spring-2023`. * `productIds` (_array of string_, required) List of product IDs applicable for manual cycle count for specific products. Each item: Product ID applicable for manual cycle count. ### PartialCycleCountRequest * `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed. Example: `001`. * `name` (_string_, required) Logical name for this cycle count. Example: `Spring 2020 cycle count`. * `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC. Example: `2011-12-18T10:15:30+01:00`. * `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself. Allowed values: `CORPORATE`, `STORE`. * `description` (_string_) Detailed description for the cycle count. Example: `Spring 2020 cycle count to be completed before 4/30`. * `cycleCountStatus` (_string_, required, read-only) 1. **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress. Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`. * `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created. Example: `10001`. * `externalReferenceId` (_string_) External cycle count or batch ID. Example: `spring-2023`. * `criteria` (_PartialCycleCountCriteria_, required) ### Reason Reason for returning the item. * `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT. Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64. * `reasonCode` (_string_, required) Reason code. Maximum length: 64. * `reasonText` (_string_, nullable) Reason text. Maximum length: 256. ### Shipment Shipment details. * `poNumber` (_string_) Purchase Order Number. * `uploadNumber` (_string_) Unique identifier for the upload batch, used to group related corporate transfers. * `shipFrom` (_IMSAddress_) * `shipTo` (_IMSAddress_, required) * `orders` (_array of Order_, required) List of orders contained in the shipment. ### PartialCycleCountCriteria Partial cycle count is done on the products which satisfy the selection criteria. The selection criteria is based on any one of the product attributes. * `attribute` (_string_, required, write-only) A product attribute used to determine the products that require cycle count. POS product has multiple attributes like brand, category, color, size, etc. Refer to the create product API (POST /merchant/{version}/products). Note: To utilize any product attribute, it must first be included in the product feed. Example: `brand`. * `values` (_array of string_, required, write-only) List of values corresponding to the attribute. The values must match those provided in the product feed. Each item: Value corresponding to the attribute. The value must match those provided in the product feed. Items: Example: `[Rolex,Timex]`. Example: `[Rolex,Timex]`. ### IMSAddress IMS-specific address format for inventory management and fulfillment operations. Used for shipFrom and shipTo locations in ASN shipments. * `locationId` (_string_) Location identifier. * `locationType` (_string_) Type of location (e.g., warehouse, store, distribution center). * `name` (_string_) Primary location name. * `additionalName` (_string_) Additional location name or identifier. * `streetAddress1` (_string_) Street address line 1. * `streetAddress2` (_string_) Street address line 2. * `city` (_string_) City. * `state` (_string_) State or province. * `postalCode` (_string_) Postal or ZIP code. * `country` (_string_) Country. ### Order List of orders contained in the shipment. * `id` (_string_, required) ID of the entity being transferred. * `status` (_string_) Transfer status. Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`. * `description` (_string_) Transfer description. * `processedBy` (_string_) Processed by ID. * `receivedBy` (_string_) Received by ID. * `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch. * `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch. * `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet). * `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer. * `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer. * `trackingNumber` (_string_, nullable) Item level tracking number. * `pallets` (_array of Pallet_, required) List of pallets contained in the order. ### Pallet List of pallets contained in the order. * `id` (_string_, required) ID of the entity being transferred. * `status` (_string_) Transfer status. Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`. * `description` (_string_) Transfer description. * `processedBy` (_string_) Processed by ID. * `receivedBy` (_string_) Received by ID. * `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch. * `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch. * `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet). * `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer. * `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer. * `trackingNumber` (_string_, nullable) Item level tracking number. * `cartons` (_array of Carton_, required) List of cartons contained in the pallet. ### Carton List of cartons contained in the pallet. * `id` (_string_, required) ID of the entity being transferred. * `status` (_string_) Transfer status. Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`. * `description` (_string_) Transfer description. * `processedBy` (_string_) Processed by ID. * `receivedBy` (_string_) Received by ID. * `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch. * `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch. * `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet). * `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer. * `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer. * `trackingNumber` (_string_, nullable) Item level tracking number. * `items` (_array of IMSInventoryProduct_, required) * `hasSerializedProduct` (_boolean_) App uses this boolean to determine the receiving of the entire pallet or carton. * `cartonShipments` (_array of Shipment_) List of box shipments contained in the carton. ### IMSInventoryProduct Specific to inventory product. * `id` (_string_, required) ID of the entity being transferred. * `status` (_string_) Transfer status. Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`. * `description` (_string_) Transfer description. * `processedBy` (_string_) Processed by ID. * `receivedBy` (_string_) Received by ID. * `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch. * `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch. * `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet). * `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer. * `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer. * `trackingNumber` (_string_, nullable) Item level tracking number. * `productTitle` (_string_) Product title. * `productImageUrl` (_string_) Product image URL. * `color` (_string_) Product color. * `size` (_string_) Product size. * `gtin` (_string_) Product UPC code. * `vendorNumber` (_string_) Product vendor number. * `quantity` (_integer (int32)_, required) Product quantity being transferred. Minimum: 1. * `quantityTransferred` (_integer (int32)_) Actual product quantity transferred. * `quantityReceived` (_integer (int32)_) Actual product quantity received. * `serialNumberedItems` (_array of ClearanceItem_) * `fullPriceSerialNumbers` (_array of string_) Serial numbers. * `removedSerialNumbers` (_array of string_) Removed serial numbers. This is for the backend to remove serial numbers from the database. * `serialNumberRequired` (_boolean_) Serial number required. * `scannedSerialNumbers` (_array of string_) Scanned serial numbers. * `externalDocNumber` (_string_) External Doc Number. * `externalLineNumber` (_string_) External Line Number. * `itemHierarchyId` (_string_) Item hierarchy ID inside a container. * `costPrice` (_number (double)_) Cost price of each item. * `casePackQuantity` (_integer (int32)_) Quantity of item per case pack. * `casePackID` (_string_) ID of case packed products. * `inventoryTransferDetailId` (_string_) When a user manually adds an item to transfer, the backend allocates a UUID to the field and returns it in the response. For all subsequent calls from the app, the same UUID is provided in the request and is used by the backend to determine whether to update or insert the item. * `salesPrice` (_number_) Sales price of the product. * `shipper` (_string_) Carrier name, for example, FedEx or UPS. ### ClearanceItem Product location within the store. * `serialNumber` (_string_) Serial number of the item (if applicable). * `clearancePrice` (_number_) * `itemLocationWithinStore` (_string_) * `instructionText` (_string_)