Create a node

POST 
https://euwest.api.elasticpath.com/pcm/hierarchies/:hierarchyID/nodes

Creates a node in the specified hierarchy.

Sorting Nodes in a Hierarchy

You can sort the order of your nodes, regardless of where the nodes are in the hierarchy.

You can do this by adding a meta object to the body of your request and specifying a sort_order value.

The node with the highest value of sort_order is displayed first. For example, a node with a sort_order value of 3 appears before a node with a sort_order value of 2.

• If you don’t provide sort_order when creating nodes, all child nodes in the response for Get a Node’s Children request are ordered by the updated_at time in descending order, with the most recently updated child node first.
• If you set sort_order for only a few child nodes, the child nodes with a sort_order value appear first and then other child nodes appear in the order of updated_at time.

You can also specify a sort_order when creating a node relationship.

• If you create a node (Node A) with a sort_order and then you create a relationship for Node A with another node (Node B), the sort_order you specified when creating Node A is overwritten.
• If you create Node A and then you create a relationship with Node B but do not configure a sort_order, the sort_order you specified when you created Node A is not overwritten.

Curating Products in a node

You can curate the products in a node. Product curation allows you to promote specific products within each node of your hierarchies, enabling you to create unique product collections in your storefront. For example, you may find you have an abundance of cotton T-Shirts and you want to promote these products to the top of the product list. When a shopper navigates to T-shirts, the cotton T-Shirts are displayed first.

You can do this by adding a curated_products attribute to the body of your request and adding an array of product IDs to the attribute. You should add the products IDs in the order you want them to be displayed in your node. The first product ID is displayed first in the product list.

You can only curate 20 products or less. You cannot have more than 20 curated products.

• The product IDs you provide must exist in the specified node.

• If a curated product is removed from a node, the product is also removed from the curated_products list.

• Once you have curated the products in a node, you can use the get node products endpoint to retrieve a list of curated products.

  You can then display your curated products in your catalogs using the following catalog endpoints.

• Get a node in your latest catalog release.

• Get a node in a catalog.

• Get all nodes in your latest catalog release.

• Get all nodes in a catalog.

• Get node children in your latest catalog release.

• Get node children in a catalog.

Request

Path Parameters

hierarchyID uuidrequired

A unique identifier for the hierarchy.

application/json

Body

data object
type stringrequired
Possible values: [node]
This represents the type of resource object being returned. Always node.
attributes objectrequired
name string
The name of the node, such as Ranges or Refrigerators. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.
description string
A description of the node.
slug string
A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.
curated_products uuid[]
You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront. See Curating Products in a node.
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 node.
description string
A localized description for the node.
meta object
sort_order integer
You can sort the order of your nodes, regardless of where the nodes are in the hierarchy. The sort_order for each node. This value determines the order of nodes in the response for the Get a Node’s Children request. The node with the highest value of sort_order is displayed first. For example, a node with a sort_order value of 3 appears before a node with a sort_order value of 2.
• If you don’t provide sort_order when creating nodes, all child nodes in the response for Get a Node’s Children request are ordered by the updated_at time in descending order, with the most recently updated child node first.
• If you set sort_order for only a few child nodes or not all, the child nodes with a sort_order value appear first and then other child nodes appear in the order of updated_at time. See Sorting Nodes in a hierarchy.

Responses

201

Successfully returns the created node

application/json

Schema

Schema

data object

id uuid

The unique identifier of a node.

type string

Possible values: [node]

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

attributes object

name string

The name of the node, such as Ranges or Refrigerators. Names must be unique among sibling nodes in the hierarchy. Otherwise, a name can be non-unique within the hierarchy and across multiple hierarchies.

description string

A description for a node.

slug string

A slug for the node. Slugs must be unique among sibling nodes in the hierarchy. Otherwise, a slug can be non-unique within the hierarchy and across multiple hierarchies.

curated_products uuid[]

You can curate your products in your nodes product lists. Product curation allows you to promote specific products within each node in a hierarchy, enabling you to create unique product collections in your storefront.

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 object

Relationships allow you to move between requests. Includes links to the child nodes and products associated with a hierarchy or node.

