Salesforce B2C Commerce 24.7 > Open Commerce API 23.2 > Data API resources 23.2

Categories resource (Data API 23.2)

Summary

Http Method Resource Description
GET /catalogs/{catalog_id}/categories Action to get all the categories with no filtering.
PUT /catalogs/{catalog_id}/categories/{category_id} Creates a catalog category using the information provided.
PATCH /catalogs/{catalog_id}/categories/{category_id} Updates a catalog category using the information provided.
GET /catalogs/{catalog_id}/categories/{category_id} Action to read an existing category within a catalog. By default, the server also returns the first level of sub-categories, but you can specify another level by setting the levels parameter. Please note, using a large value for levels may cause performance issues in case of a large and deep category tree.
DELETE /catalogs/{catalog_id}/categories/{category_id} Deletes the category by catalog ID and category ID
PUT /catalogs/{catalog_id}/categories/{category_id}/products/{product_id}

Creates a category product assignment using the information provided;

As the assigned position n is a normalized target position, we'll make sure that the product is assigned to a position so that the order of positions are maintained. For example, product A, B, C at position 1, 2, 3. product D is assigned to position 2, the end result is A, D, B, C with order of positions 1, 2, 3, 4;

If there are n existing positioned assignment, assigning a new product to position >= n+1 will end with new assignment with position n+1.
PATCH /catalogs/{catalog_id}/categories/{category_id}/products/{product_id}

Updates the category product assignment with the specified information, such as position.

As the assigned position n is a normalized target position, we'll make sure that the product is assigned to a position so that the order of positions are maintained.

For example, if we have products A, B, C, D at positions 1, 2, 3, 4 and update product A with new position 3, the end result is B, C, A, D with order of positions 1, 2, 3, 4.

If we then update product C to no position, the end result is B, A, D, C with order of positions 1, 2, 3, null.

If there are n existing positioned assignment, updating product to position >= n will end with new assignment with position such that the order of positions is maintained.
DELETE /catalogs/{catalog_id}/categories/{category_id}/products/{product_id} Removes a category product assignment;

For example, if we have products A, B, C at positions 1, 2, 7.5 and delete assignment for product B, this will end up the products A, B, C at positions 1, null, 7.5.
GET /catalogs/{catalog_id}/categories/{category_id}/products/{product_id} Retrieves category product assignment information. Expands that can be applied for the get request
  • product_base - String
  • product_images - String - to fetch image groups specified for the given product
  • product_all_images - String - to fetch image groups specified for the given product plus images for its variants and variation groups

Get Categories

Action to get all the categories with no filtering.

Url

