Create relationships between a node and child nodes

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

Use this endpoint to create relationships between a single parent node and one or more child nodes. You can create a relationship only if:

• The parent node already exists.
• All child nodes already exist.
• Every child node in the body of the request exists in the same hierarchy as the parent node.
• A node is not a parent of itself. An array of child nodes request body must not contain the ID of the parent node in the path.
• All siblings in a hierarchy must have a unique slug. Siblings are the child nodes that are related to the same parent.

Sort Order

You can also provide sort_order information when you create a relationship by adding a meta object to the array of node reference objects for each child node that requires sorting.

The node with the highest value of sort_order appears at the top of the response. 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 relationships, all child nodes in the response for Get a Node’s Children request are ordered by the updated_at time in descending order. The most recently updated child node appears at the top of the response.
• If you set sort_order for only a few child nodes or not all, the child nodes with sort_order value appear first in the response and then other child nodes appear in the order of updated_at time.

You can also specify a sort_order when creating and updating a node.

• If you create or update 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\updating Node A is overwritten.
• If you create\update 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\updated Node A is not overwritten.

Request

Path Parameters

hierarchyID stringrequired

A unique identifier for the hierarchy.

nodeID stringrequired

A unique identifier for the node.

application/json

Body

data object[]
Array [
id stringrequired
The unique identifier of the child node. Must not match the node ID specified in the request path.
Example: 00000000-0000-0000-0000-000000000000
type stringrequired
This represents the type of resource object being returned. Always node.
Possible values: [node]
]

Responses

200

Successfully returns the node's children

application/json

Schema

Schema

data object

id string

The unique identifier of a node.

type string

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

Possible values: [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 string[]

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 stringrequired

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

Possible values: [node]

id stringrequired

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.

Example: 2020-09-22T09:00:00

updated_at date-time

The date and time a node was updated.

Example: 2020-09-22T09:00:00

parent_name string

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

owner string

The node owner, either organization or store.

Possible values: [store, organization]

Example (auto)

{
  "data": {
    "id": "string",
    "type": "node",
    "attributes": {
      "name": "string",
      "description": "string",
      "slug": "string",
      "curated_products": [
        "string"
      ],
      "locales": {}
    },
    "relationships": {
      "children": {
        "data": [
          null
        ],
        "links": {
          "related": "string"
        }
      },
      "parent": {
        "data": {
          "type": "node",
          "id": "string"
        }
      },
      "products": {
        "data": [
          null
        ],
        "links": {
          "related": "string"
        }
      }
    },
    "meta": {
      "sort_order": 0,
      "created_at": "2020-09-22T09:00:00",
      "updated_at": "2020-09-22T09:00:00",
      "parent_name": "string",
      "owner": "store"
    }
  }
}

set-node-children

{
  "data": {
    "type": "node",
    "id": "9ea0de15-3347-43dd-8faa-cd32f44a04c7",
    "attributes": {
      "description": "Latest Ballet Shoes",
      "locales": {
        "fr-FR": {
          "name": "Chaussons de ballet",
          "description": "Dernières 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"
        }
      },
      "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",
      "sort_order": 5,
      "updated_at": "2024-01-11T19:56:53.695Z"
    }
  }
}

403

Forbidden

application/json

Schema

Schema

errors undefined[]required
Array [
status stringrequired
The HTTP response code of the error.
Example: 500
title stringrequired
A brief summary of the error.
Example: Internal server error
detail string
Optional additional detail about the error.
Example: An internal error has occurred.
request_id string
Internal request ID.
Example: 00000000-0000-0000-0000-000000000000
meta object
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

{
  "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.
Example: 500
title stringrequired
A brief summary of the error.
Example: Internal server error
detail string
Optional additional detail about the error.
Example: An internal error has occurred.
request_id string
Internal request ID.
Example: 00000000-0000-0000-0000-000000000000
meta object
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

{
  "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.
Example: 500
title stringrequired
A brief summary of the error.
Example: Internal server error
detail string
Optional additional detail about the error.
Example: An internal error has occurred.
request_id string
Internal request ID.
Example: 00000000-0000-0000-0000-000000000000
meta object
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

{
  "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.
Example: 500
title stringrequired
A brief summary of the error.
Example: Internal server error
detail string
Optional additional detail about the error.
Example: An internal error has occurred.
request_id string
Internal request ID.
Example: 00000000-0000-0000-0000-000000000000
meta object
Additional supporting meta data for the error.
Example: {"missing_ids":["e7d50bd5-1833-43c0-9848-f9d325b08be8"]}
]

Example (auto)

{
  "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

• csharp
• curl
• dart
• go
• http
• java
• javascript
• kotlin
• c
• nodejs
• objective-c
• ocaml
• php
• powershell
• python
• r
• ruby
• rust
• shell
• swift

• HTTPCLIENT
• RESTSHARP

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://euwest.api.elasticpath.com/pcm/hierarchies/:hierarchyID/nodes/:nodeID/relationships/children");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer <TOKEN>");
var content = new StringContent("{\n  \"data\": [\n    {\n      \"id\": \"00000000-0000-0000-0000-000000000000\",\n      \"type\": \"node\"\n    }\n  ]\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Request Collapse all

Base URL

https://euwest.api.elasticpath.com

Auth

Bearer Token

Parameters

hierarchyID — pathrequired

nodeID — pathrequired

Body

• Example (from schema)
• set-node-children

{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "node"
    }
  ]
}

ResponseClear

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