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
6.3 beta
X

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.