GET https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories?start={Integer}&count={Integer}&select={String}&expand={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

Categories

Path Parameters

Parameter Type Description Constraints
catalog_id String   minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
count Integer Optional count for retrieving only a subset of the items (default is 25).  
expand String    
select String The property selector.  
start Integer Optional start index for retrieving the items from a given index (default 0).  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CatalogNotFoundException

catalogId (String)

 Indicates that the catalog is not provided in the request.

Sample

REQUEST:
GET /s/-/dw/data/v23_2/catalogs/main-catalog/categories?expand=vm&select=(**) HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTPS/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=900,must-revalidate
{
  "_v" : "23.2",
  "count" : 1,
  "data" : [
      "_v" : "23.2",
      "_type" : "category",
      "categories" :
      [
         {
            "_type" : "category",
            "creation_date" : "2015-11-30T18:48:37.333Z",
            "description" :
            {
               "default" : "sub-category 1 for main catalog"
            },
            "id" : "sub-category-1",
            "image" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20image",
            "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/main-catalog/categories/sub-category-1",
            "name" :
            {
               "default" : "Sub-category 1"
            },
            "online" : true,
            "parent_category_id" : "root",
            "paths" :
            [
               {
                  "_type" : "path_record",
                  "id" : "sub-category-1",
                  "name" :
                  {
                     "default" : "Sub-category 1"
                  }
               }
            ],
            "position" : 1.0,
            "thumbnail" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20thumbnail"
         }
      ],
      "creation_date" : "2015-11-29T18:48:37.333Z",
      "description" :
      {
         "default" : "root category for main catalog"
      },
      "id" : "root",
      "image" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20image",
      "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/main-catalog/categories/root",
      "name" :
      {
         "default" : "Root Category"
      },
      "online" : true,
      "paths" :
      [
         {
            "_type" : "path_record",
            "id" : "root",
            "name" :
            {
               "default" : "root"
            }
         }
      ],
      "position" : 1.0,
      "sorting_rules" :
      [
         {
            "_type" : "sorting_rule",
            "creation_date" : "2015-11-19T20:46:37.000Z",
            "description" : "Sorts by price ascending",
            "id" : "price-low-to-high",
            "product_sorting_rule_steps" :
            [

               {
                  "_type" : "sorting_rule_step",
                  "direction" : "Ascending",
                  "is_system" : false,
                  "position" : 0,
                  "text_relevance_included" : false,
                  "type_id" : "price"
               }
            ],
            "site" : "main-site"
         }
      ],
      "thumbnail" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20thumbnail",
   }],
   "select": "**",
   "start": 0,
   "total": 1
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CatalogNotFoundException",
    "message":"No catalog with ID 'main-catalog' was found."
  }
}

Create Category

Creates a catalog category using the information provided.

Url

PUT https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

Category

Response Document

Category

Path Parameters

Parameter Type Description Constraints
catalog_id String The id of the catalog. minLength=1
category_id String The id of the category to be created maxLength=256, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 CategoryInvalidException

catalogId (String)

categoryId (String)

field (String)

 Indicates that the category in the request is not valid (the argument indicates the field that was invalid).
400 IdConflictException

bodyID (String)

urlID (String)

 Indicates that the category ID in the request URL does not match the category ID in the request body.
404 CatalogNotFoundException

catalogId (String)

 Indicates that the catalog is not provided in the request.

Sample

REQUEST:
PUT /s/-/dw/data/v23_2/catalogs/main-catalog/categories/category1 HTTP/1.1
Host: example.com
Accept: application/json
{ 
  "description" : "category 1 description", 
  "id" : "category1", 
  "image": "demandware.jpg",
  "name" : "category 1 name", 
  "page_description": "category 1 page description",
  "page_keywords": "category 1 page keywords",
  "page_title": "category 1 page title",
  "parent_category_id" : "root", 
  "online" : true,
  "position": 2,
  "thumbnail": "demandware-thumb.jpg"
}

RESPONSE:
HTTPS/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=900,must-revalidate
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "category",
   "creation_date" : "2015-12-15T19:57:23.421Z",
   "description" : 
   {
      "default" : "category 1 description"
   },
   "id" : "category1",
   "image" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1450204042887/demandware.jpg",
   "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/main-catalog/categories/category1",
   "name" : 
   {
      "default" : "category 1 name"
   },
   "online" : true,
   "page_description" : 
   {
      "default" : "category 1 page description"
   },
   "page_keywords" : 
   {
      "default" : "category 1 page keywords"
   },
   "page_title" : 
   {
      "default" : "category 1 page title"
   },
   "parent_category_id" : "root",
   "position" : 2.0,
   "thumbnail" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1450204042887/demandware-thumb.jpg"
}


# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CatalogNotFoundException",
    "message":"No catalog with ID 'main-catalog' was found."
  }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CategoryDuplicateException",    
    "message":"The category could not be created because of duplicate ID 'category2' in catalog 'main-catalog'."
  }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"IdConflictException",
    "message":"The ID in the request body ('category1') does not match the ID in the URL ('category2')."
  }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CategoryInvalidException",
    "message":"The field 'parent_category_id' for the category with catalog ID ''main-catalog' and category ID 'category1' is invalid."
  }
}

