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

CategoryLinks resource (Data API 23.2)

Summary

Http Method Resource Description
GET /catalogs/{catalog_id}/categories/{category_id}/category_links Action to get a set of outgoing category links in a given catalog category, sorted by position.
GET /catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type} Action to get category link information.
PATCH /catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type} Updates the category link with the specified information.
DELETE /catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type} Deletes the category link by ID
PUT /catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type} Creates a category link using the information provided. If a category link with the same unique identifier, it will be updated with the new position.

Get Category Links

Action to get a set of outgoing category links in a given catalog category, sorted by position.

Url

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

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

CategoryLinks

Path Parameters

Parameter Type Description Constraints
catalog_id String The id of the catalog. minLength=1
category_id String The id of the source category. minLength=1

Query Parameters

Parameter Type Description Constraints
count Integer    
select String Optional select clause for getting fields from the returned JSON document.  
start Integer    

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CatalogNotFoundException

catalogId (String)

 Thrown in case the source catalog does not exist
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Thrown in case the source category does not exist

Sample

REQUEST:
GET  /s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory1/category_links?select=(**) 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
Content-Length: 67
Content-Type: application/json; charset=UTF-8
{
  "_v" : "23.2",
  "count" : 2,
  "data" : [
    {
       "_v" : "23.2",
       "_type" : "category_link",
       "last_modified" : "2015-11-18.75:15:24.827Z",
       "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category1/other",
       "position" : 1.0,
       "source_catalog_id" : "MyCatalog",
       "source_catalog_name": { "default": "My Catalog" },
       "source_category_id" : "MyCategory1",
       "source_category_name": { "default": "My Awesome Category" },
       "target_catalog_id" : "OtherCatalog",
       "target_catalog_name": { "default": "That Other Catalog" },
       "target_category_id" : "Category1",
       "target_category_name": { "default": "Category 1" },
       "type" : "other"
    },
    {
       "_v" : "23.2",
       "_type" : "category_link",
       "last_modified" : "2015-11-19T15:15:24.000Z",
       "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category2/other",
       "position" : 2.0,
       "source_catalog_id" : "MyCatalog",
       "source_catalog_name": { "default": "My Catalog" },
       "source_category_id" : "MyCategory1",
       "source_category_name": { "default": "My Awesome Category" },
       "target_catalog_id" : "OtherCatalog",
       "target_catalog_name": { "default": "That Other Catalog" },
       "target_category_id" : "Category2",
       "target_category_name": { "default": "Category 2" },
       "type" : "other"
    }
  ],
  "select": "(**)",
  "start" : 0,
  "total" : 2
}

# 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":"CatalogNotFoundException",
    "message":"No catalog with ID 'WapiCatalog' was found."
  }
}

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 'category1' for catalog 'main-catalog' was found."
  }
}

Get Category Link

Action to get category link information.

Url

GET https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type}?select={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

CategoryLink

Path Parameters

Parameter Type Description Constraints
catalog_id String The id of the source catalog. minLength=1
category_id String The id of the source category. minLength=1
target_catalog_id String The id of the target catalog. minLength=1
target_category_id String The id of the target category. minLength=1
type Enum {other, accessories, cross_selling, up_selling, spare_parts} the link type  

Query Parameters

Parameter Type Description Constraints
select String Optional select clause for getting fields from the returned JSON document.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CatalogNotFoundException

catalogId (String)

 Thrown in case the source catalog or the target catalog do not exist
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Thrown in case the source category or the target category do not exist
404 CategoryLinkNotFoundException

sourceCatalogId (String)

sourceCategoryId (String)

targetCatalogId (String)

targetCategoryId (String)

linkType (Enum {other, accessories, cross_selling, up_selling, spare_parts})

 Thrown in case the category link does not exist from the source catalog/category to the destination catalog/category with the given type.

Sample

REQUEST:
GET  /s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category1/other 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
Content-Length: 67
Content-Type: application/json; charset=UTF-8
{
    "_v" : "23.2",
    "_type" : "category_link",
    "last_modified" : "2015-11-18.75:15:24.827Z",
    "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category1/other",
    "position" : 2.0,
    "source_catalog_id" : "MyCatalog",
    "source_catalog_name": { "default": "My Catalog" },
    "source_category_id" : "MyCategory1",
    "source_category_name": { "default": "My Awesome Category" },
    "target_catalog_id" : "OtherCatalog",
    "target_catalog_name": { "default": "That Other Catalog" },
    "target_category_id" : "Category1",
    "target_category_name": { "default": "Category 1" },
    "type" : "other"
}

# 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":"CatalogNotFoundException",
    "message":"No catalog with ID 'WapiCatalog' was found."
  }
}

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 'MyCategory1' for catalog 'MyCatalog' 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",
    "_type":"fault",
    "fault":{
        "type":"CategoryLinkNotFoundException",
        "message":"No category link found from 'MyCatalog 'MyCategory1' to 'OtherCatalog' 'Category1' with type 'other' was found."
    }
}

Update Category Link

Updates the category link with the specified information.

Url

PATCH https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CategoryLink

Response Document

CategoryLink

Path Parameters

Parameter Type Description Constraints
catalog_id String The id of the source catalog. minLength=1
category_id String The id of the source category. minLength=1
target_catalog_id String The id of the target catalog. minLength=1
target_category_id String The id of the target category. minLength=1
type Enum {other, accessories, cross_selling, up_selling, spare_parts} the link type  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CatalogNotFoundException

