Category endpoint

This page describes the category endpoint, which can be used to interact with your external e-commerce solution’s REST service.

Magento is now Adobe Commerce, powered by Magento. In the examples and configuration below, we may refer to Adobe Commerce as Magento.
The category key was exposed for the commercetools connection in version 1.3.2.

GET

Get all categories

Returns a list of all categories for a given connection.

Request URL

/.rest/ecommerce/v1/categories/list

Parameters

Parameter Description Type Data Type

definitionName

required

The definition name.

query

string

connectionName

required

The connection name.

query

string

Magento example

Gets a list of all the categories.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/list?definitionName=magento&connectionName=connection"

JSON response

[
    {
        "id": {
            "definitionName": "magento",
            "connectionName": "connection",
            "itemId": "1"
        },
        "name": "Root Catalog",
        "position": 0,
        "level": 0,
        "description": "",
        "parentId": null,
        "path": "1",
        "is_active": null,
        "created_at": "2018-08-07 12:46:57",
        "updated_at": "2019-03-22 12:48:42",
        "available_sort_by": [],
        "include_in_menu": "true",
        "extension_attributes": null,
        "custom_attributes": [
            {
                "value": [
                    "1"
                ],
                "attribute_code": "path"
            },
            {
                "value": [
                    "39"
                ],
                "attribute_code": "children_count"
            }
        ],
        "product_count": null
    },
    {
        "id": {
            "definitionName": "magento",
            "connectionName": "connection",
            "itemId": "2"
        },
        "name": "Default Category",
        "position": 1,
        "level": 1,
        "description": "",
        "parentId": "1",
        "path": "1/2",
        "is_active": "true",
        "created_at": "2018-08-07 12:46:57",
        "updated_at": "2019-03-22 12:48:42",
        "available_sort_by": [],
        "include_in_menu": "true",
        "extension_attributes": null,
        "custom_attributes": [
            {
                "value": [
                    "PRODUCTS"
                ],
                "attribute_code": "display_mode"
            },
            {
                "value": [
                    "1/2"
                ],
                "attribute_code": "path"
            },
            {
                "value": [
                    "38"
                ],
                "attribute_code": "children_count"
            }
        ],
        "product_count": null
    },
    {
        "id": {
            "definitionName": "magento",
            "connectionName": "connection",
            "itemId": "3"
        },
        "name": "Gear",
        "position": 4,
        "level": 2,
        "description": "",
        "parentId": "2",
        "path": "1/2/3",
        "is_active": "true",
        "created_at": "2018-08-07 12:47:02",
        "updated_at": "2019-03-22 12:48:42",
        "available_sort_by": [],
        "include_in_menu": "true",
        "extension_attributes": null,
        "custom_attributes": [
            {
                "value": [
                    "PAGE"
                ],
                "attribute_code": "display_mode"
            },
            {
                "value": [
                    "0"
                ],
                "attribute_code": "is_anchor"
            },
            {
                "value": [
                    "1/2/3"
                ],
                "attribute_code": "path"
            },
            {
                "value": [
                    "<referenceContainer name=\"catalog.leftnav\" remove=\"true\"/>"
                ],
                "attribute_code": "custom_layout_update"
            },
            {
                "value": [
                    "3"
                ],
                "attribute_code": "children_count"
            },
            {
                "value": [
                    "gear"
                ],
                "attribute_code": "url_key"
            },
            {
                "value": [
                    "gear"
                ],
                "attribute_code": "url_path"
            }
        ],
        "product_count": null
    },
    ...

commercetools example

Gets a list of all the categories.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/list?definitionName=commercetools&connectionName=connection"

JSON response

[
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "5c804c8d-d628-41fe-84ca-6f5a1fb161a9"
        },
        "name": "Pijamas",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "c13a3224-aef7-4a61-b0bb-72f342f5577c",
        "path": "Pijamas",
        "key": "PIJAMAS"
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "05005125-3b5b-40df-bd8f-18cf6e2aa0d4"
        },
        "name": "New",
        "description": null,
        "position": null,
        "level": null,
        "parentId": null,
        "path": "New",
        "key": "new1"
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "7ad6b953-b7b4-4194-829e-8c90dc79a90f"
        },
        "name": "Women",
        "description": null,
        "position": null,
        "level": null,
        "parentId": null,
        "path": "Women",
        "key": "women2"
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "c13a3224-aef7-4a61-b0bb-72f342f5577c"
        },
        "name": "Men",
        "description": null,
        "position": null,
        "level": null,
        "parentId": null,
        "path": "Men",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "653b26f7-092a-463f-b9f3-1a75986a3e83"
        },
        "name": "Accessories",
        "description": null,
        "position": null,
        "level": null,
        "parentId": null,
        "path": "Accessories",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "1e616640-0411-435d-92c0-3ee7a04ac60a"
        },
        "name": "Sale",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "0491d1f9-0afa-4e89-84d3-e4a042df5c7b",
        "path": "Sale",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "18c16f24-876a-429d-b341-ba11fa797b52"
        },
        "name": "Women",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "05005125-3b5b-40df-bd8f-18cf6e2aa0d4",
        "path": "Women",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "c7043d3d-e966-456a-b998-20e32a57c330"
        },
        "name": "Men",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "05005125-3b5b-40df-bd8f-18cf6e2aa0d4",
        "path": "Men",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "589d0273-8e3f-4d1f-b8eb-a9105c6a8689"
        },
        "name": "Special",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "05005125-3b5b-40df-bd8f-18cf6e2aa0d4",
        "path": "Special",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "64431455-bca5-4f29-8425-9781b440d0fc"
        },
        "name": "Clothing",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "7ad6b953-b7b4-4194-829e-8c90dc79a90f",
        "path": "Clothing",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "bac84eff-714a-4d14-b24f-26e7e8f7f6a3"
        },
        "name": "Shoes",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "7ad6b953-b7b4-4194-829e-8c90dc79a90f",
        "path": "Shoes",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "f70cd477-ba44-4fa0-8998-9c44548ce15f"
        },
        "name": "Bags",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "7ad6b953-b7b4-4194-829e-8c90dc79a90f",
        "path": "Bags",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "a94eb98f-5b02-4b4a-adb2-6e3e0c68e4e8"
        },
        "name": "Looks",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "7ad6b953-b7b4-4194-829e-8c90dc79a90f",
        "path": "Looks",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "5cb33df5-047e-47f4-8515-d4cd5881ffa5"
        },
        "name": "Clothing",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "c13a3224-aef7-4a61-b0bb-72f342f5577c",
        "path": "Clothing",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "20a36a61-96f3-466d-945a-55d20114c049"
        },
        "name": "Shoes",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "c13a3224-aef7-4a61-b0bb-72f342f5577c",
        "path": "Shoes",
        "key": null
    },
    ...