Update Category

Updates a catalog category using the information provided.

Url

PATCH https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

Category

Response Document

Category

Path Parameters

Parameter Type Description Constraints
catalog_id String The id of the catalog. minLength=1
category_id String The id of the category maxLength=256, minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 CategoryInvalidException

catalogId (String)

categoryId (String)

field (String)

 Indicates that the category in the request is not valid (the argument indicates the field that was invalid).
404 CatalogNotFoundException

catalogId (String)

 Indicates that the catalog is not provided in the request.
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Indicates that the category does not exist for the catalog provided in the request.

Sample

REQUEST:
PATCH /s/-/dw/data/v23_2/catalogs/main-catalog/categories/category1 HTTP/1.1
Host: example.com
Accept: application/json
{
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "description" : "category 1 description", 
   "id" : "category1", 
   "image": "demandware.jpg",
   "name" : "category 1 name", 
   "online" : true,
   "page_description": "category 1 page description",
   "page_keywords": "category 1 page keywords",
   "page_title": "category 1 page title",
   "parent_category_id" : "category2", 
   "position" : 5, 
   "thumbnail": "demandware-thumb.jpg"
}

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=900,must-revalidate
{
   "_v" : "23.2",
   "_resource_state" : "045f07bb655171dc37d8eb8bf4b0db7ac1fb3a160002eb96fbe6e2f95aa4b6cc",
   "_type" : "category",
   "description" : 
   {
      "default" : "category 1 description"
   },
   "id" : "category1",
   "image" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1450204042887/demandware.jpg",
   "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/main-catalog/categories/category1",
   "name" : 
   {
      "default" : "category 1 name"
   },
   "online" : true,
   "page_description" : 
   {
      "default" : "category 1 page description"
   },
   "page_keywords" : 
   {
      "default" : "category 1 page keywords"
   },
   "page_title" : 
   {
      "default" : "category 1 page title"
   },
   "parent_category_id" : "category2",
   "position" : 5.0,
   "thumbnail" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1450204042887/demandware-thumb.jpg"
}


# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CategoryNotFoundException",
       "message":"No category with ID 'category1' for catalog 'main-catalog' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CatalogNotFoundException",
    "message":"No catalog with ID 'main-catalog' was found."
  }
}

RESPONSE:
HTTP/1.1 400 Bad Request
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CategoryInvalidException",
    "message":"The field 'parent_category_id' for the category with catalog ID ''main-catalog' and category ID 'category1' is invalid."
  }
}

Get category

Action to read an existing category within a catalog. By default, the server also returns the first level of sub-categories, but you can specify another level by setting the levels parameter. Please note, using a large value for levels may cause performance issues in case of a large and deep category tree.

Url