catalogId (String)

 Thrown in case the source catalog or the target catalog do not exist
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Thrown in case the source category or the target category do not exist
404 CategoryLinkNotFoundException

sourceCatalogId (String)

sourceCategoryId (String)

targetCatalogId (String)

targetCategoryId (String)

linkType (Enum {other, accessories, cross_selling, up_selling, spare_parts})

 Thrown in case the category link does not exist from the source catalog/category to the destination catalog/category with the given type.

Sample

REQUEST:
PATCH  /s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category1/other HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

{
   "position" : 5,
}
# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
    "_v" : "23.2",
    "_type" : "category_link",
    "last_modified" : "2015-11-18.75:15:24.827Z",
    "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category1/other",
    "position" : 5.0,
    "source_catalog_id" : "MyCatalog",
    "source_catalog_name": { "default": "My Catalog" },
    "source_category_id" : "MyCategory1",
    "source_category_name": { "default": "My Awesome Category" },
    "target_catalog_id" : "OtherCatalog",
    "target_catalog_name": { "default": "That Other Catalog" },
    "target_category_id" : "Category1",
    "target_category_name": { "default": "Category 1" },
    "type" : "other"
}

# 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":"CatalogNotFoundException",
    "message":"No catalog with ID 'WapiCatalog' was found."
  }
}

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 'MyCategory1' for catalog 'MyCatalog' 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",
    "_type":"fault",
    "fault":{
        "type":"CategoryLinkNotFoundException",
        "message":"No category link found from 'MyCatalog 'MyCategory1' to 'OtherCatalog' 'Category1' with type 'other' was found."
    }
}

Delete Category Link

Deletes the category link by ID

Url

DELETE https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
catalog_id String The id of the source catalog. minLength=1
category_id String The id of the source category. minLength=1
target_catalog_id String The id of the target catalog. minLength=1
target_category_id String The id of the target category. minLength=1
type Enum {other, accessories, cross_selling, up_selling, spare_parts} the link type  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CatalogNotFoundException

catalogId (String)

 Thrown in case the source catalog or the target catalog do not exist
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Thrown in case the source category or the target category do not exist
404 CategoryLinkNotFoundException

sourceCatalogId (String)

sourceCategoryId (String)

targetCatalogId (String)

targetCategoryId (String)

linkType (Enum {other, accessories, cross_selling, up_selling, spare_parts})

 Thrown in case the category link does not exist from the source catalog/category to the destination catalog/category with the given type.

Sample

REQUEST:
DELETE  /s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category1/other HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

# 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":"CatalogNotFoundException",
    "message":"No catalog with ID 'WapiCatalog' was found."
  }
}

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 '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",
    "_type":"fault",
    "fault":{
        "type":"CategoryLinkNotFoundException",
        "message":"No category link found from 'MyCatalog 'MyCategory1' to 'OtherCatalog' 'Category1' with type 'other' was found."
    }
}

Create Category Link

Creates a category link using the information provided. If a category link with the same unique identifier, it will be updated with the new position.

Url

PUT https://hostname:port/dw/data/v23_2/catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

CategoryLink

Response Document

CategoryLink

Path Parameters

Parameter Type Description Constraints
catalog_id String The id of the source catalog. minLength=1
category_id String The id of the source category. minLength=1
target_catalog_id String The id of the target catalog. minLength=1
target_category_id String The id of the target category. minLength=1
type Enum {other, accessories, cross_selling, up_selling, spare_parts} the link type  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CatalogNotFoundException

catalogId (String)

 Thrown in case the source catalog or the target catalog do not exist
404 CategoryNotFoundException

catalogId (String)

categoryId (String)

 Thrown in case the source category or the target category do not exist

Sample

REQUEST:
PUT /s/-/data/v23_2/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category1/other HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
    "_v" : "23.2",
    "_type" : "category_link",
    "last_modified" : "2015-11-18.75:15:24.827Z",
    "position" : 1.0,
    "source_catalog_id" : "MyCatalog",
    "source_catalog_name": { "default": "My Catalog" },
    "source_category_id" : "MyCategory1",
    "source_category_name": { "default": "My Awesome Category" },
    "target_catalog_id" : "OtherCatalog",
    "target_catalog_name": { "default": "That Other Catalog" },
    "target_category_id" : "Category1",
    "target_category_name": { "default": "Category 1" },
    "type" : "other"
}

# in case of success:

RESPONSE:
HTTP/1.1 201 CREATED
Content-Length: 67
Content-Type: application/json; charset=UTF-8
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
    "_v" : "23.2",
    "_type" : "category_link",
    "last_modified" : "2015-11-18.75:15:24.827Z",
    "link" : "https://example.com/s/-/dw/data/v23_2/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category1/other",
    "position" : 1.0,
    "source_catalog_id" : "MyCatalog",
    "source_catalog_name": { "default": "My Catalog" },
    "source_category_id" : "MyCategory1",
    "source_category_name": { "default": "My Awesome Category" },
    "target_catalog_id" : "OtherCatalog",
    "target_catalog_name": { "default": "That Other Catalog" },
    "target_category_id" : "Category1",
    "target_category_name": { "default": "Category 1" },
    "type" : "other"
}

# 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":"CatalogNotFoundException",
    "message":"No catalog with ID 'WapiCatalog' was found."
  }
}

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 'MyCategory1' for catalog 'MyCatalog' 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.