Salesforce Commerce example

Gets a list of all the categories.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/list?definitionName=salesforce-commerce&connectionName=connection-RefArch"

JSON response

[
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics"
      },
      "description":"",
      "name":"Electronics",
      "position":5,
      "level":null,
      "parentId":"electronics-m-catalog~root",
      "path":"Electronics",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-accessories"
      },
      "description":"",
      "name":"Accessories",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics",
      "path":"Accessories",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-camcorders"
      },
      "description":"",
      "name":"Camcorders",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics",
      "path":"Camcorders",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-digital-cameras"
      },
      "description":"",
      "name":"Digital Cameras",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics",
      "path":"Digital Cameras",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-digital-media-players"
      },
      "description":"",
      "name":"Electronics Digital Media Players",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics",
      "path":"Electronics Digital Media Players",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-game-consoles"
      },
      "description":"",
      "name":"Game Consoles",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics-gaming",
      "path":"Game Consoles",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-games"
      },
      "description":"",
      "name":"Games",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics-gaming",
      "path":"Games",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-gaming"
      },
      "description":"",
      "name":"Electronics Gaming",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics",
      "path":"Electronics Gaming",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-gps-units"
      },
      "description":"",
      "name":"GPS Units",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics",
      "path":"GPS Units",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-mobile-phones"
      },
      "description":"",
      "name":"Mobile Phones",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics",
      "path":"Mobile Phones",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-televisions"
      },
      "description":"",
      "name":"TVs",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics",
      "path":"TVs",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-televisions-flat-screen"
      },
      "description":"",
      "name":"Flat Screen",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics-televisions",
      "path":"Flat Screen",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-televisions-projection"
      },
      "description":"",
      "name":"Projection",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics-televisions",
      "path":"Projection",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~electronics-televisions-tv-dvd-combo"
      },
      "description":"",
      "name":"TV/DVD Combo",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog~electronics-televisions",
      "path":"TV/DVD Combo",
      "assignedSites":[

      ]
   },
   {
      "id":{
         "definitionName":"salesforce-commerce",
         "connectionName":"connection-RefArch",
         "itemId":"electronics-m-catalog~root"
      },
      "description":"",
      "name":"Electronics Master Catalog",
      "position":null,
      "level":null,
      "parentId":"electronics-m-catalog",
      "path":"Electronics Master Catalog",
      "assignedSites":[

      ]
   }
]