GET https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}?levels={Integer}&expand={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

Category

Path Parameters

Parameter Type Description Constraints
catalog_id String the id of the catalog that the category belongs to minLength=1, nullable=false
category_id String the id of the category requested maxLength=256, minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
expand String the expansion that client can use to specify and retrieve further information about the category (Internal use only for now).  
levels Integer Specifies how many levels of nested sub-categories you want the server to return. The default value is 1. minIntegerValue=0

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CatalogNotFoundException

catalogId (String)

 Indicates that the catalog is not provided in the request.
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Indicates that the category does not exist for the catalog provided in the request.

Sample

REQUEST:
GET /s/-/dw/data/v23_2/catalogs/main-catalog/categories/root HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTPS/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=900,must-revalidate
{
   "_v" : "23.2",
   "_resource_state" : "43c2d7a118bd0a4034399ed86c86654b40c198ea64fd3195e5587d9211d10d7e",
   "_type" : "category",
   "categories" : 
   [
      {
         "_type" : "category",
         "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
         "creation_date" : "2015-11-30T18:48:37.333Z",
         "description" : 
         {
            "default" : "sub-category 1 for main catalog"
         },
         "id" : "sub-category-1",
         "image" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20image",
         "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/main-catalog/categories/sub-category-1",
         "name" : 
         {
            "default" : "Sub-category 1"
         },
         "online" : true,
         "parent_category_id" : "root",
         "paths" : 
         [
            
            {
               "_type" : "path_record",
               "id" : "main-catalog",
               "name" : 
               {
                  "default" : "Main Catalog"
               }
            },
            
            {
               "_type" : "path_record",
               "id" : "root",
               "name" : 
               {
                  "default" : "root category"
               }
            },
            
            {
               "_type" : "path_record",
               "id" : "sub-category-1",
               "name" : 
               {
                  "default" : "Sub-category 1"
               }
            }
         ],
         "position" : 1.0,
         "thumbnail" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20thumbnail"
      },
      {
         "_type" : "category",
          "_resource_state" : "045f07bb655171dc37d8eb8bf4b0db7ac1fb3a160002eb96fbe6e2f95aa4b6cc",
         "creation_date" : "2015-12-02T18:48:37.333Z",
         "description" : 
         {
            "default" : "sub-category 2 for main catalog"
         },
         "id" : "sub-category-2",
         "image" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20image",
         "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/main-catalog/categories/sub-category-2",
         "name" : 
         {
            "default" : "Sub-category 2"
         },
         "online" : true,
         "parent_category_id" : "root",
         "paths" : 
         [
            {
               "_type" : "path_record",
               "id" : "main-catalog",
               "name" : 
               {
                  "default" : "Main Catalog"
               }
            },
            
            {
               "_type" : "path_record",
               "id" : "root",
               "name" : 
               {
                  "default" : "root category"
               }
            },
            
            {
               "_type" : "path_record",
               "id" : "sub-category-2",
               "name" : 
               {
                  "default" : "Sub-category 2"
               }
            }
         ],
         "position" : 2.0,
         "thumbnail" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20thumbnail"
      }
   ],
   "creation_date" : "2015-11-29T18:48:37.333Z",
   "description" : 
   {
      "default" : "root category for main catalog"
   },
   "id" : "root",
   "image" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20image",
   "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/main-catalog/categories/root",
   "name" : 
   {
      "default" : "Root Category"
   },
   "online" : true,
   "paths" : 
   [
      
      {
         "_type" : "path_record",
         "id" : "main-catalog",
         "name" : 
         {
            "default" : "Main Catalog"
         }
      },
      
      {
         "_type" : "path_record",
         "id" : "root",
         "name" : 
         {
            "default" : "root"
         }
      }
   ],
   "position" : 1.0,
   "sorting_rules" : 
   [
      {
         "_type" : "sorting_rule",
         "creation_date" : "2015-11-19T20:46:37.000Z",
         "description" : "Sorts by price ascending",
         "id" : "price-low-to-high",
         "product_sorting_rule_steps" : 
         [
            
            {
               "_type" : "sorting_rule_step",
               "direction" : "Ascending",
               "is_system" : false,
               "position" : 0,
               "text_relevance_included" : false,
               "type_id" : "price"
            }
         ],
         "site" : "main-site"
      },
      {
         "_type" : "sorting_rule",
         "creation_date" : "2015-11-19T20:46:37.000Z",
         "description" : "Sorts by price ascending",
         "id" : "price-low-to-high",
         "product_sorting_rule_steps" : 
         [
            
            {
               "_type" : "sorting_rule_step",
               "direction" : "Ascending",
               "is_system" : false,
               "position" : 0,
               "text_relevance_included" : false,
               "type_id" : "price"
            }
         ],
         "site" : "main-site"
      }
   ],
   "thumbnail" : "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20thumbnail",
}


# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CategoryNotFoundException",
    "message":"No category with ID 'root' for catalog 'main-catalog' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CatalogNotFoundException",
    "message":"No catalog with ID 'main-catalog' was found."
  }
}