children object

The child nodes related to the resource.

data array

An array of child nodes.

links object

Links allow you to move between requests.

related string

A link to a related resource.

parent object

The parent node related to the resource

data object

The parent node

type string

Possible values: [node]

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

id uuid

The unique identifier of a node.

products object

The products related to the resource.

data array

An array of products.

links object

Links allow you to move between requests.

related string

A link to a related resource.

meta object

sort_order integer

The sort order value. The node with the highest value of sort_order is displayed first. For example, a node with a sort_order value of 3 appears before a node with a sort_order value of 2. See Sorting Nodes in a hierarchy.

created_at date-time

The date and time a node is created.

updated_at date-time

The date and time a node was updated.

parent_name string

The name of the parent of the node if one exists.

owner string

Possible values: [store, organization]

The node owner, either organization or store.

Example (from schema)

{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "node",
    "attributes": {
      "name": "string",
      "description": "string",
      "slug": "string",
      "curated_products": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ],
      "locales": {}
    },
    "relationships": {
      "children": {
        "data": [
          null
        ],
        "links": {
          "related": "string"
        }
      },
      "parent": {
        "data": {
          "type": "node",
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }
      },
      "products": {
        "data": [
          null
        ],
        "links": {
          "related": "string"
        }
      }
    },
    "meta": {
      "sort_order": 0,
      "created_at": "2024-06-10T16:24:01.719Z",
      "updated_at": "2024-06-10T16:24:01.719Z",
      "parent_name": "string",
      "owner": "store"
    }
  }
}

created-node

{
  "data": {
    "type": "node",
    "id": "9ea0de15-3347-43dd-8faa-cd32f44a04c7",
    "attributes": {
      "description": "All Ballet Shoes",
      "locales": {
        "fr-FR": {
          "name": "Chaussons de ballet",
          "description": "Toutes les chaussures de ballet"
        }
      },
      "name": "Ballet Shoes",
      "slug": "ballet-shoes"
    },
    "relationships": {
      "children": {
        "data": [],
        "links": {
          "related": "/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/children"
        }
      },
      "parent": {
        "data": {
          "type": "node",
          "id": "14e8e15a-7214-435d-bccb-6ae9b570d683"
        }
      },
      "products": {
        "data": [],
        "links": {
          "related": "/hierarchies/6183d10c-94b5-4caa-9f12-2f14cb738d41/nodes/9ea0de15-3347-43dd-8faa-cd32f44a04c7/products"
        }
      }
    },
    "meta": {
      "created_at": "2024-01-11T19:19:50.087Z",
      "owner": "store",
      "parent_name": "Shoes",
      "sort_order": 2,
      "updated_at": "2024-01-11T19:19:50.087Z"
    }
  }
}

403

Forbidden

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": [
    {
      "title": "Forbidden",
      "status": "403",
      "detail": "entity owned by organization"
    }
  ]
}

404

Bad Request. Not Found.

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": [
    {
      "title": "Not Found",
      "status": "404"
    }
  ]
}

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"
    }
  ]
}

Authorization: http

name: bearerAuthtype: httpscheme: bearer

• curl
• python
• go
• nodejs
• ruby
• csharp
• php
• java
• powershell

• CURL

curl -L -X POST 'https://euwest.api.elasticpath.com/pcm/hierarchies/:hierarchyID/nodes' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "data": {
    "type": "node",
    "attributes": {
      "name": "string",
      "description": "string",
      "slug": "string",
      "curated_products": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ],
      "locales": {}
    },
    "meta": {
      "sort_order": 0
    }
  }
}'

Request Collapse all

Base URL

https://euwest.api.elasticpath.com

Auth

Bearer Token

Parameters

hierarchyID — pathrequired

Body

• Example (from schema)
• create-node

{
  "data": {
    "type": "node",
    "attributes": {
      "name": "string",
      "description": "string",
      "slug": "string",
      "curated_products": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ],
      "locales": {}
    },
    "meta": {
      "sort_order": 0
    }
  }
}

ResponseClear

Click the Send API Request button above and see the response here!