SAP example

Gets a list of all the categories.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/list?definitionName=sap-commerce&connectionName=electronics"

JSON response

[
    {
        "id": {
            "definitionName": "sap-commerce",
            "connectionName": "electronics",
            "itemId": "electronicsProductCatalog"
        },
        "name": "Electronics Product Catalog",
        "description": null,
        "position": null,
        "level": null,
        "parentId": null,
        "path": null
    },
    {
        "id": {
            "definitionName": "sap-commerce",
            "connectionName": "electronics",
            "itemId": "electronicsProductCatalog/Staged"
        },
        "name": "Staged",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "electronicsProductCatalog",
        "path": null
    },
    {
        "id": {
            "definitionName": "sap-commerce",
            "connectionName": "electronics",
            "itemId": "electronicsProductCatalog/Online"
        },
        "name": "Online",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "electronicsProductCatalog",
        "path": null
    },
    {
        "id": {
            "definitionName": "sap-commerce",
            "connectionName": "electronics",
            "itemId": "electronicsProductCatalog/Online/B2C_Color"
        },
        "name": "Color",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "electronicsProductCatalog/Online",
        "path": null
    },
    ...
]

Get category by ID

Returns a category based on its ID.

Request URL

/.rest/ecommerce/v1/categories/{categoryId}

Parameters

Parameter Description Type Data Type

definitionName

required

The definition name.

query

string

connectionName

required

The connection name.

query

string

categoryId

required

The ID of the category.

path

string

Magento example

Gets the category with an ID of 2.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/2?definitionName=magento&connectionName=connection"

JSON response

{
    "id": {
        "definitionName": "magento",
        "connectionName": "connection",
        "itemId": "2"
    },
    "name": "Default Category",
    "position": 1,
    "level": 1,
    "description": "",
    "parentId": "1",
    "path": "1/2",
    "is_active": "true",
    "created_at": "2018-08-07 12:46:57",
    "updated_at": "2019-03-22 12:48:42",
    "available_sort_by": [],
    "include_in_menu": "true",
    "extension_attributes": null,
    "custom_attributes": [
        {
            "value": [
                "PRODUCTS"
            ],
            "attribute_code": "display_mode"
        },
        {
            "value": [
                "1/2"
            ],
            "attribute_code": "path"
        },
        {
            "value": [
                "38"
            ],
            "attribute_code": "children_count"
        }
    ],
    "product_count": null
}

commercetools example

Gets the category with an ID of 5c804c8d-d628-41fe-84ca-6f5a1fb161a9.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/5c804c8d-d628-41fe-84ca-6f5a1fb161a9?definitionName=commercetools&connectionName=connection"

JSON response

