Create a hierarchy

POST 
/pcm/hierarchies

Creates a hierarchy with a name, description, and slug to organize products in your catalog.

Custom Attributes

Custom attributes allow you to extend the data model with your own key-value data.

You can define up to 100 custom attributes in each group (shopper_attributes and admin_attributes). Both keys and values must be strings.

• shopper_attributes are visible in shopper-facing catalogs and accessible to both shoppers and administrators. Ideal for customer-facing data, such as promotional labels or product tags.
• admin_attributes are private and not visible in catalogs. Best suited for internal operational data, such as cost tracking or workflow metadata.

See Custom Attributes.

Request

application/json

Body

required

data objectrequired

type stringrequired

Possible values: [hierarchy]

This represents the type of resource object being returned. Always hierarchy.

attributes objectrequired

name string

The name of the hierarchy, such as Major Appliances.

description string

A description of the hierarchy.

slug string

A unique slug for the hierarchy.

admin_attributes object

admin_attributes are not displayed in catalogs. This means admin_attributes can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to shopper_attributes.

admin_attributes are structured as key-value pairs. Both the keys and values are strings. You can have up to 100 keys.

property name* stringnullable

shopper_attributes object

shopper_attributes are displayed in catalogs. This means shopper_attributes can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to admin_attributes.

shopper_attributes are structured as key-value pairs. Both the keys and values are strings. You can have up to 100 keys.

property name* stringnullable

locales object

Product Experience Manager supports localization of products and hierarchies. If your store supports multiple languages, you can localize product names and descriptions. You can have as many locales as you want.

property name* object

A three-letter language code that represents the name of language you have used.

name string

A localized name for the hierarchy.

description string

A localized description for the hierarchy.

Responses

201

Returns a created hierarchy with the following attributes.

application/json

Schema

Schema

data objectrequired

id stringrequired

A unique identifier generated when a hierarchy is created.

type stringrequired

Possible values: [hierarchy]

This represents the type of resource object being returned. Always hierarchy.

attributes objectrequired

name string

The name of a hierarchy, such as Major Appliances.

description string

A description for a hierarchy.

slug string

A unique slug for a hierarchy.

admin_attributes object

admin_attributes are not displayed in catalogs. This means admin_attributes can only be viewed by administrators. If you want a custom attribute to be displayed in a catalog, you must add it to shopper_attributes.

admin_attributes are structured as key-value pairs. Both the keys and values are strings. You can have up to 100 keys.

property name* stringnullable

shopper_attributes object

shopper_attributes are displayed in catalogs. This means shopper_attributes can be viewed by both shoppers and administrators. If you do not want a custom attribute to be displayed in a catalog, you must add it to admin_attributes.

shopper_attributes are structured as key-value pairs. Both the keys and values are strings. You can have up to 100 keys.

property name* stringnullable

locales object

Product Experience Manager supports localization of hierarchies and nodes. If you store supports multiple languages, you can localize hierarchy and node names and descriptions.

property name* object

A three-letter language code that represents the name of language you have used.

name string

A localized hierarchy or node name.

description string

A localized hierarchy or node description.

relationships objectrequired

children object

The child nodes related to the hierarchy.

data array

An array of child nodes.

links object

Links allow you to move between requests.

related string

A link to a related resource.

meta objectrequired

created_at date-time

The date and time a hierarchy is created.

updated_at date-time

The date and time a hierarchy is updated.

owner string

Possible values: [store, organization]

The owner of a resource, either organization or store.

Example (from schema)

{
  "data": {
    "id": "string",
    "type": "hierarchy",
    "attributes": {
      "name": "string",
      "description": "string",
      "slug": "string",
      "admin_attributes": {
        "cost_of_goods": "42.0",
        "charge_type": "credit card"
      },
      "shopper_attributes": {
        "cost_of_goods": "42.0",
        "charge_type": "credit card"
      },
      "locales": {}
    },
    "relationships": {
      "children": {
        "data": [
          null
        ],
        "links": {
          "related": "string"
        }
      }
    },
    "meta": {
      "created_at": "2020-09-22T09:00:00",
      "updated_at": "2020-09-22T09:00:00",
      "owner": "store"
    }
  }
}

created-hierarchy

{
  "data": {
    "type": "hierarchy",
    "id": "6183d10c-94b5-4caa-9f12-2f14cb738d41",
    "attributes": {
      "description": "Shoes Category",
      "locales": {
        "fr-FR": {
          "name": "Chaussures",
          "description": "Catégorie de chaussures"
        }
      },
      "admin_attributes": {
        "cost_of_goods": "42.0",
        "charge_type": "credit card"
      },
      "shopper_attributes": {
        "cost_of_goods": "42.0",
        "charge_type": "credit card"
      },
      "name": "Shoes",
      "slug": "shoes"
    },
    "relationships": {
      "children": {
        "data": [],
        "links": {
          "related": "/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/children"
        }
      }
    },
    "meta": {
      "created_at": "2024-01-10T20:16:35.343Z",
      "owner": "store",
      "updated_at": "2024-01-10T20:16:35.343Z"
    }
  }
}

422

Bad request. The request failed validation.

application/json

Schema

Schema

errors undefined[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
request_id string
Internal request ID.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": "500",
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "request_id": "00000000-0000-0000-0000-000000000000",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

failed-validation

{
  "errors": [
    {
      "title": "Failed Validation",
      "status": "422",
      "detail": "<XYZ> can not be empty"
    }
  ]
}

500

Internal server error. There was a system failure in the platform.

application/json

Schema

Schema

errors undefined[]required
Array [
status stringrequired
The HTTP response code of the error.
title stringrequired
A brief summary of the error.
detail string
Optional additional detail about the error.
request_id string
Internal request ID.
meta object
Additional supporting meta data for the error.
]

Example (from schema)

{
  "errors": [
    {
      "status": "500",
      "title": "Internal server error",
      "detail": "An internal error has occurred.",
      "request_id": "00000000-0000-0000-0000-000000000000",
      "meta": {
        "missing_ids": [
          "e7d50bd5-1833-43c0-9848-f9d325b08be8"
        ]
      }
    }
  ]
}

internal-server-error

{
  "errors": [
    {
      "status": "500",
      "title": "Internal Server Error",
      "detail": "There was an internal server error, you can report with your request id.",
      "request_id": "635da56d-75a1-43cd-b696-7ab119756b3a"
    }
  ]
}

Loading...