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

Categories resource (Shop API 23.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/v23_2/categories/({id},...,{id})?levels={Integer}&locale={String}

Formats

json, xml

Authentication

Name	Description
JWT	Authentication via Customer JWT.
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.	minIntegerValue=0
locale	String	The locale context.

Customization

This Resource supports server-side customization.

Extension Point	Method Detail
dw.ocapi.shop.category.beforeGET	beforeGET (categoryId : String ) : Status The function is called before the request will be processed. Parameters: categoryId - the id of the category 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

Extension Point

Method Detail

dw.ocapi.shop.category.beforeGET

beforeGET (categoryId : String ) : Status

The function is called before the request will be processed.

Parameters:: categoryId - the id of the category
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/v23_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" : "23.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/v23_2/categories/{id}?levels={Integer}&locale={String}

Formats

json, xml

Authentication

Name	Description
JWT	Authentication via Customer JWT.
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.	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.