{
    "id": {
        "definitionName": "commercetools",
        "connectionName": "connection",
        "itemId": "5c804c8d-d628-41fe-84ca-6f5a1fb161a9"
    },
    "name": "Pijamas",
    "description": null,
    "position": null,
    "level": null,
    "parentId": "c13a3224-aef7-4a61-b0bb-72f342f5577c",
    "path": "Pijamas",
    "key": "PIJAMAS"
}

Salesforce Commerce example

Gets the category with an ID of electronics-m-catalog~electronics.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/electronics-m-catalog~electronics?definitionName=salesforce-commerce&connectionName=connection-RefArch"

JSON response

{
    {
    "id": {
        "definitionName": "salesforce-commerce",
        "connectionName": "connection-RefArch",
        "itemId": "electronics-m-catalog~electronics"
    },
    "description": "",
    "name": "Electronics",
    "position": 5,
    "level": null,
    "parentId": "electronics-m-catalog~root",
    "path": "Electronics",
    "assignedSites": []
    }
}

SAP example

Gets the category with an ID of electronicsProductCatalog.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/electronicsProductCatalog?definitionName=sap-commerce&connectionName=electronics"

JSON response

{
    "id": {
        "definitionName": "sap-commerce",
        "connectionName": "electronics",
        "itemId": "electronicsProductCatalog"
    },
    "name": "Electronics Product Catalog",
    "description": null,
    "position": null,
    "level": null,
    "parentId": null,
    "path": null
}

Get category by product ID

Returns a category based on the ID of a product.

Request URL

/.rest/ecommerce/v1/categories/product/{productId}

Parameters

Parameter Description Type Data Type

definitionName

required

The definition name.

query

string

connectionName

required

The connection name.

query

string

productId

required

The unique ID of the product.

Magento: SKU of the product.

path

string

Magento example

Gets the category corresponding to the product with an ID (SKU) of 24-MB01.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/product/24-MB01?definitionName=magento&connectionName=connection"

JSON response

[
    {
        "id": {
            "definitionName": "magento",
            "connectionName": "connection",
            "itemId": "3"
        },
        "name": "Gear",
        "position": 4,
        "level": 2,
        "description": "",
        "parentId": "2",
        "path": "1/2/3",
        "is_active": "true",
        "created_at": "2018-08-07 12:47:02",
        "updated_at": "2019-03-22 12:48:42",
        "available_sort_by": [],
        "include_in_menu": "true",
        "extension_attributes": null,
        "custom_attributes": [
            {
                "value": [
                    "PAGE"
                ],
                "attribute_code": "display_mode"
            },
            {
                "value": [
                    "0"
                ],
                "attribute_code": "is_anchor"
            },
            {
                "value": [
                    "1/2/3"
                ],
                "attribute_code": "path"
            },
            {
                "value": [
                    "<referenceContainer name=\"catalog.leftnav\" remove=\"true\"/>"
                ],
                "attribute_code": "custom_layout_update"
            },
            {
                "value": [
                    "3"
                ],
                "attribute_code": "children_count"
            },
            {
                "value": [
                    "gear"
                ],
                "attribute_code": "url_key"
            },
            {
                "value": [
                    "gear"
                ],
                "attribute_code": "url_path"
            }
        ],
        "product_count": null
    },
    {
        "id": {
            "definitionName": "magento",
            "connectionName": "connection",
            "itemId": "4"
        },
        "name": "Bags",
        "position": 1,
        "level": 3,
        "description": "",
        "parentId": "3",
        "path": "1/2/3/4",
        "is_active": "true",
        "created_at": "2018-08-07 12:47:02",
        "updated_at": "2018-08-07 12:47:02",
        "available_sort_by": [],
        "include_in_menu": "true",
        "extension_attributes": null,
        "custom_attributes": [
            {
                "value": [
                    "1"
                ],
                "attribute_code": "is_anchor"
            },
            {
                "value": [
                    "1/2/3/4"
                ],
                "attribute_code": "path"
            },
            {
                "value": [
                    "0"
                ],
                "attribute_code": "children_count"
            },
            {
                "value": [
                    "bags"
                ],
                "attribute_code": "url_key"
            },
            {
                "value": [
                    "gear/bags"
                ],
                "attribute_code": "url_path"
            }
        ],
        "product_count": null
    }
]

