--- schema_version: "1" id: ddad9bd61a566a9f8a256cb50b5ee844681f2734c35f8aba56751fba253575f4 title: Product 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/product-management-api.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/product-management-api source_site: developer.salesforce.com content_type: documentation content_hash: c587ac6c2ebb31a43071587c7c631f7b2dbb91c78080efd8861eb50514f10c25 products: - Point of Sale for Developers - Salesforce APIs --- Product Management API # Product Management API [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/product-management-api/product-management-api-oas-public.yaml) POS Merchant API to perform CRUD operations on Product objects in the POS system. The APIs do not support field mapping and transformation logic available in CMS. **Version:** 2.3.4 ## Tags ### Product Management API [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/product-management-api/product-management-api-oas-public.yaml) POS Merchant API to perform CRUD operations on Product objects in the POS system. The APIs do not support field mapping and transformation logic available in CMS. ## Operations ### PUT Update products. `PUT /merchant/{version}/products` Operation ID: `updateProducts`. Tags: Product Management API. Update products. The request must include all properties of the product along with properties to be modified. #### Parameters * `PredictSpring-Secret` (header, string) * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `ProductRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `ProductResponse`. ### POST Create products. `POST /merchant/{version}/products` Operation ID: `addProducts`. Tags: Product Management API. Create products. The request must include all properties of a product. Do not use this API to update existing products, as any updates using this API are not effective. Use the PUT API to update existing products. #### Parameters * `PredictSpring-Secret` (header, string) * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `ProductRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `ProductResponse`. ### DELETE Delete products. `DELETE /merchant/{version}/products` Operation ID: `deleteProducts`. Tags: Product Management API. Delete products. The request must contain variantGroupID and product IDs. Product IDs can be a single product ID or multiple product IDs separated by commas. #### Parameters * `version` (path, string, required) Supported: v1. Pattern: v1|v2. * `variantGroupId` (query, string) * `productIds` (query, string) #### Responses * **default** Default response. Media type: `application/json`. Schema: `PSResponse`. ### PATCH Patch products. `PATCH /merchant/{version}/products` Operation ID: `patchProducts`. Tags: Product Management API. Update products. The request can include any or all properties of a product. Full product details are not needed. **Limit:** 100 products per request. If all products are updated successfully, a successful response is returned. Otherwise, error details are provided. Validation includes: 1. Empty or null product list 2. Valid existing product ID 3. Invalid product class, product title length. #### Parameters * `PredictSpring-Secret` (header, string) * `version` (path, string, required) Supported: v1. Pattern: v1|v2. #### Request body Media type: `application/json`. Schema: `ProductRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `ProductResponse`. ## Schemas ### ProductRequest * `products` (_array of MerchantProduct_) List of products. ### ProductResponse * `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`. * `products` (_array of MerchantProduct_, read-only) List of products. * `error` (_boolean_) ### 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_) ### MerchantProduct List of products. * `productId` (_string_, required) Distinct product ID for each combination of variations, for example, size or color. Example: `3661601595547`. * `title` (_string_, required) Product title. Example: `E18PENDANT1`. * `description` (_string_, required) Product description. Example: `Number 1 medallion`. * `productClass` (_string_, required) Product class of the item. Example: `Merchandise`. * `categories` (_array of string_) Merchant categories of the product. A pipe-separated list of category names belongs to this product. Items: Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`. Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`. * `googleCategory` (_string_) Product categories for Google search. Example: `Accessories > Categories > Jewelry`. * `imageUrl` (_string_) Image url of the product. Example: `https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html`. * `additionalImageUrls` (_array of string_) Additional image urls of the product. Items: Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`. Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`. * `condition` (_string_) Product condition. Allowed values: `NEW`, `USED`, `REFURBISHED`, `NEW, USED, REFURBISHED` . Example: `NEW`. * `availability` (_string_) Free text value that provides information about the availability of the product. Example: `Available`. * `listPrice` (_number (double)_, required) Listing price of the product. Example: `60`. * `salePrice` (_number (double)_, required) Sale price of the product. It can be same as listing price. Example: `60`. * `storePrice` (_number (double)_) Store specific price of the product. Example: `55`. * `currencyCode` (_string_) ISO currency code. Default: `USD`. Minimum length: 3. Maximum length: 3. Example: `USD`. * `brand` (_string_) Brand of the product. Example: `Gucci`. * `gtin` (_string_) Product's GTIN. Possible values are: UPC, EAN, JAN, ISBN, and ITF-14. Minimum length: 12. Maximum length: 14. Example: `065100004327`. * `mpn` (_string_) Manufacturer part number. Example: `100-440-0.750-3434-A`. * `gender` (_string_) Free text to provide gender related to the product. Example: `Unisex`. * `ageGroup` (_string_) Free text to provide age group related to the product. Example: `10-45`. * `subVariantGroupId` (_string_) ID of the subvariant group. * `variantGroupId` (_string_, required) Group ID of the product. All the different variations of the product are grouped together under a single group ID. Example: `E18PENDANT1`. * `color` (_string_) Product color. Example: `Silver`. * `colorSwatchUrl` (_string_) The image link for color swatches. * `size` (_string_) Product size. Example: `M`. * `pattern` (_string_) Free text to provide the product pattern. Example: `Oval`. * `sku` (_string_) SKU Id of the product. It can be same as product Id and unique per variation of the product. Example: `3661601595547`. * `isOnSale` (_boolean_, required) Specifies whether the product is on sale. Example: `false`. * `promotionTitle` (_string_, nullable) Promotion title applicable to the product. Example: `Summer22`. * `promotionPrice` (_number (double)_, nullable) Discounted price after applying promotion corresponding to the promotion title. Example: `55`. * `customString0` (_string_, nullable) Custom field of type String. * `customString1` (_string_, nullable) Custom field of type String. * `customString2` (_string_, nullable) Custom field of type String. * `customString3` (_string_, nullable) Custom field of type String. * `customString4` (_string_, nullable) Custom field of type String. * `customString5` (_string_, nullable) Custom field of type String. * `customString6` (_string_, nullable) Custom field of type String. * `customString7` (_string_, nullable) Custom field of type String. * `customString8` (_string_, nullable) Custom field of type String. * `customString9` (_string_, nullable) Custom field of type String. * `customString10` (_string_, nullable) Custom field of type String. * `customString11` (_string_, nullable) Custom field of type String. * `customString12` (_string_, nullable) Custom field of type String. * `customInt0` (_integer (int32)_, nullable) Custom field of type Integer. * `customInt1` (_integer (int32)_, nullable) Custom field of type Integer. * `customDecimal0` (_number (float)_, nullable) Custom field of type Decimal. * `customDecimal1` (_number (float)_, nullable) Custom field of type Decimal. * `customDateTime0` (_integer (int64)_, nullable) Custom field of type Epoch time in millis. * `customDateTime1` (_integer (int64)_, nullable) Custom field of type Epoch time in millis. * `onlineInventory` (_integer (int32)_, nullable) The current online inventory. You must provide a value if online inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**). * `material` (_string_, nullable) Product material. Example: `Metal`. * `manufacturer` (_string_, nullable) Manufacturer of the product. Example: `ABC Jewellers`. * `sizeGuideUrl` (_string_, nullable) Image URL of the size guide. * `manufacturerDetails` (_string_, nullable) Manufacturer details. * `manufacturerLocation` (_string_, nullable) Location of product manufacturer. * `productLocation` (_string_, nullable) Product manufacturing location. * `banner` (_string_, nullable) Banner text. If provided, banner text is shown on PLP and PDP screens. * `availableStores` (_array of string_, nullable) List of stores where the product is available. * `lastUpdate` (_string (date-time)_) * `storeInventory` (_integer (int32)_, nullable) The current store inventory. You must provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**). * `isVirtual` (_boolean_, nullable) Specifies whether the product is available only in online mode. * `multipleGTINs` (_array of string_, nullable) If the product supports multiple GTINs, provide all of them. * `storeProductDetails` (_StoreProductDetails_) * `onlineAvailableStores` (_array of string_, nullable) List of stores where online products are available. * `costPrice` (_number (double)_, nullable) Cost per item. * `casePackQuantity` (_integer (int32)_, nullable) Number of items per case pack. * `additionalCharges` (_string_, nullable) Additional charges for CA, FR. * `casePackID` (_string_, nullable) Identifier for case pack. * `availabilityStartTime` (_string (date-time)_, nullable) Start time, when product is visible on POS. * `availabilityEndTime` (_string (date-time)_, nullable) End time, when product will not be visible on POS. ### StoreProductDetails Provide details about products in the store. This includes store-level inventory, store level pricing, store level promotions, etc. You must provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**). * `storeId` (_string_) Store or warehouse ID. * `productId` (_string_) Product ID. * `storeInventory` (_integer (int32)_) Product sellable quantity. * `storePrice` (_number_) Product price at the store. * `storePromoText` (_string_) Product promotion text applicable to this store. * `listPrice` (_number_) Product list price. * `salesPrice` (_number_) Product sale price. * `storePromoBanner` (_string_) Product promotion banner text. * `clearanceItems` (_array of ClearanceItem_) Product location within the store. * `allocatedQuantity` (_integer (int32)_) Product quantity allocated for shipment or BOPIS orders. * `safetyStockQuantity` (_integer (int32)_) Product safety stock quantity. * `quantityOnHand` (_integer (int32)_) Product quantity on hand. * `quantityInTransit` (_integer (int32)_) Product quantity in transit to this store. * `quantityOnOrder` (_integer (int32)_) Product quantity on order for this store. * `notForSaleQuantity` (_integer (int32)_) Damaged product quantity that isn't for sale. * `returnedItemsQuantity` (_integer (int32)_) Returned product quantity that isn't for sale. * `floorDemoQuantity` (_integer (int32)_) Floor/Demo product quantity that isn't for sale. * `fullPriceSerialNumbers` (_array of string_) Full price serial numbers. * `storeOnlineQuantity` (_integer (int32)_) Online product quantity available for sale in store. * `customString0` (_string_) Custom string attribute of the product for the store. * `customString1` (_string_) Custom string attribute of the product for the store. * `quantity` (_integer (int32)_) ### ClearanceItem Product location within the store. * `serialNumber` (_string_) Serial number of the item (if applicable). * `clearancePrice` (_number_) * `itemLocationWithinStore` (_string_) * `instructionText` (_string_)