Delete Category

Deletes the category by catalog ID and category ID

Url

DELETE https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
catalog_id String The site context. minLength=1, nullable=false
category_id String The category id to remove minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CatalogNotFoundException

catalogId (String)

 Indicates that the catalog is not provided in the request.
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Indicates that the category does not exist for the catalog provided in the request.

Sample

REQUEST:
DELETE /s/-/dw/data/v23_2/catalogs/main-catalog/categories/category1  HTTP/1.1
Host: example.com
Accept: application/json
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

RESPONSE:
HTTPS/1.1 204 NO CONTENT

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CategoryNotFoundException",
    "message":"No category with ID 'category1' for catalog 'main-catalog' was found."
  }
}

RESPONSE:
HTTP/1.1 404 Not Found
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"CatalogNotFoundException",
    "message":"No catalog with ID 'main-catalog' was found."
  }
}

Create Category Product Assignment

Creates a category product assignment using the information provided;

As the assigned position n is a normalized target position, we'll make sure that the product is assigned to a position so that the order of positions are maintained. For example, product A, B, C at position 1, 2, 3. product D is assigned to position 2, the end result is A, D, B, C with order of positions 1, 2, 3, 4;

If there are n existing positioned assignment, assigning a new product to position >= n+1 will end with new assignment with position n+1.

Url

PUT https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}/products/{product_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CategoryProductAssignment

Response Document

CategoryProductAssignment

Path Parameters

Parameter Type Description Constraints
catalog_id String The id of the requested catalog to which to assign the product. minLength=1
category_id String The id of the requested category to which to assign the product. minLength=1
product_id String The id (SKU) of the requested product to assign. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 IdConflictException

bodyID (String)

urlID (String)

 if the Id in request is not the same as the ID in document.
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Thrown if the category does not exist matching the given id.
404 CatalogNotFoundException

catalogId (String)

 Thrown if the catalog does not exist matching the given id.
404 ProductNotFoundException

productId (String)

 Thrown if the product does not exist matching the given id.

Sample

REQUEST:
PUT /s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory/products/MyProduct HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
  "position":1
}

# in case of success:

RESPONSE:
HTTP/1.1 201 CREATED
Content-Length: 67
Location: https://example.com/s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory/products/MyProduct
Content-Type: application/json; charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "category_product_assignment",
   "catalog_id" : "MyCatalog",
   "category_id" : "MyCategory",
   "link": "https://example.com/s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory/products/MyProduct",
   "owning_catalog_name" : 
   {
      "default" : "My Catalog"
   },
   "position" : 1.0,
   "product_id" : "MyProduct",
   "product_name" : 
   {
      "default" : "My Product"
   }
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "23.2",
   "fault" : 
   {
      "type" : "CategoryNotFoundException",
      "message" : "No category with ID 'MyCategory' for catalog 'MyCatalog' was found."
   }
}

Update Category Product Assignment

Updates the category product assignment with the specified information, such as position.

As the assigned position n is a normalized target position, we'll make sure that the product is assigned to a position so that the order of positions are maintained.

For example, if we have products A, B, C, D at positions 1, 2, 3, 4 and update product A with new position 3, the end result is B, C, A, D with order of positions 1, 2, 3, 4.

If we then update product C to no position, the end result is B, A, D, C with order of positions 1, 2, 3, null.

If there are n existing positioned assignment, updating product to position >= n will end with new assignment with position such that the order of positions is maintained.

Url