commercetools example

Gets the category corresponding to the product with an ID of cb292097-a8cf-4b51-8258-879d3e85036a.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/product/cb292097-a8cf-4b51-8258-879d3e85036a?definitionName=commercetools&connectionName=connection"

JSON response

[
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "05005125-3b5b-40df-bd8f-18cf6e2aa0d4"
        },
        "name": "New",
        "description": null,
        "position": null,
        "level": null,
        "parentId": null,
        "path": "New",
        "key": "new1"
    }
]

Salesforce Commerce example

Gets the category corresponding to the product with an ID of electronics-m-catalog~canon-eos-50d-bodyM.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/product/electronics-m-catalog~canon-eos-50d-bodyM?definitionName=salesforce-commerce&connectionName=connection-RefArch"

JSON response

[
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "storefront-catalog-m-en~newarrivals-electronics"
        },
        "description": "",
        "name": "Electronics",
        "position": 5,
        "level": null,
        "parentId": "storefront-catalog-m-en~newarrivals",
        "path": "Electronics",
        "assignedSites": []
    },
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "electronics-m-catalog~electronics-digital-cameras"
        },
        "description": "",
        "name": "Digital Cameras",
        "position": null,
        "level": null,
        "parentId": "electronics-m-catalog~electronics",
        "path": "Digital Cameras",
        "assignedSites": []
    },
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "storefront-catalog-m-en~electronics-digital-cameras"
        },
        "description": "",
        "name": "Digital Cameras",
        "position": 7,
        "level": null,
        "parentId": "storefront-catalog-m-en~electronics",
        "path": "Digital Cameras",
        "assignedSites": []
    },
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "storefront-catalog-m-en~sale-electronics-digital"
        },
        "description": "",
        "name": "Digital Cameras",
        "position": 4,
        "level": null,
        "parentId": "storefront-catalog-m-en~sale-electronics",
        "path": "Digital Cameras",
        "assignedSites": []
    }
]

SAP example

Gets the category corresponding to the product with an ID of 553637.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/product/553637?definitionName=sap-commerce&connectionName=electronics"

JSON response

[
    {
        "id": {
            "definitionName": "sap-commerce",
            "connectionName": "electronics",
            "itemId": "electronicsProductCatalog/Online/brand_26"
        },
        "name": "Samsung",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "electronicsProductCatalog/Online/brands",
        "path": null
    },
    {
        "id": {
            "definitionName": "sap-commerce",
            "connectionName": "electronics",
            "itemId": "electronicsProductCatalog/Online/576"
        },
        "name": "Digital Compacts",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "electronicsProductCatalog/Online/575",
        "path": null
    }
]

Get category by parent ID

Returns a category based on the ID of the parent category.

Request URL

/.rest/ecommerce/v1/categories/?parentId

Parameters

Parameter Description Type Data Type

definitionName

required

The definition name.

query

string

connectionName

required

The connection name.

query

string

parentId

required

The ID of the parent category.

Default is 3 for Magento.

path

string

Magento example

Gets the child category of the parent category with an ID of 3.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/?parentId=3&definitionName=magento&connectionName=connection"

JSON response

