--- schema_version: "1" id: 91dbf10d4e0149facfff039484f64779a7c9213a807ccaa272e99b2928f6fff6 title: Products 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/products.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/products source_site: developer.salesforce.com content_type: documentation content_hash: f7fa36521ad54bbc361466a64f03112d84019afdb6f58d9621f48fc2ea9257f7 products: - B2C Commerce API - Salesforce APIs --- Products # Products [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/products/products-oas-v1-public.yaml) ## API Overview The Products API enables you to build merchandising apps that merchandisers use to add products to catalogs, configure products for your storefront, and manage products in their ecommerce channels. For more information, see [Products](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/products/b2c_products.html) in the Salesforce B2C Commerce Infocenter. ### Authentication & Authorization The client managing product information must have access to the Products resource. This API requires a bearer token in the header of the request. The client accessing the API must first authenticate against Account Manager to get the bearer token. You must include the relevant scope(s) in the client ID used to generate the SLAS token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) ### Use Cases #### Add Products Use the Products API to add new products to a catalog. You can add or update product details like attributes, variations, variation attributes, and images. You can also use the API to change a product’s catalog assignment. If you are adding products from an external product information management (PIM) system, use the Mulesoft Accelerator component created for Commerce Cloud. For more detail, see [Variation Groups](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/products/b2c_variation_groups.html) in the Salesforce B2C Commerce Infocenter. ![b2c-commerce-products-screenshot-1.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-products-screenshot-1.png) #### Create & Validate Variation Groups Use the API to enable a shopper to switch between different variants on a product page. You can group variation products into variation groups or group master products by one or more attributes. The variants within a variation group are linked. Linked variants allow a shopper to switch between different variants. For more detail, see [Variation Groups](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/products/b2c_variation_groups.html) in the Salesforce B2C Commerce Infocenter. ![b2c-commerce-products-screenshot-2.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-products-screenshot-2.png) #### Search for Variants Use the Product API to enable merchants to use a set of filtering and sorting criteria to search for variants assigned to a master product, or variation group. For more detail, see [Product Variations](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/products/b2c_product_variations.html) in the Salesforce B2C Commerce Infocenter. ![b2c-commerce-products-screenshot-3.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-products-screenshot-3.png) #### Manage Product Options Use the API to view and manage product options for a given product so that optional accessories, upgrades, or services can be sold with the product. For example, a product warranty or monogramming. For more detail, see [Product Options](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/products/b2c_product_options.html) in the Salesforce B2C Commerce Infocenter. ![b2c-commerce-products-screenshot-4.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-products-screenshot-4.png) **Version:** 1.2.0 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/product/products/v1` * `shortCode (default shortCode)` ## Security * `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication. * OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * Scope sfcc.products: Product scope READONLY * Scope sfcc.products.rw: Product scope * OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token) * Scope sfcc.products: Product scope READONLY * Scope sfcc.products.rw: Product scope ## Operations ### GET Get product information. `GET /organizations/{organizationId}/products/{productId}` Operation ID: `getProduct`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Retrieve detailed information about a specific product. #### Parameters * `productId` (path, ProductId, required) * `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 ``` * `siteId` (query, SiteId) The site context. #### Responses * **200** Retrieved product information successfully. Media type: `application/json`. Schema: `Product`. _Example: DataProductExpand_ ``` { "assignedCategories": [ { "catalogId": "apparel-catalog", "categoryId": "mens-accessories" }, { "catalogId": "storefront-catalog-en", "categoryId": "top-seller" }, { "catalogId": "storefront-catalog-en", "categoryId": "electronics-gaming" } ], "brand": "Apple", "classificationCategory": { "catalogId": "storefront-catalog-en", "categoryId": "top-seller" }, "creationDate": "2019-02-21T22:10:02.000Z", "id": "apple-ipod-classic", "image": { "absUrl": "https://example.com/images/large/ipod-classic-silver.jpg", "alt": { "default": "Apple iPod Classic, , large" }, "path": "large/ipod-classic-silver.jpg", "title": { "default": "Apple iPod Classic, " } }, "imageGroups": [ { "images": [ { "absUrl": "https://example.com/images/large/ipod-classic-silver.jpg", "alt": { "default": "Apple iPod Classic, , large" }, "path": "large/ipod-classic-silver.jpg", "title": { "default": "Apple iPod Classic, " } } ], "viewType": "large" }, { "images": [ { "absUrl": "https://example.com/images/medium/ipod-classic-silver.jpg", "alt": { "default": "Apple iPod Classic, , medium" }, "path": "medium/ipod-classic-silver.jpg", "title": { "default": "Apple iPod Classic, " } } ], "viewType": "medium" }, { "images": [ { "absUrl": "https://example.com/images/small/ipod-classic-silver.jpg", "alt": { "default": "Apple iPod Classic, , small" }, "path": "small/ipod-classic-silver.jpg", "title": { "default": "Apple iPod Classic, " } } ], "viewType": "small" } ], "lastModified": "2019-08-28T18:49:09.000Z", "localizedTaxClassId": { "de": "exempt", "default": "standard", "en-US": "exempt" }, "longDescription": { "default": { "markup": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats", "source": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats" } }, "name": { "default": "Apple iPod Classic" }, "onlineFlag": { "default": true }, "owningCatalogId": "electronics-catalog", "owningCatalogName": { "default": "Electronics Master Catalog" }, "pageDescription": { "default": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go." }, "pageKeywords": { "default": "Apple, iPod, iPod Classic, MP3, Music Player" }, "pageTitle": { "default": "Apple iPod Nano" }, "primaryCategories": [ { "catalogId": "apparel-catalog", "categoryId": "mens-accessories" }, { "catalogId": "storefront-catalog-en", "categoryId": "top-seller" } ], "primaryCategoryId": "top-seller", "searchable": { "default": true }, "shortDescription": { "default": { "markup": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go.", "source": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go." } }, "taxClassId": "standard", "type": { "master": true }, "validFrom": { "default": "1998-05-03T00:00:00.000Z", "default@SiteGenesis": "1998-05-11T00:00:00.000Z" }, "validTo": { "default": "2028-07-03T00:00:00.000Z", "default@SiteGenesis": "2028-05-30T00:03:00.000Z" }, "variants": [ { "productId": "apple-ipod-classic-silver-120g", "variationValues": { "color": "Silver", "memorySize": "120 GB" } }, { "productId": "apple-ipod-classic-black-120g", "variationValues": { "color": "Black", "memorySize": "120 GB" } } ], "variationAttributes": [ { "attributeDefinitionId": "color", "attributeDefinitionName": { "default": "Color" }, "id": "color", "name": { "default": "Color" }, "shared": true, "slicing": false, "values": [ { "name": { "default": "Silver" }, "position": 1, "value": "Silver" }, { "name": { "default": "Black" }, "position": 2, "value": "Black" }, { "name": { "default": "Purple" }, "position": 3, "value": "Purple" }, { "name": { "default": "Blue" }, "position": 4, "value": "Blue" }, { "name": { "default": "Green" }, "position": 5, "value": "Green" }, { "name": { "default": "Yellow" }, "position": 6, "value": "Yellow" }, { "name": { "default": "Orange" }, "position": 7, "value": "Orange" }, { "name": { "default": "Red" }, "position": 8, "value": "Red" }, { "name": { "default": "Fuscia" }, "position": 9, "value": "Fuscia" } ], "variationAttributeType": "string" }, { "attributeDefinitionId": "memorySize", "attributeDefinitionName": { "default": "Memory Size" }, "id": "memorySize", "name": { "default": "Memory Size" }, "shared": true, "slicing": false, "values": [ { "name": { "default": "1 GB" }, "position": 1, "value": "1 GB" }, { "name": { "default": "2 GB" }, "position": 2, "value": "2 GB" }, { "name": { "default": "8 GB" }, "position": 3, "value": "8 GB" }, { "name": { "default": "16 GB" }, "position": 4, "value": "16 GB" }, { "name": { "default": "32 GB" }, "position": 5, "value": "32 GB" }, { "name": { "default": "120 GB" }, "position": 6, "value": "120 GB" } ], "variationAttributeType": "string" } ] } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: getProduct400_ ``` { "title": "Unqueryable Field", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field", "detail": "The field 'link' can't be queried.", "field": "link" } ``` * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: getProduct401_ ``` { "title": "Invalid Access Token", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-access-token", "detail": "The request is unauthorized, the access token is invalid.", "accessToken": "hbGciOiJIUzI1NiIsInR5cCI6Ikp" } ``` * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: getProduct404_ ``` { "title": "Product Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-not-found", "detail": "No product with ID '1585183329877' could be found.", "productId": "1585183329877" } ``` ### PUT Create or overwrite a product with provided data. `PUT /organizations/{organizationId}/products/{productId}` Operation ID: `createProduct`. Security: AmOAuth2 (sfcc.products.rw). Create a product using the information provided. If a product with the same unique identifier exists, it is overwritten. #### Parameters * `productId` (path, ProductId, required) * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `Product`. _Example DataProductExpand: same as GET /organizations/{organizationId}/products/{productId} 200 response._ #### Responses * **200** Product was updated successfully. Media type: `application/json`. Schema: `Product`. _Example DataProductExpand: same as GET /organizations/{organizationId}/products/{productId} 200 response._ * **201** Product was created successfully. Media type: `application/json`. Schema: `Product`. _Example DataProductExpand: same as GET /organizations/{organizationId}/products/{productId} 200 response._ * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### DELETE Deletes the product by ID. `DELETE /organizations/{organizationId}/products/{productId}` Operation ID: `deleteProduct`. Security: AmOAuth2 (sfcc.products.rw). Permanently remove a product by ID. #### Parameters * `productId` (path, ProductId, required) * `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 ``` #### Responses * **204** Deleted the product successfully. * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PATCH Partially update fields of an existing product. `PATCH /organizations/{organizationId}/products/{productId}` Operation ID: `updateProduct`. Security: AmOAuth2 (sfcc.products.rw). Update a product using the information provided. Fields that can be updated: name, pageDescription, longDescription, pageTitle, pageKeywords, brand, ean, upc, manufactureSku, manufactureName, searchable, unit, searchable, onlineFlag, defaultVariantId. Custom attributes are used to extend a standard Product system object. This endpoint can be used to update custom attribute values for a particular product SKU. If you try to update a non-existent custom attribute, the request won't fail, but no changes are made and the attribute is not created. #### Parameters * `productId` (path, ProductId, required) * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `Product`. _Example DataProductExpand: same as GET /organizations/{organizationId}/products/{productId} 200 response._ #### Responses * **200** Updated the product successfully. Media type: `application/json`. Schema: `Product`. _Example DataProductExpand: same as GET /organizations/{organizationId}/products/{productId} 200 response._ * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### POST Search product variations using complex queries and filters. `POST /organizations/{organizationId}/products/{productId}/variant-search` Operation ID: `searchProductVariations`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Search product variations for master product or variation group product. The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes: | Attribute | Type | | --- | --- | | id | String | | productId | String | | name | String | | online | SiteSpecific Boolean | | inStock | Boolean | | searchable | SiteSpecific Boolean | | ats - Available quantity to sell | Double | | variationAttribute.ATTRIBUTE\_ID (Ex:variation\_attribute.color) | String | Sortable Fields: | Attribute | Type | | --- | --- | | id | String | | productId | String | | name | String | | online | SiteSpecific Boolean | | inStock | Boolean | | searchable | SiteSpecific Boolean | | ats - Available quantity to sell | Double | Note: The calculated value of "online" and "searchable" is used in the search/sort. A search/sort by the site-specific attributes require the Site ID query parameter to be set. They are "online", "inStock", "searchable" and "ats". We assume that every field that starts with variationAttribute. is searchable and dot is followed by "ATTRIBUTE\_ID". The list of expansions to retrieve product information. The expand values available are: * \_base - Basic product information is retrieved. This expand is included by default. * all - All product information, including the following properties are retrieved: * image * price - siteId must be provided to see this property * priceCurrency - siteId must be provided to see this property * availability - Information related to the availability of the product variation. This expand is not included by default. * ats - siteId must be provided to see this property * inStock - siteId must be provided to see this property * online - siteId must be provided to see this property * searchable * variations - Information related to product variations is retrieved. This expand is included by default. * attributes - Information related to product variation attributes is retrieved. This expand is not included by default. #### Parameters * `productId` (path, ProductId, required) * `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 ``` * `siteId` (query, SiteId) The site context. #### Request body (required) Media type: `application/json`. Schema: `VariantSearchRequest`. _Example: VariantSearchRequestBody_ ``` { "query": { "textQuery": { "fields": [ "id" ], "searchPhrase": "ipod" } }, "expand": [ "variations" ] } ``` #### Responses * **200** Search results returned. Media type: `application/json`. Schema: `VariantSearchResult`. _Example: VariantSearchResult_ ``` { "limit": 2, "hits": [ { "defaultProductVariation": false, "productId": "apple-ipod-classic-silver-120g", "variationValues": { "color": "Silver", "memorySize": "120 GB" } }, { "defaultProductVariation": false, "productId": "apple-ipod-classic-black-120g", "variationValues": { "color": "Black", "memorySize": "120 GB" } } ], "query": { "textQuery": { "fields": [ "id" ], "searchPhrase": "ipod" } }, "offset": 0, "total": 2 } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### GET List all variation groups of a product. `GET /organizations/{organizationId}/products/{masterProductId}/variation-groups` Operation ID: `getVariationGroupsForMasterProduct`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). List all variation groups of a product. #### Parameters * `masterProductId` (path, string, required) The ID of the master product that contains the variation group. Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`. * `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 ``` * `siteId` (query, SiteId) The site context. * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 50. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Get VariationGroups for a product was successful. Media type: `application/json`. Schema: `VariationGroups`. _Example: VariationGroupsResult_ ``` { "limit": 1, "data": [ { "productId": "apple-ipod-classic-1", "variationValues": { "color": "Silver", "memorySize": "120 GB" } } ], "offset": 0, "total": 1 } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### GET Get a specific variation group. `GET /organizations/{organizationId}/products/{masterProductId}/variation-groups/{id}` Operation ID: `getVariationGroupForMasterProduct`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Read a variation group for a product. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `masterProductId` (path, string, required) The ID of the master product that contains the variation group. Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`. * `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 ``` * `siteId` (query, SiteId) The site context. #### Responses * **200** Get VariationGroup by Id for a product was successful. Media type: `application/json`. Schema: `VariationGroup`. _Example: VariationGroupsIdResult_ ``` { "productId": "apple-ipod-classic-1", "variationValues": { "color": "Silver", "memorySize": "120 GB" } } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PUT Assign or create a variation group for a product. `PUT /organizations/{organizationId}/products/{masterProductId}/variation-groups/{id}` Operation ID: `assignVariationGroupToMasterProduct`. Security: AmOAuth2 (sfcc.products.rw). Assign a variation group for a product. If the variation group product does not initially exist, one is created using the body passed in. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `masterProductId` (path, string, required) The ID of the master product that contains the variation group. Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`. * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `VariationGroup`. _Example: VariationGroupsIdRequestBody_ ``` { "orderable": true, "price": 500, "productId": "apple-ipod-classic-1", "variationValues": { "color": "Silver", "memorySize": "120 GB" } } ``` #### Responses * **200** Successfully assigned a variation group for given product. Media type: `application/json`. Schema: `VariationGroup`. _Example: VariationGroupsIdResult_ ``` { "productId": "apple-ipod-classic-1", "variationValues": { "color": "Silver", "memorySize": "120 GB" } } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### DELETE Unassign a variation group (product not deleted). `DELETE /organizations/{organizationId}/products/{masterProductId}/variation-groups/{id}` Operation ID: `unassignVariationGroupFromMasterProduct`. Security: AmOAuth2 (sfcc.products.rw). Unassign a variation group product from a product. The variation group product is not deleted: it remains as a typical product after unassign. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `masterProductId` (path, string, required) The ID of the master product that contains the variation group. Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`. * `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 ``` #### Responses * **204** Deleted the variation group successfully. * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PATCH Update an existing variation group. `PATCH /organizations/{organizationId}/products/{masterProductId}/variation-groups/{id}` Operation ID: `updateVariationGroupForMasterProduct`. Security: AmOAuth2 (sfcc.products.rw). Update a variation group for a product master. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `masterProductId` (path, string, required) The ID of the master product that contains the variation group. Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`. * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `VariationGroup`. _Example: VariationGroupsIdRequestBody_ ``` { "orderable": true, "price": 500, "productId": "apple-ipod-classic-1", "variationValues": { "color": "Silver", "memorySize": "120 GB" } } ``` #### Responses * **200** Update was successful. Media type: `application/json`. Schema: `VariationGroup`. _Example: VariationGroupsIdResult_ ``` { "productId": "apple-ipod-classic-1", "variationValues": { "color": "Silver", "memorySize": "120 GB" } } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### GET List all variations of a master product. `GET /organizations/{organizationId}/products/{masterProductId}/variations` Operation ID: `getVariationsForMasterProduct`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). List all variations of a master product. #### Parameters * `masterProductId` (path, string, required) The ID of the master product that contains the variation group. Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`. * `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 ``` * `siteId` (query, SiteId) The site context. * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 50. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Get variation by ID successful. Media type: `application/json`. Schema: `Variants`. _Example: getProduct400_ ``` { "limit": 4, "data": [ { "productId": "apple-ipod-classic-silver-120g" }, { "productId": "apple-ipod-classic-black-120g" }, { "productId": "apple-ipod-classic-2" }, { "productId": "apple-ipod-classic-blue-32g" } ], "offset": 0, "total": 4 } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### GET Get details of a specific variation. `GET /organizations/{organizationId}/products/{masterProductId}/variations/{id}` Operation ID: `getVariationForMasterProduct`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Get details of a specific variation. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `masterProductId` (path, string, required) The ID of the master product that contains the variation group. Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`. * `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 ``` * `siteId` (query, SiteId) The site context. #### Responses * **200** Get variation by ID successful. Media type: `application/json`. Schema: `Variant`. _Example: VariationsIdResult_ ``` { "defaultProductVariation": false, "productId": "apple-ipod-classic-blue-32g", "variationValues": { "color": "Blue", "memorySize": "32 GB" } } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PUT Assign a variation to a master product (creates if not exists). `PUT /organizations/{organizationId}/products/{masterProductId}/variations/{id}` Operation ID: `assignVariationForMasterProduct`. Security: AmOAuth2 (sfcc.products.rw). Assign a variation for a product master. If the variation product does not initially exist, one is created using the body that is passed. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `masterProductId` (path, string, required) The ID of the master product that contains the variation group. Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`. * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `Variant`. _Example: VariationsIdRequestBody_ ``` { "orderable": true, "price": 500, "productId": "apple-ipod-classic-blue-32g", "variationValues": { "color": "Blue", "memorySize": "32 GB" } } ``` #### Responses * **200** Updated the variation product successfully. Media type: `application/json`. Schema: `Variant`. _Example: VariationsIdResult_ ``` { "defaultProductVariation": false, "productId": "apple-ipod-classic-blue-32g", "variationValues": { "color": "Blue", "memorySize": "32 GB" } } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### DELETE Unassign a variation from a product (does not delete it). `DELETE /organizations/{organizationId}/products/{masterProductId}/variations/{id}` Operation ID: `unassignVariationFromMasterProduct`. Security: AmOAuth2 (sfcc.products.rw). Unassign a variation product from a product. The variation product is not deleted: it remains as a typical product after unassign. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `masterProductId` (path, string, required) The ID of the master product that contains the variation group. Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`. * `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 ``` #### Responses * **204** Deleted the variation group successfully. * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PATCH Update a specific product variation. `PATCH /organizations/{organizationId}/products/{masterProductId}/variations/{id}` Operation ID: `updateVariationForMasterProduct`. Security: AmOAuth2 (sfcc.products.rw). Update a variation for a product. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `masterProductId` (path, string, required) The ID of the master product that contains the variation group. Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`. * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `Variant`. _Example: VariationsIdRequestBody_ ``` { "orderable": true, "price": 500, "productId": "apple-ipod-classic-blue-32g", "variationValues": { "color": "Blue", "memorySize": "32 GB" } } ``` #### Responses * **200** Variation updated successfully. Media type: `application/json`. Schema: `Variant`. _Example: VariationsIdResult_ ``` { "defaultProductVariation": false, "productId": "apple-ipod-classic-blue-32g", "variationValues": { "color": "Blue", "memorySize": "32 GB" } } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### GET Retrieve product options for a product. `GET /organizations/{organizationId}/products/{productId}/product-options` Operation ID: `getProductOptions`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Read local and shared product options for a specified product. #### Parameters * `productId` (path, ProductId, required) * `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 ``` * `currency` (query, CurrencyCode) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable. _Example: CurrencyCode_ ``` USD ``` * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 50. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Retrieved product options successfully. Media type: `application/json`. Schema: `ProductOptions`. _Example: ProductOptionsResult_ ``` { "limit": 1, "data": [ { "id": "digitalCameraWarranty", "values": [ { "id": "001", "optionPrices": [ { "currencyMnemonic": "USD", "value": 9.99 } ], "value": { "default": "1 Year Warranty" } }, { "id": "003", "optionPrices": [ { "currencyMnemonic": "USD", "value": 29.99 } ], "value": { "default": "5 Year Warranty" } }, { "id": "000", "optionPrices": [ { "currencyMnemonic": "USD", "value": 39.99 } ], "value": { "default": "None" } }, { "id": "002", "optionPrices": [ { "currencyMnemonic": "USD", "value": 49.99 } ], "value": { "default": "3 Year Warranty" } } ] } ], "offset": 0, "total": 1 } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### GET Retrieve a specific product option. `GET /organizations/{organizationId}/products/{productId}/product-options/{id}` Operation ID: `getProductOption`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Read a local or shared product option for a specified product. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `productId` (path, ProductId, required) * `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 ``` * `currency` (query, CurrencyCode) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable. _Example: CurrencyCode_ ``` USD ``` #### Responses * **200** Retrieved product options successfully. Media type: `application/json`. Schema: `ProductOption`. _Example: ProductOptionsIdResult_ ``` { "customName": { "default": "My Option" }, "description": { "default": "Description for my option." }, "id": "my-option", "image": { "absUrl": "https://example.com/on/demandware.static/-/Sites-XMaster/default/aaaaaaaabbbbbbbbbabababba/option.jpg", "disBaseUrl": "https://example.com/dw/image/v2/zzzz_s01/on/demandware.static/-/Sites-XMaster/default/aaaaaaaabbbbbbbbbabababba/option.jpg", "path": "option.jpg" }, "name": "option", "shared": false, "sortingMode": "byoptionprice" } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PUT Create or bind a product option. `PUT /organizations/{organizationId}/products/{productId}/product-options/{id}` Operation ID: `createProductOption`. Security: AmOAuth2 (sfcc.products.rw). Creates a local product option using the information provided or binds a shared product option to the product. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `productId` (path, ProductId, required) * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `ProductOption`. _Example: ProductOptionsIdRequestBody_ ``` { "id": "my-option", "customName": { "default": "My Option" }, "description": { "default": "Description for my option." }, "image": { "path": "option.jpg" } } ``` #### Responses * **200** Updated product option successfully. Media type: `application/json`. Schema: `ProductOption`. _Example ProductOptionsIdResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{id} 200 response._ * **201** Created or binded product option successfully. Media type: `application/json`. Schema: `ProductOption`. _Example ProductOptionsIdResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{id} 200 response._ * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### DELETE Delete or unbind a product option. `DELETE /organizations/{organizationId}/products/{productId}/product-options/{id}` Operation ID: `deleteProductOption`. Security: AmOAuth2 (sfcc.products.rw). Delete a local product option or unbind a shared product option from the product. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `productId` (path, ProductId, required) * `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 ``` #### Responses * **204** Deleted product option successfully. * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PATCH Update a product option. `PATCH /organizations/{organizationId}/products/{productId}/product-options/{id}` Operation ID: `updateProductOption`. Security: AmOAuth2 (sfcc.products.rw). Update a local product option with the information provided. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `productId` (path, ProductId, required) * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `ProductOption`. _Example: ProductOptionsIdRequestBody_ ``` { "id": "my-option", "customName": { "default": "My Option" }, "description": { "default": "Description for my option." }, "image": { "path": "option.jpg" } } ``` #### Responses * **200** Updated product option successfully. Media type: `application/json`. Schema: `ProductOption`. _Example ProductOptionsIdResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{id} 200 response._ * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### GET Retrieve a product option value. `GET /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id}` Operation ID: `getProductOptionValue`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Read a local product option value for a specified product. #### Parameters * `productId` (path, ProductId, required) * `optionId` (path, string, required) The ID of the local product option. Minimum length: 1. Maximum length: 256. Example: `sony-ps3-bundle`. * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `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 ``` #### Responses * **200** Successfully retrieved product option value. Media type: `application/json`. Schema: `ProductOptionValue`. _Example: ProductOptionsValuesResult_ ``` { "defaultProductOptionValue": false, "id": "value1", "optionPrices": [ { "currencyMnemonic": "USD", "value": 100 } ], "skuExtension": "s10", "value": { "default": "value 1", "en-US": "value 1(en-US)", "en": "value 1(en)" } } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PUT Create a product option value. `PUT /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id}` Operation ID: `createProductOptionValue`. Security: AmOAuth2 (sfcc.products.rw). Create a local product option value using the information provided. #### Parameters * `productId` (path, ProductId, required) * `optionId` (path, string, required) The ID of the local product option. Minimum length: 1. Maximum length: 256. Example: `sony-ps3-bundle`. * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `ProductOptionValue`. _Example: ProductOptionsValuesRequestBody_ ``` { "id": "my-option", "value": { "default": "value 1", "en": "value 1(en)", "en-US": "value 1(en-US)" }, "optionPrices": [ { "currencyMnemonic": "USD", "value": 100 } ], "skuExtension": "s10" } ``` #### Responses * **200** Updated product option value successfully. Media type: `application/json`. Schema: `ProductOptionValue`. _Example ProductOptionsValuesResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id} 200 response._ * **201** Created product option value successfully. Media type: `application/json`. Schema: `ProductOptionValue`. _Example ProductOptionsValuesResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id} 200 response._ * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### DELETE Delete a product option value. `DELETE /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id}` Operation ID: `deleteProductOptionValue`. Security: AmOAuth2 (sfcc.products.rw). Delete a local product option value by ID. #### Parameters * `productId` (path, ProductId, required) * `optionId` (path, string, required) The ID of the local product option. Minimum length: 1. Maximum length: 256. Example: `sony-ps3-bundle`. * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `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 ``` #### Responses * **204** Deleted product option value successfully. * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PATCH Update a product option value. `PATCH /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id}` Operation ID: `updateProductOptionValue`. Security: AmOAuth2 (sfcc.products.rw). Update a local product option value using the information provided. #### Parameters * `productId` (path, ProductId, required) * `optionId` (path, string, required) The ID of the local product option. Minimum length: 1. Maximum length: 256. Example: `sony-ps3-bundle`. * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `ProductOptionValue`. _Example ProductOptionsValuesRequestBody: same as PUT /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id} request._ #### Responses * **200** Product option value updated successfully. Media type: `application/json`. Schema: `ProductOptionValue`. _Example ProductOptionsValuesResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id} 200 response._ * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### GET Retrieve a variation attribute value. `GET /organizations/{organizationId}/products/{productId}/variation-attributes/{attributeId}/values/{id}` Operation ID: `getVariationAttributeValue`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Get product variation attribute information. #### Parameters * `productId` (path, ProductId, required) * `attributeId` (path, string, required) The variation attribute ID. Minimum length: 1. Maximum length: 256. Example: `colour`. * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `siteId` (query, SiteId) The site context. * `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 ``` #### Responses * **200** Retrieved variation attribute value successfully. Media type: `application/json`. Schema: `VariationAttributeValue`. _Example: VariationAttributeValuesIdResult_ ``` { "description": { "default": "desc of 8 (default)", "en-US": "desc of 8 (en-US)", "en": "desc of 8 (en)" }, "position": 1, "value": "8" } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PUT Create a variation attribute value. `PUT /organizations/{organizationId}/products/{productId}/variation-attributes/{attributeId}/values/{id}` Operation ID: `createVariationAttributeValue`. Security: AmOAuth2 (sfcc.products.rw). Create a product variation attribute value. #### Parameters * `productId` (path, ProductId, required) * `attributeId` (path, string, required) The variation attribute ID. Minimum length: 1. Maximum length: 256. Example: `colour`. * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `VariationAttributeValue`. _Example: VariationAttributeValuesIdRequestBody_ ``` { "value": "8", "description": { "default": "desc of 8 (default)", "en": "desc of 8 (en)", "en-US": "desc of 8 (en-US)" } } ``` #### Responses * **200** Created product variation attribute value successfully. Media type: `application/json`. Schema: `VariationAttributeValue`. _Example: VariationAttributeValuesIdResult_ ``` { "description": { "default": "desc of 8 (default)", "en-US": "desc of 8 (en-US)", "en": "desc of 8 (en)" }, "position": 1, "value": "8" } ``` * **201** Created product variation attribute value successfully. Media type: `application/json`. Schema: `VariationAttributeValue`. _Example: VariationAttributeValuesIdResult_ ``` { "description": { "default": "desc of 8 (default)", "en-US": "desc of 8 (en-US)", "en": "desc of 8 (en)" }, "position": 1, "value": "8" } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### DELETE Delete a variation attribute value. `DELETE /organizations/{organizationId}/products/{productId}/variation-attributes/{attributeId}/values/{id}` Operation ID: `deleteVariationAttributeValue`. Security: AmOAuth2 (sfcc.products.rw). Delete the variation attribute value of a variation attribute bound to a product. #### Parameters * `productId` (path, ProductId, required) * `attributeId` (path, string, required) The variation attribute ID. Minimum length: 1. Maximum length: 256. Example: `colour`. * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `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 ``` #### Responses * **204** Deleted variation attribute value successfully. * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PATCH Update a variation attribute value. `PATCH /organizations/{organizationId}/products/{productId}/variation-attributes/{attributeId}/values/{id}` Operation ID: `updateVariationAttributeValue`. Security: AmOAuth2 (sfcc.products.rw). Update the variation attribute value of a variation attribute of a product. #### Parameters * `productId` (path, ProductId, required) * `attributeId` (path, string, required) The variation attribute ID. Minimum length: 1. Maximum length: 256. Example: `colour`. * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `VariationAttributeValue`. _Example: VariationAttributeValuesIdRequestBody_ ``` { "value": "8", "description": { "default": "desc of 8 (default)", "en": "desc of 8 (en)", "en-US": "desc of 8 (en-US)" } } ``` #### Responses * **200** Updated variation attribute value successfully. Media type: `application/json`. Schema: `VariationAttributeValue`. _Example: VariationAttributeValuesIdResult_ ``` { "description": { "default": "desc of 8 (default)", "en-US": "desc of 8 (en-US)", "en": "desc of 8 (en)" }, "position": 1, "value": "8" } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### GET Retrieve variation attributes of a product. `GET /organizations/{organizationId}/products/{productId}/variation-attributes` Operation ID: `getVariationAttributes`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Read variation attributes of a product of type variant, variation master, or variation group. #### Parameters * `productId` (path, ProductId, required) * `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 ``` * `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25. Default: `25`. Minimum: 1. Maximum: 50. * `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset. Default: `0`. Minimum: 0. #### Responses * **200** Retrieved the list of VariationAttributes for the product ID successfully. Media type: `application/json`. Schema: `VariationAttributes`. _Example: VariationAttributesResult_ ``` { "limit": 3, "data": [ { "attributeDefinitionId": "color", "attributeDefinitionName": { "default": "Color" }, "id": "color", "name": { "default": "Color" }, "shared": true, "slicing": false, "values": [ { "name": { "default": "Silver" }, "position": 1, "value": "Silver" }, { "name": { "default": "Black" }, "position": 2, "value": "Black" }, { "name": { "default": "Purple" }, "position": 3, "value": "Purple" }, { "name": { "default": "Blue" }, "position": 4, "value": "Blue" }, { "name": { "default": "Green" }, "position": 5, "value": "Green" }, { "name": { "default": "Yellow" }, "position": 6, "value": "Yellow" }, { "name": { "default": "Orange" }, "position": 7, "value": "Orange" }, { "name": { "default": "Red" }, "position": 8, "value": "Red" }, { "name": { "default": "Fuscia" }, "position": 9, "value": "Fuscia" } ], "variationAttributeType": "string" }, { "attributeDefinitionId": "memorySize", "attributeDefinitionName": { "default": "Memory Size" }, "id": "memorySize", "name": { "default": "Memory Size" }, "shared": true, "slicing": false, "values": [ { "name": { "default": "1 GB" }, "position": 1, "value": "1 GB" }, { "name": { "default": "2 GB" }, "position": 2, "value": "2 GB" }, { "name": { "default": "8 GB" }, "position": 3, "value": "8 GB" }, { "name": { "default": "16 GB" }, "position": 4, "value": "16 GB" }, { "name": { "default": "32 GB" }, "position": 5, "value": "32 GB" }, { "name": { "default": "120 GB" }, "position": 6, "value": "120 GB" } ], "variationAttributeType": "string" }, { "attributeDefinitionId": "size", "attributeDefinitionName": { "default": "Size" }, "id": "screenSize", "name": { "default": "Size" }, "shared": false, "slicing": false, "values": [ { "description": { "default": "desc of 8 (default)", "en-US": "desc of 8 (en-US)", "en": "desc of 8 (en)" }, "position": 1, "value": "8" } ], "variationAttributeType": "string" } ], "offset": 0, "total": 3 } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### GET Retrieve a specific variation attribute. `GET /organizations/{organizationId}/products/{productId}/variation-attributes/{id}` Operation ID: `getVariationAttribute`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Get variation attribute information only for master product. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `productId` (path, ProductId, required) * `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 ``` #### Responses * **200** Retrieved the VariationAttribute for the product ID successfully. Media type: `application/json`. Schema: `VariationAttribute`. _Example: VariationAttributeResult_ ``` { "attributeDefinitionId": "size", "attributeDefinitionName": { "default": "Size" }, "id": "screenSize", "name": { "default": "Size" }, "shared": false, "slicing": false, "variationAttributeType": "string" } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PUT Create a variation attribute. `PUT /organizations/{organizationId}/products/{productId}/variation-attributes/{id}` Operation ID: `createVariationAttribute`. Security: AmOAuth2 (sfcc.products.rw). Create a variation attribute using the information provided. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `productId` (path, ProductId, required) * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `VariationAttribute`. _Example: VariationAttributeRequestBody_ ``` { "attributeDefinitionId": "size", "attributeDefinitionName": { "default": "Screen Size" } } ``` #### Responses * **200** Created variation attribute successfully. Media type: `application/json`. Schema: `VariationAttribute`. _Example VariationAttributeResult: same as GET /organizations/{organizationId}/products/{productId}/variation-attributes/{id} 200 response._ * **201** Created variation attribute successfully. Media type: `application/json`. Schema: `VariationAttribute`. _Example VariationAttributeResult: same as GET /organizations/{organizationId}/products/{productId}/variation-attributes/{id} 200 response._ * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### DELETE Remove a variation attribute. `DELETE /organizations/{organizationId}/products/{productId}/variation-attributes/{id}` Operation ID: `deleteVariationAttribute`. Security: AmOAuth2 (sfcc.products.rw). Delete the variation attribute by ID. #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `productId` (path, ProductId, required) * `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 ``` #### Responses * **204** Deleted variation attribute successfully. * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### PATCH Update a variation attribute. `PATCH /organizations/{organizationId}/products/{productId}/variation-attributes/{id}` Operation ID: `updateVariationAttribute`. Security: AmOAuth2 (sfcc.products.rw). Update the variation attribute with the specified information. name slicing #### Parameters * `id` (path, string, required) The ID of the variation attribute to create. Minimum length: 1. Maximum length: 256. Example: `colour`. * `productId` (path, ProductId, required) * `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 ``` #### Request body (required) Media type: `application/json`. Schema: `VariationAttribute`. _Example: VariationAttributeRequestBody_ ``` { "attributeDefinitionId": "size", "attributeDefinitionName": { "default": "Screen Size" } } ``` #### Responses * **200** Updated variation attribute successfully. Media type: `application/json`. Schema: `VariationAttribute`. _Example VariationAttributeResult: same as GET /organizations/{organizationId}/products/{productId}/variation-attributes/{id} 200 response._ * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ * **404** Resource requested not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._ ### GET Get allowed attributes, values, and operators for creating rule-based categorization conditions. `GET /organizations/{organizationId}/categorization-attribute-definitions` Operation ID: `getCategorizationAttributeDefinitions`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Get the list of allowed attributes, values, and operators for creating rule-based categorization conditions. #### 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 ``` * `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified. _Example: LanguageCountry_ ``` en-US ``` _Example: CountryCode_ ``` US ``` #### Responses * **200** Categorization attribute definitions retrieved successfully. Media type: `application/json`. Schema: `CategorizationAttributeDefinitionsResult`. _Example: CategorizationAttributeDefinitionResult_ ``` { "limit": 1, "data": [ { "id": "ProductType", "attributeName": "Categorization Product Type", "allowedOperators": [ "equals", "not_equals" ], "allowedValues": [ "Item", "Master", "BundledProduct", "ProductSet", "SetProduct", "VariationGroup", "VariationProduct" ], "allowedDisplayValues": [ "Item", "Master", "BundledProduct", "ProductSet", "SetProduct", "VariationGroup", "VariationProduct" ], "attributeType": "categorization", "valueType": "enum-of-string" }, { "id": "CategoryId", "attributeName": "Categorization Category Id", "allowedOperators": [ "equals" ], "attributeType": "categorization", "valueType": "string" }, { "id": "OwningCatalogId", "attributeName": "Categorization Owning Catalog Id", "allowedOperators": [ "equals" ], "attributeType": "categorization", "valueType": "string" }, { "id": "brand", "attributeName": "Brand", "allowedOperators": [ "equals", "not_equals", "contains", "starts_with", "is_defined", "is_not_defined", "is_one_of", "not_one_of" ], "attributeType": "system", "valueType": "string" }, { "id": "RelevanceAttribute1", "attributeName": "RelevanceAttribute1", "allowedOperators": [ "equals", "not_equals", "contains", "starts_with", "is_defined", "is_not_defined", "is_one_of", "not_one_of" ], "attributeType": "custom", "valueType": "string" } ], "total": 5 } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ ### POST Search products. `POST /organizations/{organizationId}/product-search` Operation ID: `searchProducts`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Search for products. The query attribute specifies a complex query that can be used to narrow down the search. Attributes are grouped into different buckets. The following is a list of searchable attributes with their corresponding buckets: Main: | Attribute | Type | | --- | --- | | id | String | | name | String | | online | SiteSpecific Boolean | | searchable | SiteSpecific Boolean | | validFrom | SiteSpecfic DateTime | | validTo | SiteSpecfic DateTime | | type | ProductType | | creationDate | DateTime | | lastModified | DateTime | Catalog: | Attribute | Type | | --- | --- | | catalogId | String | Category: | Attribute | Type | | --- | --- | | categoryId | String | Special: type - {"item", "set, "bundle", "master", "partOfProductSet", "bundled", "variant", "variationGroup", "option", "retailSet", "partOfRetailSet"} The sortable properties are: | Attribute | Type | | --- | --- | | id | String | | name | String | | creationDate | DateTime | Note that catalogId is the ID of the catalog to which products are assigned Only attributes in the same bucket can be joined using a disjunction (OR). For instance, when joining id and catalogId, only a conjunction is allowed (AND), whereas id and searchable can be joined using a disjunction because they are in the same bucket. If an attribute is used in a disjunction (OR) that violates this rule, an exception is thrown. The product search retrieves additional properties of the product when expansions are used. The available expand attribute values are: * ‘all' retrieves all product properties. This is the default when no expand value is included in the request. * 'none' retrieves no expansion properties. * ‘availability' retrieves the following properties: * ats * inStock * online * ‘categories' retrieves the assignedCategories property. * ‘images' retrieves the image property. * ‘allImages' when used with images retrieves the following properties: * image * imageGroups * 'prices' retrieves the following properties: * price * priceCurrency * ‘sets' retrieves the following properties: * setProducts * productSets * ‘bundles' retrieves the following properties: * productBundles * bundledProduct #### 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 ``` * `siteId` (query, SiteId) The site context. #### Request body (required) Media type: `application/json`. Schema: `ProductSearchRequest`. _Example: ProductSearchRequestBody_ ``` { "query": { "textQuery": { "fields": [ "id" ], "searchPhrase": "apple-ipod-classic" } } } ``` #### Responses * **200** Product search completed successfully. Media type: `application/json`. Schema: `ProductSearchResult`. _Example: ProductSearchResult_ ``` { "limit": 2, "hits": [ { "brand": "Apple", "creationDate": "2019-02-21T22:10:02.000Z", "id": "apple-ipod-classic", "lastModified": "2019-09-17T19:13:39.000Z", "longDescription": { "default": { "markup": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats", "source": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats" } }, "name": { "default": "Apple iPod Classic" }, "onlineFlag": { "default": true }, "owningCatalogId": "electronics-catalog", "owningCatalogName": { "default": "Electronics Master Catalog" }, "pageDescription": { "default": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go." }, "pageKeywords": { "default": "Apple, iPod, iPod Classic, MP3, Music Player" }, "pageTitle": { "default": "Apple iPod Nano" }, "searchable": { "default": true }, "shortDescription": { "default": { "markup": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go.", "source": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go." } }, "type": { "master": true } }, { "brand": "Apple", "creationDate": "2019-09-04T16:07:43.000Z", "id": "apple-ipod-classic-1", "lastModified": "2019-09-04T16:19:03.000Z", "longDescription": { "default": { "markup": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats", "source": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats" } }, "name": { "default": "Apple iPod Classic" }, "onlineFlag": { "default": false }, "owningCatalogId": "electronics-catalog", "owningCatalogName": { "default": "Electronics Master Catalog" }, "pageDescription": { "default": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go." }, "pageKeywords": { "default": "Apple, iPod, iPod Classic, MP3, Music Player" }, "pageTitle": { "default": "Apple iPod Nano" }, "searchable": { "default": false }, "shortDescription": { "default": { "markup": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go.", "source": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go." } }, "type": { "variationGroup": true, "master": false } } ], "query": { "textQuery": { "fields": [ "id" ], "searchPhrase": "apple-ipod-classic" } }, "offset": 0, "total": 2 } ``` * **400** Bad Request. Thrown when a specified expand parameter value is unknown. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._ * **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._ ### POST Search for unassigned products. `POST /organizations/{organizationId}/unassigned-product-search` Operation ID: `searchUnassignedProducts`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw). Search for products that are not assigned to a specific category within a catalog. This endpoint helps identify products that exist in the catalog but are not categorized under the specified category. The query attribute specifies a complex query that can be used to narrow down the search. The catalogId and categoryId are required parameters to identify the catalog and category context. #### 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 ``` * `siteId` (query, SiteId) The site context. #### Request body (required) Media type: `application/json`. Schema: `UnassignedProductSearchRequest`. _Example: UnassignedProductSearchRequestBody_ ``` { "catalogId": "electronics-catalog", "categoryId": "electronics-gaming", "query": { "textQuery": { "fields": [ "id" ], "searchPhrase": "ipod" } }, "limit": 10, "offset": 0 } ``` #### Responses * **200** Unassigned product search completed successfully. Media type: `application/json`. Schema: `UnassignedProductSearchResult`. _Example: UnassignedProductSearchResult_ ``` { "catalogId": "electronics-catalog", "categoryId": "electronics-gamingx", "limit": 1, "hits": [ { "brand": "Apple", "creationDate": "2019-02-21T22:10:02.000Z", "id": "apple-ipod-nano", "lastModified": "2019-09-17T19:13:39.000Z", "longDescription": { "default": { "markup": "The iPod nano is a stylish and compact music player with a sleek design.", "source": "The iPod nano is a stylish and compact music player with a sleek design." } }, "name": { "default": "Apple iPod Nano" }, "onlineFlag": { "default": true }, "owningCatalogId": "electronics-catalog", "owningCatalogName": { "default": "Electronics Master Catalog" }, "pageDescription": { "default": "Experience music on the go with the Apple iPod Nano." }, "pageKeywords": { "default": "Apple, iPod, Nano, MP3, Music Player" }, "pageTitle": { "default": "Apple iPod Nano" }, "searchable": { "default": true }, "shortDescription": { "default": { "markup": "The iPod nano is a stylish and compact music player.", "source": "The iPod nano is a stylish and compact music player." } }, "type": { "item": true, "master": false } } ], "query": { "textQuery": { "fields": [ "id" ], "searchPhrase": "ipod" } }, "sorts": [ { "field": "id", "sortOrder": "asc" } ], "offset": 0, "total": 10 } ``` * **400** Bad Request. Returned when a specified query parameter is invalid or when required fields are missing. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: invalidExpandValue400_ ``` { "title": "Invalid Expand Value", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-expand-value", "detail": "The expand value 'does_not_exist' is invalid.", "expandValue": "does_not_exist" } ``` _Example: fieldNotSortable400_ ``` { "title": "Field Not Sortable", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable", "detail": "The field 'unsortableField' can't be used to sort the results.", "field": "unsortableField" } ``` _Example: malformedSelector400_ ``` { "title": "Malformed Selector", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-selector", "detail": "The property selector '**)' is malformed.", "selector": "**)" } ``` * **404** Not found. Media type: `application/problem+json`. Schema: `ErrorResponse`. _Example: catalogNotFound404_ ``` { "title": "Catalog Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/catalog-not-found", "detail": "No catalog with ID 'DoesnotExist' could be found.", "catalogId": "DoesnotExist" } ``` _Example: categoryNotFound404_ ``` { "title": "Category Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/category-not-found", "detail": "No category with ID 'DoesnotExist' for catalog 'WapiCatalog' could be found.", "categoryId": "DoesnotExist" } ``` ## Schemas ### ProductId The id (SKU) of the product. Type: `string`. Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`. ### 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`. ### SiteId The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites Type: `string`. Minimum length: 1. Maximum length: 32. Example: `RefArch`. ### Product Any product that is sold, shown alone, and does not have variations such as different sizes or colors. Product that has no reliance on any other product for inheritance. _A product has a SKU and can have a product option, which has a different SKU_. * `assignedCategories` (_array of CatalogCategoryId_) The catalog categories that the product is assigned to. It is read only. * `ats` (_number (double)_) The Available To Sell (ATS) inventory value of the product. This is a calculated value. Example: `15`. * `brand` (_string_) The brand of the product. Example: `Apple`. * `bundledProducts` (_array of Product_) The array of bundled products which the product includes. It is read only. * `classificationCategory` (_CatalogCategoryId_) * `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'. It is read only. Example: `253402214400`. * `defaultVariantId` (_string_) The ID of the product's default variant. It is read only. Example: `apple-ipod-classic-8gb-black`. * `ean` (_string_) The European Article Number of the product. Example: `ksdf69w4`. * `id` (_ProductId_, required) * `image` (_MediaFile_) * `imageGroups` (_array of ImageGroup_) The array of product image groups. It is read only. * `inStock` (_boolean_) The flag that indicates if the product is in stock, or not. This is a calculated value. Example: `true`. * `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'. It is read only. Example: `253402214400`. * `localizedTaxClassId` (_object_) The localized tax class identifier of the product. Additional properties: `string`. _Example_ ``` { "en_US": "exempt" } ``` * `longDescription` (_object_) The localized long description of the product. Additional properties: `MarkupText`. * `manufacturerName` (_string_) The name of the product's manufacturer. Example: `Apple`. * `manufacturerSku` (_string_) The SKU of the product's manufacturer. Example: `HSD68J`. * `master` (_Master_) * `name` (_object_) The localized name of the product. Additional properties: `string`. _Example_ ``` { "en_US": "Apple Ipod Classic" } ``` * `online` (_boolean_) The flag that indicates if the product is online, or not. This is a calculated value. Example: `true`. * `onlineFlag` (_object_) The site-specific online status of the product. Additional properties: `boolean`. _Example_ ``` { "Site1": true } ``` * `owningCatalogId` (_string_) The ID of the catalog that owns the product. Example: `apple-master-catalog`. * `owningCatalogName` (_object_) The localized name of the catalog that owns the product. It is read only. Additional properties: `string`. _Example_ ``` { "en_US": "Apple Master Catalog" } ``` * `pageDescription` (_object_) The localized page description of the product. Additional properties: `string`. _Example_ ``` { "en_US": "Page Description" } ``` * `pageKeywords` (_object_) The localized page keywords of the product. Additional properties: `string`. _Example_ ``` { "en_US": "Keywords" } ``` * `pageTitle` (_object_) The localized page title of the product. Additional properties: `string`. _Example_ ``` { "en_US": "Page Title" } ``` * `price` (_number (double)_) The price of the product. Example: `219.99`. * `priceCurrency` (_string_) The currency code for a product's price. Example: `USD`. * `pricePerUnit` (_number (double)_) The price per unit of the product. This is a read only field. Example: `1`. * `primaryCategories` (_array of CatalogCategoryId_) The primary catalog categories that the product is assigned to. It is read only. * `primaryCategoryId` (_string_) The ID of the products primary category. This is a read only field. It is read only. Example: `electronics-media-players`. * `productBundles` (_array of Product_) The array of product bundles which the product belongs to. It is read only. * `productOptions` (_array of ProductOption_) The array of product options. This is applicable for products of type "option". It is read only. * `productSets` (_array of Product_) The array of product sets which the product belongs to. It is read only. * `searchable` (_object_) The site-specific searchable status of the product. Additional properties: `boolean`. _Example_ ``` { "Site1": true } ``` * `setProducts` (_array of Product_) The array of set products which the product includes. It is read only. * `shortDescription` (_object_) The localized short description of the product. Additional properties: `MarkupText`. * `taxClassId` (_string_) The tax class identifier of the product. Example: `standard`. * `type` (_ProductType_) * `unit` (_string_) The sales unit of the product. Example: `single`. * `unitMeasure` (_string_) The unitMeasure of the product. Example: `each`. * `unitQuantity` (_number (double)_) The unitQuantity of the product. Example: `15`. * `upc` (_string_) The Universal Product Code (UPC) of the product. Example: `66JSD88JASD`. * `validFrom` (_object_) The valid/online from date of the product. Additional properties: `string`. _Example_ ``` { "default@SiteGenesis": "2000-05-11T00:00:00.000Z" } ``` * `validTo` (_object_) The valid/online to date of the product. Additional properties: `string`. _Example_ ``` { "default@SiteGenesis": "2050-05-11T00:00:00.000Z" } ``` * `variants` (_array of Variant_) The array of variants of the product. This is applicable for product types "master" and "variationGroup" only. It is read only. * `variationAttributes` (_array of VariationAttribute_) The sorted array of variation attributes assigned to the product. This is applicable for product types "master", "variationGroup" and "variant" only. It is read only. * `variationGroups` (_array of VariationGroup_) The array of variation groups in the product. This is applicable for product type "master" only. It is read only. * `variationValues` (_object_) The variation values selected for the product in variation attribute id and value pairs. This is applicable for product types "Variant" and "VariationGroup" only. It is read only. Additional properties: `string`. _Example_ ``` { "color": "red", "size": "8gb" } ``` ### 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`. ### VariantSearchRequest Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource. Includes all fields of `SearchRequest`. _Example_ ``` { "limit": 4, "query": { "textQuery": { "fields": [ "id", "description" ], "searchPhrase": "campaign" } }, "offset": 2 } ``` ### VariantSearchResult Document that represents a search on certificates and keys. Includes all fields of `PaginatedSearchResult`. * `hits` (_array of Variant_, required) An array of search hits (`Variant` objects). ### VariationGroups Document representing an unfiltered list of variation groups. Includes all fields of `PaginatedResultBase`. * `data` (_array of VariationGroup_, required) The array of variation group objects. ### VariationGroup Representation of a group of variant products by an attribute. This is a non-buyable entity, provides inheritable attributes for it's product variants, and is used for navigation. _Doesn't have a SKU._ * `orderable` (_boolean_) A flag indicating whether the variation group is orderable. Example: `true`. * `price` (_number (double)_) The sales price of the variation group. Example: `229.99`. * `productId` (_string_, required) The ID (SKU) of the variation group. Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic-black`. * `variationValues` (_object_) The actual variation attribute ID - value pairs. Additional properties: `string`. _Example_ ``` { "color": "red" } ``` ### Variants Document representing an unfiltered list of variants. Includes all fields of `PaginatedResultBase`. * `data` (_array of Variant_, required) An array of variants. ### Variant A product which is a variation within a master product that describes different colors, sizes, or other variation attributes. _Has a SKU_ * `ats` (_number (double)_) The Available To Sell (ATS) inventory value of the product. This is a calculated value. Example: `10`. * `defaultProductVariation` (_boolean_) A flag indicating whether the variant is a default variant. Example: `true`. * `image` (_MediaFile_) * `inStock` (_boolean_) True if the product is in stock, false if not. Example: `true`. * `online` (_boolean_) If the product is currently online. True if online, false if not. Example: `true`. * `orderable` (_boolean_) A flag indicating whether the variant is orderable. Example: `true`. * `price` (_number (double)_) The sales price of the variant. Example: `29.99`. * `priceCurrency` (_string_) Currency code for the price of the product. Example: `USD`. * `productId` (_ProductId_, required) * `searchable` (_object_) A flag indicating whether the variant is searchable. Additional properties: `boolean`. _Example_ ``` { "Site1": true } ``` * `variationAttributes` (_array of VariationAttribute_) Variation attributes. * `variationValues` (_object_) The actual variation attribute ID - value pairs. Additional properties: `string`. _Example_ ``` { "color": "black" } ``` ### CurrencyCode A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable. Type: `string`. Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`. ### ProductOptions Document representing an unfiltered list of product options. Includes all fields of `PaginatedResultBase`. * `data` (_array of ProductOption_, required) The array of product option objects. ### ProductOption Product options enable you to sell configurable products that have optional accessories, upgrades, or additional services. Options are always purchased with a product and can't be purchased separately. * `customName` (_object_) The localized custom name of the product option. Additional properties: `string`. _Example_ ``` { "en_US": "Warranty" } ``` * `defaultProductOptionValue` (_string_) The default product option value. Example: `5-years`. * `description` (_object_) The localized description of the product option. Additional properties: `string`. _Example_ ``` { "en_US": "Option Description" } ``` * `id` (_string_, required) The object attribute definition ID which is also the identifier for the product option. Minimum length: 1. Example: `warranty`. * `image` (_MediaFile_) * `name` (_string_) The name of the object attribute definition. Example: `Warranty`. * `selectedOptionValue` (_string_) The selected option value of the product option. Example: `2-years`. * `shared` (_boolean_) The flag that indicates if the product option is shared or local. Example: `false`. * `sortingMode` (_string_) The sorting mode for the product option values. Allowed values: `byexplicitorder`, `byoptionprice`. Example: `byoptionprice`. * `values` (_array of ProductOptionValue_) The sorted array of values of the product option. ### ProductOptionValue Document representing a product option Value * `defaultProductOptionValue` (_boolean_) Flag indicating if the product option value is the default value for the product option. Example: `true`. * `id` (_string_, required) The ID of the product option value. Minimum length: 1. Example: `5-year`. * `optionPrices` (_array of Money_) The list of prices in the product option value. * `skuExtension` (_string_) The SKU extension of the product option value. Example: `extension`. * `value` (_object_, required) The localized value of the product option. Additional properties: `string`. _Example_ ``` { "en_US": "5 Year Warranty" } ``` ### VariationAttributeValue Document representing a variation attribute value. * `description` (_object_) The localized description of the variation value. Additional properties: `string`. _Example_ ``` { "en_US": "Red" } ``` * `image` (_MediaFile_) * `imageSwatch` (_MediaFile_) * `name` (_object_) The localized display name of the variation value. Additional properties: `string`. _Example_ ``` { "color": "Red" } ``` * `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell. Example: `true`. * `position` (_number (double)_) The position of the value among all values of a variation attribute. Example: `2`. * `value` (_string_, required) The actual variation value. Minimum length: 1. Example: `red`. ### VariationAttributes Document representing an unfiltered list of variation attributes. Includes all fields of `PaginatedResultBase`. * `data` (_array of VariationAttribute_, required) The array of variation attribute objects. ### VariationAttribute Document representing a variation attribute. * `attributeDefinitionId` (_string_, required) The id of the requested attribute definition. Example: `color`. * `attributeDefinitionName` (_object_) The localized display name of the variation attribute definition. Additional properties: `string`. _Example_ ``` { "en_US": "Color" } ``` * `defaultValue` (_string_) Default variation attribute value. Example: `black`. * `id` (_string_) The ID of the variation attribute. Minimum length: 1. Example: `color`. * `name` (_object_) The localized display name of the variation attribute. Additional properties: `string`. _Example_ ``` { "en_US": "Color" } ``` * `shared` (_boolean_) Returns the value of attribute 'shared' if attribute is local or shared. Example: `false`. * `slicing` (_boolean_) Returns the value of attribute 'slicing'. Example: `true`. * `values` (_array of VariationAttributeValue_) The sorted array of variation values. This array can be empty. * `variationAttributeType` (_string_) Variation attribute type. Allowed values: `string`, `int`, `unknown`. Example: `string`. ### LocaleCode A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified. One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`. ### CategorizationAttributeDefinitionsResult The list of categorization attributes supported for rule based categorization. Includes all fields of `ResultBase`. * `data` (_array of CategorizationAttributeDefinition_, required) The list of the categorization attribute definitions. This can be empty. ### ProductSearchRequest Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource. Includes all fields of `SearchRequest`. _Example_ ``` { "limit": 4, "query": { "textQuery": { "fields": [ "id", "description" ], "searchPhrase": "campaign" } }, "offset": 2 } ``` ### ProductSearchResult Document representing a product search result. Includes all fields of `PaginatedSearchResult`. * `hits` (_array of Product_, required) A sorted array of search hits (`Product` objects). The array can be empty. ### UnassignedProductSearchRequest Document representing an unassigned product search request. This search finds products that are not assigned to a specific category within a catalog. Includes all fields of `SearchRequest`. * `catalogId` (_string_, required) The ID of the catalog to which the specified category belongs. Minimum length: 1. Maximum length: 256. Example: `electronics-catalog`. * `categoryId` (_string_, required) The ID of the category to which products are not assigned. Minimum length: 1. Maximum length: 256. Example: `electronics-gaming`. _Example_ ``` { "catalogId": "electronics-catalog", "categoryId": "electronics-gaming", "limit": 10, "query": { "textQuery": { "fields": [ "id" ], "searchPhrase": "ipod" } }, "offset": 0 } ``` ### UnassignedProductSearchResult Document representing an unassigned product search result. Contains products that are not assigned to the specified category. Includes all fields of `PaginatedSearchResult`. * `catalogId` (_string_) The ID of the catalog to which the specified category belongs. Minimum length: 1. Maximum length: 256. Example: `electronics-catalog`. * `categoryId` (_string_) The ID of the category to which products are not assigned. Minimum length: 1. Maximum length: 256. Example: `electronics-gaming`. * `hits` (_array of Product_, required) A sorted array of search hits (`Product` objects). If there are no hits, the array can be empty. ### CatalogCategoryId Document representing a catalog category ID. * `catalogId` (_CatalogId_, required) * `categoryId` (_CategoryId_, required) ### MediaFile Document representing media file. * `absUrl` (_string_) The absolute URL with request protocol. Example: `https://www.example-image.com/images/apple-ipod-classic.jpg`. * `alt` (_object_) The alternative image text. Additional properties: `string`. _Example_ ``` { "en_US": "iPod" } ``` * `disBaseUrl` (_string_) The Dynamic Image Service (DIS) base URL for product images only. Example: `https://www.dis-base-url/images/apple-ipod-clasic.jpg`. * `path` (_string_, required) The raw media file path. Example: `/images/apple-ipod-classic.jpg`. * `title` (_object_) The image title. Additional properties: `string`. _Example_ ``` { "en_US": "iPod" } ``` ### ImageGroup Document representing an image group containing a list of images for a particular view type and an optional variation value. * `images` (_array of MediaFile_, required) The images of the image group. * `variationAttributes` (_array of VariationAttribute_) Returns a list of variation attributes applying to this image group. * `viewType` (_string_, required) The image view type. Example: `hi-res`. ### MarkupText Document representing markup text. * `markup` (_string_, required) The rendered HTML. * `source` (_string_, required) The raw markup text. ### Master Representation of a group of variant products by an attribute. This is a non-buyable entity, provides inheritable attributes for it's product variants, and is used for navigation. _Does'nt have a SKU._ * `masterId` (_ProductId_, required) * `orderable` (_boolean_) A flag indicating whether at least one of the variants is orderable. Example: `true`. * `price` (_number (double)_) The minimum sales price of the related variants. Example: `199.99`. * `priceMax` (_number (double)_) The maximum sales of related variants. Example: `219.99`. * `prices` (_object_) prices Additional properties: `number (double)`. ### ProductType Document representing a product type. * `bundle` (_boolean_) A flag indicating whether the product is a bundle. Example: `false`. * `bundled` (_boolean_) A flag indicating whether the product is bundled. Example: `false`. * `item` (_boolean_) A flag indicating whether the product is a standard item. Example: `false`. * `master` (_boolean_, required) A flag indicating whether the product is a master. Example: `true`. * `option` (_boolean_) A flag indicating whether the product is an option. Example: `false`. * `partOfProductSet` (_boolean_) A flag indicating whether the product is part of product set. Example: `false`. * `partOfRetailSet` (_boolean_) A flag indicating whether the product is part of retail set. Example: `false`. * `retailSet` (_boolean_) A flag indicating whether the product is a retail set. Example: `false`. * `set` (_boolean_) A flag indicating whether the product is a set. Example: `false`. * `variant` (_boolean_) A flag indicating whether the product is a variant. Example: `false`. * `variationGroup` (_boolean_) A flag indicating whether the product is a variation group. Example: `false`. ### SearchRequest Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource. * `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200. Minimum: 1. Maximum: 200. Example: `10`. * `query` (_Query_, required) * `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed. * `offset` (_Offset_) ### PaginatedSearchResult Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`. Includes all fields of `PaginatedResultBase`. * `query` (_Query_, required) * `sorts` (_array of Sort_) The sorting that was applied to the result. * `hits` (_array of object_) The sorted array of search hits. Can be empty. _Example_ ``` { "limit": 1, "hits": [ { "couponId": "coupon1", "creationDate": "2019-10-20T12:00:00Z", "description": "This coupon is used to give 10% off stuff.", "enabled": false, "exportedCodeCount": 0, "lastModified": "2019-10-30T04:23:59Z", "redemptionCount": 3, "redemptionLimits": { "limitPerCode": 1, "limitPerCustomer": 1, "limitPerTimeFrame": { "limit": 2, "redemptionTimeFrame": 24 } }, "singleCode": "MyCode", "systemCodesConfig": { "codePrefix": "SG", "numberOfCodes": 500000 }, "totalCodesCount": 50, "type": "single_code" } ], "query": { "textQuery": { "fields": [ "id", "description" ], "searchPhrase": "stuff" } }, "sorts": [ { "field": "couponId", "sortOrder": "desc" } ], "offset": 2, "total": 8 } ``` ### PaginatedResultBase Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`. Includes all fields of `ResultBase`. * `offset` (_Offset_, required) ### Money A combination of a Currency and an amount of that Currency. * `currencyMnemonic` (_CurrencyCode_) * `value` (_number (double)_) The amount of money for the given currency. Example: `1234.56`. ### LanguageCountry A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'. Type: `string`. Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`. ### LanguageCode A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). Type: `string`. Pattern: ^\[a-z\]\[a-z\]$. Example: `en`. ### DefaultFallback A specialized value indicating the system default values for locales. Type: `string`. Default: `default`. Pattern: ^default$. Example: `default`. ### ResultBase Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned. * `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema. Example: `10`. * `total` (_Total_, required) ### CategorizationAttributeDefinition The categorization attribute definition. * `id` (_string_, required) The ID of the supported attribute. Maximum length: 256. Example: `producttype`. * `attributeName` (_string_) The display name of the supported attribute. Maximum length: 4000. Example: `Product Type`. * `attributeType` (_string_, required) The type of the attribute (custom/system/categorization). "system" indicates the System Attribute of the Product in ECOM, "custom" indicates the Custom Attribute of the Product in ECOM defined by merchant and "categorization" indicates the attribute used for categorization purposes ONLY and is not a defined attribute on the Product Object. Allowed values: `custom`, `system`, `categorization`. Example: `categorization`. * `valueType` (_string_, required) The value type of the attribute. Allowed values: `string`, `int`, `double`, `text`, `html`, `date`, `datetime`, `image`, `boolean`, `money`, `quantity`, `email`, `password`, `set-of-string`, `set-of-int`, `set-of-double`, `enum-of-string`, `enum-of-int`. Example: `string`. * `allowedOperators` (_array of string_, required) The list of allowed operators for this attribute based on its value type. Items: Allowed values: `starts_with`, `contains`, `equals`, `not_equals`, `greater_than`, `less_than`, `is_one_of`, `not_one_of`, `is_defined`, `is_not_defined`. Example: `equals`. _Example_ ``` [ "equals", "notEquals" ] ``` * `allowedValues` (_array of string_) The list of allowed values for this attribute IF its attributeType is an ENUM. Items: Maximum length: 4000. Example: `1`. _Example_ ``` [ 1, 2 ] ``` * `allowedDisplayValues` (_array of string_) The list of allowed Localized Display values for this attribute IF its attributeType is an ENUM based on the locale query param requested. If no locale query param value is provided "default" locale is assumed. Items: Maximum length: 4000. Example: `One`. _Example_ ``` [ "One", "Two" ] ``` ### CatalogId The ID of the catalog. Type: `string`. Minimum length: 1. Maximum length: 256. Example: `apparel-catalog`. ### CategoryId The ID of the category. Type: `string`. Minimum length: 1. Maximum length: 256. Example: `mens`. ### Query A set of objects that define criteria used to select records. A query can contain one of the following: * `MatchAllQuery` * Matches all documents. * `TermQuery` * Matches one or more documents against one or more document fields. * `TextQuery` * Matches text against one or more fields. * `BoolQuery` * Allows construction of a logical expression of multiple queries. * `FilteredQuery` * Allows a filter to be applied to a query. * `NestedQuery` * Allows you to query on nested documents. * _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._ Minimum properties: 1. Maximum properties: 1. * `boolQuery` (_BoolQuery_) * `filteredQuery` (_FilteredQuery_) * `matchAllQuery` (_MatchAllQuery_) * `nestedQuery` (_NestedQuery_) * `termQuery` (_TermQuery_) * `textQuery` (_TextQuery_) _Example_ ``` { "filteredQuery": { "query": { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "disabled" } }, "filter": { "termFilter": { "field": "enabled", "operator": "is", "values": [ false ] } } } } ``` ### Sort Document representing a sort request. Each API has a different default sort configuration that can be modified in the request. * `field` (_string_, required) The name of the field to sort on. Maximum length: 256. Example: `couponId`. * `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used. Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`. _Example_ ``` { "field": "couponId", "sortOrder": "desc" } ``` ### Offset The zero-based index of the first hit/data to include in the result. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `0`. ### Total The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated. Type: `integer (int32)`. Default: `0`. Minimum: 0. Example: `10`. ### BoolQuery A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses: * `must`, which combines as an `AND` operator. * `should`, which combines as an `OR` operator. * `must_not`, which combines as a `NOT` operator. If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example: ``` (must-1 AND must-1 AND ...) AND (should-1 OR should-2 OR ...) AND NOT (must_not-1 OR must_not-2 OR ...) ``` * `must` (_array of Query_) List of queries to be evaluated as an `AND` operator. * `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator. * `should` (_array of Query_) List of queries to be evaluated as an `OR` operator. _Example_ ``` { "value": { "must": [ { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "DEAL" } }, { "textQuery": { "fields": [ "description" ], "searchPhrase": "Big bargain deal" } } ], "mustNot": [ { "termQuery": { "fields": [ "enabled" ], "operator": "is", "values": [ false ] } } ] } } ``` ### FilteredQuery Allows to filter the result of a possibly complex query using a possibly complex filter. * `filter` (_Filter_, required) * `query` (_Query_, required) _Example_ ``` { "query": { "textQuery": { "fields": [ "couponId" ], "searchPhrase": "disabled" } }, "filter": { "termFilter": { "field": "enabled", "operator": "is", "values": [ false ] } } } ``` ### MatchAllQuery Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints. ### NestedQuery Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints. A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation. * `path` (_string_, required) The path to the nested document. Maximum length: 2048. Example: `order.shippingAddresses`. * `query` (_Query_, required) * `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score. Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`. _Example_ ``` { "path": "order.shippingAddresses", "query": { "boolQuery": { "must": [ { "boolQuery": { "must": [ { "termQuery": { "fields": [ "order.shippingAddresses.firstName" ], "operator": "is", "values": [ "John" ] } } ] } }, { "boolQuery": { "must": [ { "termQuery": { "fields": [ "order.shippingAddresses.lastName" ], "operator": "is", "values": [ "Doe" ] } } ] } } ] } }, "scoreMode": "avg" } ``` ### TermQuery A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator. **Limitations:** * The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise. * A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields. * `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator. Minimum items: 1. * `operator` (_string_, required) Returns the operator to use for the term query. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`. * `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator. Items: Example: `myCouponId`. ### TextQuery A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields. * `fields` (_array of Field_, required) The document fields that the search phrase matches against. Minimum items: 1. * `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces. Example: `campaign summer`. _Example_ ``` { "fields": [ "couponId" ], "searchPhrase": "limit" } ``` ### Filter Contains a set of objects that define criteria used to select records. A filter can contain one of the following: * `TermFilter` * Matches records where a field (or fields) exactly matches some simple value (including `null`). * `RangeFilter` * Matches records where a field value lies within a specified range. * `Range2Filter` * Matches records in a specified range across fields. * `QueryFilter` * Matches records based on a query. * `BoolFilter` * Provides filtering of records using a set of filters combined using a logical operator. Minimum properties: 1. Maximum properties: 1. * `boolFilter` (_BoolFilter_) * `queryFilter` (_QueryFilter_) * `range2Filter` (_Range2Filter_) * `rangeFilter` (_RangeFilter_) * `termFilter` (_TermFilter_) ### Field Name of the field. Might be a custom field name prefixed with c\_. Type: `string`. Maximum length: 260. Example: `couponId`. ### BoolFilter Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator. * `filters` (_array of Filter_) A list of filters that are logically combined by an operator. * `operator` (_string_, required) The logical operator that is used to combine the filters. Allowed values: `and`, `or`, `not`. Example: `and`. _Example_ ``` { "value": { "operator": "and", "filters": [ { "termFilter": { "field": "id", "operator": "is", "values": [ "myId" ] } }, { "termFilter": { "field": "couponId", "operator": "is", "values": [ "couponOne" ] } } ] } } ``` ### QueryFilter Wraps any query and allows it to be used as a filter. * `query` (_Query_, required) ### Range2Filter Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range. The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`. The second range (R2) is defined by `fromValue` and `toValue`. The filter mode specifies the method used to compare the two ranges: * `overlap`: R1 overlaps fully or partially with R2. * `containing`: R1 contains R2. * `contained`: R1 is contained in R2. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive. A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. * `filterMode` (_string_) Compare mode: overlap, containing, or contained. Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`. * `fromField` (_object_, required) The field name of the field that starts the first range. Example: `validFrom`. Includes all fields of `Field`. Example: `validFrom`. * `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. Example: `2007-01-01T00:00:00.000Z`. * `toField` (_object_, required) The field name of the field that ends the first range. Example: `validTo`. Includes all fields of `Field`. Example: `validTo`. * `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. Example: `2017-01-01T00:00:00.000Z`. _Example_ ``` { "fromField": "validFrom", "toField": "validTo", "filterMode": "overlap", "fromValue": "2007-01-01T00:00:00.000Z", "toValue": "2017-01-01T00:00:00.000Z" } ``` ### RangeFilter Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive. A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default. * `field` (_object_, required) The search field. Example: `validFrom`. Includes all fields of `Field`. Example: `validFrom`. * `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended. One of: `string (date-time)`, `integer`, `number`. * _string (date-time)_ Type: `string (date-time)`. Example: `2007-01-01T00:00:00.000Z`. * _integer_ Type: `integer`. Example: `1`. * _number_ Type: `number`. Example: `1`. * `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`. Default: `true`. Example: `true`. * `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended. One of: `string (date-time)`, `integer`, `number`. * _string (date-time)_ Type: `string (date-time)`. Example: `2007-01-02T00:00:00.000Z`. * _integer_ Type: `integer`. Example: `2`. * _number_ Type: `number`. Example: `2`. * `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`. Default: `true`. Example: `true`. ### TermFilter Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only. * `field` (_object_, required) The filter field. Includes all fields of `Field`. * `operator` (_string_, required) The operator used to compare the field's values with the given values. Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`. * `values` (_array of string_) The filter values. Items: Example: `myId`. _Example_ ``` { "field": "id", "operator": "is", "values": [ "myId" ] } ```