PATCH https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}/products/{product_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CategoryProductAssignment

Response Document

CategoryProductAssignment

Path Parameters

Parameter Type Description Constraints
catalog_id String The id of the requested catalog to which the product is assigned. minLength=1
category_id String The id of the requested category to which the product is assigned. minLength=1
product_id String The id (SKU) of the requested assigned product. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Thrown if the category does not exist matching the given id.
404 CatalogNotFoundException

catalogId (String)

 Thrown if the catalog does not exist matching the given id.
404 ProductNotFoundException

productId (String)

 Thrown if the product does not exist matching the given id.
404 CategoryProductAssignmentNotFoundException

catalogId (String)

categoryId (String)

siteId (String)

 Thrown if the category product assignment does not exist.

Sample

REQUEST:
PATCH /s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory/products/MyProduct HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "position":2
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "category_product_assignment",
   "catalog_id" : "MyCatalog",
   "category_id" : "MyCategory",
   "link": "https://example.com/s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory/products/MyProduct",
   "owning_catalog_name" : 
   {
      "default" : "My Catalog"
   },
   "position" : 2.0,
   "product_id" : "MyProduct",
   "product_name" : 
   {
      "default" : "My Product"
   }
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
   "_type":"fault",
  "fault":{
    "type":"CategoryProductAssignmentNotFoundException",
    "message":"No product category assignment with catalog ID MyCatalog and category id MyCategory and product id MyProduct was found."
  }
}

Delete Category Product Assignment

Removes a category product assignment;

For example, if we have products A, B, C at positions 1, 2, 7.5 and delete assignment for product B, this will end up the products A, B, C at positions 1, null, 7.5.

Url

DELETE https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}/products/{product_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
catalog_id String The catalog of the assignment. minLength=1
category_id String The id of the requested category. minLength=1
product_id String The id of the requested product to un-assign. minLength=1, nullable=false

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Thrown if the category does not exist matching the given id.
404 CatalogNotFoundException

catalogId (String)

 Thrown if the catalog does not exist matching the given id.

Sample

REQUEST:
DELETE /s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory/products/product1 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

Get Category Product Assignment

Retrieves category product assignment information. Expands that can be applied for the get request
  • product_base - String
  • product_images - String - to fetch image groups specified for the given product
  • product_all_images - String - to fetch image groups specified for the given product plus images for its variants and variation groups

Url

GET https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}/products/{product_id}?site_id={String}&expand={String}&select={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

CategoryProductAssignment

Path Parameters

Parameter Type Description Constraints
catalog_id String The catalog of the assignment. minLength=1
category_id String The id of the requested category. minLength=1
product_id String The id (SKU) of the requested assigned product. minLength=1

Query Parameters

Parameter Type Description Constraints
expand String The List of expansion values applied to the product associated to the assignment.  
select String The selector for the get. If not passed, then the defaultSelector will be used instead.  
site_id String The site context.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Thrown if the category does not exist matching the given id.
404 CatalogNotFoundException

catalogId (String)

 Thrown if the catalog does not exist matching the given id.
404 ProductNotFoundException

productId (String)

 Thrown if the product does not exist matching the given id.
404 CategoryProductAssignmentNotFoundException

catalogId (String)

categoryId (String)

siteId (String)

 Thrown if the category product assignment does not exist matching the given ids.

Sample

REQUEST:
GET /s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory/products/MyProduct HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Aug-2014 00:00:00 GMT
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_type" : "category_product_assignment",
   "catalog_id" : "MyCatalog",
   "category_id" : "MyCategory",
   "link": "https://example.com/s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory/products/MyProduct",
   "owning_catalog_name" : 
   {
      "default" : "My Catalog"
   },
   "product_id" : "MyProduct",
   "product_name" : 
   {
      "default" : "My Product"
   }
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 NOT FOUND
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
   "_type":"fault",
  "fault":{
    "type":"CategoryProductAssignmentNotFoundException",
    "message":"No product category assignment with catalog ID 'MyCatalog' and category id 'MyCategory' and product id 'MyProduct' was found."
  }
}

Infocenter Retirement: On June 30, 2023, the Infocenter was retired, and documentation currently hosted on the Infocenter will be published to Salesforce Help, Commerce Cloud Developer Center, and Salesforce B2C Commerce Developer Documentation Resources. For more information, see the release note.

X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.