[
    {
        "id": {
            "definitionName": "magento",
            "connectionName": "connection",
            "itemId": "4"
        },
        "name": "Bags",
        "position": 1,
        "level": 3,
        "description": "",
        "parentId": "3",
        "path": "1/2/3/4",
        "is_active": "true",
        "created_at": "2018-08-07 12:47:02",
        "updated_at": "2018-08-07 12:47:02",
        "available_sort_by": [],
        "include_in_menu": "true",
        "extension_attributes": null,
        "custom_attributes": [
            {
                "value": [
                    "1"
                ],
                "attribute_code": "is_anchor"
            },
            {
                "value": [
                    "1/2/3/4"
                ],
                "attribute_code": "path"
            },
            {
                "value": [
                    "0"
                ],
                "attribute_code": "children_count"
            },
            {
                "value": [
                    "bags"
                ],
                "attribute_code": "url_key"
            },
            {
                "value": [
                    "gear/bags"
                ],
                "attribute_code": "url_path"
            }
        ],
        "product_count": null
    },
    {
        "id": {
            "definitionName": "magento",
            "connectionName": "connection",
            "itemId": "5"
        },
        "name": "Fitness Equipment",
        "position": 2,
        "level": 3,
        "description": "",
        "parentId": "3",
        "path": "1/2/3/5",
        "is_active": "true",
        "created_at": "2018-08-07 12:47:02",
        "updated_at": "2018-08-07 12:47:02",
        "available_sort_by": [],
        "include_in_menu": "true",
        "extension_attributes": null,
        "custom_attributes": [
            {
                "value": [
                    "1"
                ],
                "attribute_code": "is_anchor"
            },
            {
                "value": [
                    "1/2/3/5"
                ],
                "attribute_code": "path"
            },
            {
                "value": [
                    "0"
                ],
                "attribute_code": "children_count"
            },
            {
                "value": [
                    "fitness-equipment"
                ],
                "attribute_code": "url_key"
            },
            {
                "value": [
                    "gear/fitness-equipment"
                ],
                "attribute_code": "url_path"
            }
        ],
        "product_count": null
    },
    {
        "id": {
            "definitionName": "magento",
            "connectionName": "connection",
            "itemId": "6"
        },
        "name": "Watches",
        "position": 3,
        "level": 3,
        "description": "",
        "parentId": "3",
        "path": "1/2/3/6",
        "is_active": "true",
        "created_at": "2018-08-07 12:47:02",
        "updated_at": "2018-08-07 12:47:02",
        "available_sort_by": [],
        "include_in_menu": "true",
        "extension_attributes": null,
        "custom_attributes": [
            {
                "value": [
                    "1"
                ],
                "attribute_code": "is_anchor"
            },
            {
                "value": [
                    "1/2/3/6"
                ],
                "attribute_code": "path"
            },
            {
                "value": [
                    "0"
                ],
                "attribute_code": "children_count"
            },
            {
                "value": [
                    "watches"
                ],
                "attribute_code": "url_key"
            },
            {
                "value": [
                    "gear/watches"
                ],
                "attribute_code": "url_path"
            }
        ],
        "product_count": null
    }
]

commercetools example

Gets the child category of the parent category with an ID of c13a3224-aef7-4a61-b0bb-72f342f5577c.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/?parentId=c13a3224-aef7-4a61-b0bb-72f342f5577c&definitionName=commercetools&connectionName=connection"

JSON response

[
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "5c804c8d-d628-41fe-84ca-6f5a1fb161a9"
        },
        "name": "Pijamas",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "c13a3224-aef7-4a61-b0bb-72f342f5577c",
        "path": "Pijamas",
        "key": "PIJAMAS"
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "5cb33df5-047e-47f4-8515-d4cd5881ffa5"
        },
        "name": "Clothing",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "c13a3224-aef7-4a61-b0bb-72f342f5577c",
        "path": "Clothing",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "20a36a61-96f3-466d-945a-55d20114c049"
        },
        "name": "Shoes",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "c13a3224-aef7-4a61-b0bb-72f342f5577c",
        "path": "Shoes",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "9f7b17db-403b-491a-a12b-99e15d87f0b8"
        },
        "name": "Bags",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "c13a3224-aef7-4a61-b0bb-72f342f5577c",
        "path": "Bags",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "f431bb88-d737-4c77-9cd0-06b11c4af8c4"
        },
        "name": "Looks",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "c13a3224-aef7-4a61-b0bb-72f342f5577c",
        "path": "Looks",
        "key": null
    },
    {
        "id": {
            "definitionName": "commercetools",
            "connectionName": "connection",
            "itemId": "3ac71226-3723-47b5-8dc1-5da875a5a01f"
        },
        "name": "Edwin",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "c13a3224-aef7-4a61-b0bb-72f342f5577c",
        "path": "Edwin",
        "key": null
    }
]

