Categories Resource (Shop API 17.2)

Summary

Http Method	Resource	Description
GET	/Categories/({Id},...,{Id})	When you use the URL template below, the server returns multiple categories (a result object of category documents). You can use this template as a convenient way of obtaining multiple categories in a single request, instead of issuing separate requests for each category. You can specify multiple ids (up to a maximum of 50). You must enclose the list of ids in parentheses. If a category identifier contains a parenthesis or the separator sign, you must URL encode the character. The server only returns online categories.
GET	/Categories/{Id}	When you use the URL template below, the server returns a category identified by its id; by default, the server also returns the first level of subcategories, but you can specify another level by setting the levels parameter. The server only returns online categories.

Get Multiple Categories

When you use the URL template below, the server returns multiple categories (a result object of category documents). You can use this template as a convenient way of obtaining multiple categories in a single request, instead of issuing separate requests for each category. You can specify multiple ids (up to a maximum of 50). You must enclose the list of ids in parentheses. If a category identifier contains a parenthesis or the separator sign, you must URL encode the character. The server only returns online categories.

Url

GET http://hostname:port/dw/shop/v17_2/categories/({id},...,{id})?levels={Integer}&locale={String}

Formats

json, xml

Authentication

Name	Description
JWT	Authentication via Customer JWT token.
None	No authentication.

Response Document

CategoryResult

Path Parameters

Parameter	Type	Description	Constraints
ids	[String]	The comma separated list of category ids.	maxItems=50, maxLength=256

Query Parameters

Parameter	Type	Description	Constraints
levels	Integer	Specifies how many levels of nested subcategories you want the server to return. The default value is 1. Valid values are 0, 1, or 2.	maxIntegerValue=2, minIntegerValue=0
locale	String	The locale context.

Customization

This Resource supports server-side customization.

Extension Point Method Detail

Extension Point	Method Detail
`dw.ocapi.shop.category.afterGET`	afterGET (doc : Document) : Status The function is called after the request has been processed. Parameters: doc - the document Returns: Status.OK for success. Status.ERROR in case something went wrong.

dw.ocapi.shop.category.afterGET

afterGET (doc : Document) : Status

The function is called after the request has been processed.

Parameters:

doc - the document

Returns:

Status.OK for success.
Status.ERROR in case something went wrong.

Sample

REQUEST:
GET /dw/shop/v17_2/categories/(mens,womens)?levels=0 HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=900,must-revalidate
{
  "_v":"17.2",
  "_type":"category_result",
  "count":2,
  "total":2,
  "data":
  [{
    "id":"mens",
    "name":"Mens",
    "description":"",
    "image":"http://foo.com.bar.jpg",
    "thumbnail":"http://foo.com.bar.jpg",
    "parent_category_id":"root"
  },{
    "id":"womens",
    "name":"Womens",
    "description":"",
    "image":"http://foo.com.bar.jpg",
    "thumbnail":"http://foo.com.bar.jpg",
    "parent_category_id":"root"
  }]
}

Get Category

When you use the URL template below, the server returns a category identified by its id; by default, the server also returns the first level of subcategories, but you can specify another level by setting the levels parameter. The server only returns online categories.

Url

GET http://hostname:port/dw/shop/v17_2/categories/{id}?levels={Integer}&locale={String}

Formats

json, xml

Authentication

Name	Description
JWT	Authentication via Customer JWT token.
None	No authentication.

Response Document

Category

Path Parameters

Parameter	Type	Description	Constraints
id	String	The id of the requested category.	maxLength=256

Query Parameters

Parameter	Type	Description	Constraints
levels	Integer	Specifies how many levels of nested subcategories you want the server to return. The default value is 1. Valid values are 0, 1, or 2.	maxIntegerValue=2, minIntegerValue=0
locale	String	The locale context.

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description

404

Status	Type	Arguments	Description
404	`CategoryNotFoundException`	categoryId (String) siteId (String)	Thrown if the server could not find an online category with the specified id.

CategoryNotFoundException

categoryId (String)

siteId (String)

Thrown if the server could not find an online category with the specified id.

Customization

This Resource supports server-side customization.

Extension Point Method Detail

Extension Point	Method Detail
`dw.ocapi.shop.category.modifyGETResponse`	modifyGETResponse (scriptCategory : Category , doc : Category ) : Status The function is called after the request has been processed. Parameters: scriptCategory - an instance of dw.catalog.Category doc - the document Returns: a non-null Status ends the hook execution

dw.ocapi.shop.category.modifyGETResponse

modifyGETResponse (scriptCategory : Category , doc : Category ) : Status

The function is called after the request has been processed.

Parameters:: scriptCategory - an instance of dw.catalog.Category; doc - the document
Returns:: a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v17_2/categories/root?levels=2 HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=900,must-revalidate
{
  "_v":"17.2",
  "_type":"category",
  "id":"root",
  "categories":[
  {
    "id":"mens",
    "name":"Mens",
    "description":"",
    "image":"http://foo.com.bar.jpg",
    "thumbnail":"http://foo.com.bar.jpg",
    "parent_category_id":"root",
    "categories":[{
      "id":"footwear",
      "name":"Footwear",
      "description":"",
      "image":"http://foo.com.bar.jpg",
      "thumbnail":"http://foo.com.bar.jpg",
      "parent_category_id":"mens"
    },{
      "id":"clothing",
      "name":"Clothing",
      "description":"",
      "image":"http://foo.com.bar.jpg",
      "thumbnail":"http://foo.com.bar.jpg",
      "parent_category_id":"mens"
    }]
  },
  {
    "id":"womens",
    "name":"Womens",
    "description":"",
    "image":"http://foo.com.bar.jpg",
    "thumbnail":"http://foo.com.bar.jpg",
    "parent_category_id":"root",
    "categories":[{
      "id":"footwear",
      "name":"Footwear",
      "description":"",
      "image":"http://foo.com.bar.jpg",
      "thumbnail":"http://foo.com.bar.jpg",
      "parent_category_id":"womens"
    },{
      "id":"clothing",
      "name":"Clothing",
      "description":"",
      "image":"http://foo.com.bar.jpg",
      "thumbnail":"http://foo.com.bar.jpg",
      "parent_category_id":"womens"
    }]
  }]
}

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.