Salesforce Commerce example

Gets the child category of the parent category with an ID of electronics-m-catalog~electronics.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories/?parentId=electronics-m-catalog~electronics&definitionName=salesforce-commerce&connectionName=connection-RefArch"

JSON response

[
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "electronics-m-catalog~electronics-accessories"
        },
        "description": "",
        "name": "Accessories",
        "position": null,
        "level": null,
        "parentId": "electronics-m-catalog~electronics",
        "path": "Accessories",
        "assignedSites": []
    },
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "electronics-m-catalog~electronics-camcorders"
        },
        "description": "",
        "name": "Camcorders",
        "position": null,
        "level": null,
        "parentId": "electronics-m-catalog~electronics",
        "path": "Camcorders",
        "assignedSites": []
    },
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "electronics-m-catalog~electronics-digital-cameras"
        },
        "description": "",
        "name": "Digital Cameras",
        "position": null,
        "level": null,
        "parentId": "electronics-m-catalog~electronics",
        "path": "Digital Cameras",
        "assignedSites": []
    },
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "electronics-m-catalog~electronics-digital-media-players"
        },
        "description": "",
        "name": "Electronics Digital Media Players",
        "position": null,
        "level": null,
        "parentId": "electronics-m-catalog~electronics",
        "path": "Electronics Digital Media Players",
        "assignedSites": []
    },
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "electronics-m-catalog~electronics-gaming"
        },
        "description": "",
        "name": "Electronics Gaming",
        "position": null,
        "level": null,
        "parentId": "electronics-m-catalog~electronics",
        "path": "Electronics Gaming",
        "assignedSites": []
    },
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "electronics-m-catalog~electronics-gps-units"
        },
        "description": "",
        "name": "GPS Units",
        "position": null,
        "level": null,
        "parentId": "electronics-m-catalog~electronics",
        "path": "GPS Units",
        "assignedSites": []
    },
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "electronics-m-catalog~electronics-mobile-phones"
        },
        "description": "",
        "name": "Mobile Phones",
        "position": null,
        "level": null,
        "parentId": "electronics-m-catalog~electronics",
        "path": "Mobile Phones",
        "assignedSites": []
    },
    {
        "id": {
            "definitionName": "salesforce-commerce",
            "connectionName": "connection-RefArch",
            "itemId": "electronics-m-catalog~electronics-televisions"
        },
        "description": "",
        "name": "TVs",
        "position": null,
        "level": null,
        "parentId": "electronics-m-catalog~electronics",
        "path": "TVs",
        "assignedSites": []
    }
]

SAP example

Gets the child category of the parent category with an ID of electronicsProductCatalog/Online/1.

curl --user 'superuser:superuser' --request GET "http://localhost:8080/magnoliaAuthor/.rest/ecommerce/v1/categories?definitionName=sap-commerce&connectionName=electronics&parentId=electronicsProductCatalog/Online/1"

JSON response

[
    {
        "id": {
            "definitionName": "sap-commerce",
            "connectionName": "electronics",
            "itemId": "electronicsProductCatalog/Online/106"
        },
        "name": "Components",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "electronicsProductCatalog/Online/1",
        "path": null
    },
    {
        "id": {
            "definitionName": "sap-commerce",
            "connectionName": "electronics",
            "itemId": "electronicsProductCatalog/Online/206"
        },
        "name": "Data storage",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "electronicsProductCatalog/Online/1",
        "path": null
    },
    {
        "id": {
            "definitionName": "sap-commerce",
            "connectionName": "electronics",
            "itemId": "electronicsProductCatalog/Online/571"
        },
        "name": "Cameras",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "electronicsProductCatalog/Online/1",
        "path": null
    },
    {
        "id": {
            "definitionName": "sap-commerce",
            "connectionName": "electronics",
            "itemId": "electronicsProductCatalog/Online/1421"
        },
        "name": "Binoculars",
        "description": null,
        "position": null,
        "level": null,
        "parentId": "electronicsProductCatalog/Online/1",
        "path": null
    }
]
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Ecommerce module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules