Create a custom relationship

POST 
https://euwest.api.elasticpath.com/pcm/custom-relationships

Custom relationships can either be bi-directional or uni-directional.

• Uni-Directional: By setting bi_directional to false (or omitted from request) a uni-directional custom relationship will be created. Within a uni-directional relationship, if Product A links to Product B, Product B will not link back to Product A. This is ideal when one product (e.g., a base product) recommends another (e.g., an upsell), but the reverse recommendation is unnecessary.

• Bi-Directional: By setting bi_directional to true a bi-directional custom relationship will be created. Within a bi-directional relationship, if Product A is linked to Product B, Product B will automatically link back to Product A. This bi-directionality ensures a consistent experience, where products always suggest each other as related items.

For more information on use cases, see Custom Relationships.

Custom Relationship slugs must meet the following criteria:

• be unique
• be prefixed with CRP_. Product Experience Manager automatically adds the CRP_ prefix if you do not include it.
• contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.

Once a custom relationship has been created, you can then create Product Relationships:

1. Add the custom relationship to a product. See Attach a custom relationship to a product.
2. Associate a product to multiple products. See Associate a product with other products under a custom relationship.

Request

application/json

Bodyrequired

data objectrequired
typestringrequired
This represents the type of resource object being returned. Always custom-relationship.
Possible values: [custom-relationship]
attributes objectrequired
namestringrequired
The name of the custom relationship to display to shoppers, such as Kitchen electrics.
Example: Related Products
descriptionstring
A description of the custom relationship.
Example: A list of related products shown on the PDP.
slugstringrequired
A unique slug for the custom relationship. Must match the slug specified in the request path. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.
Possible values: Value must match regular expression ^[A-Za-z0-9._-]+$
Example: CRP_related_products
sort_orderintegernullable
The order in which the custom relationship should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.
Example: 5
external_namestringnullable
The shopper-facing name for the custom relationship. This value will be displayed to shoppers in the store-front, replacing the internal name if present. If set to NULL, the external name will be removed.
Example: Similar items to consider
external_descriptionstringnullable
The shopper-facing description for the custom relationship. This value will be shown to shoppers in the store-front, replacing the internal description if present. If set to NULL, the external description will be removed.
Example: Check out these similar products that may also meet your needs or match your preferences.
bi_directionalboolean
Is this relationship one way or bi-directional true or false. Default is false
Default value: false

Responses

201

Returns a created custom relationship with the following attributes.

application/json

Schema

Schema

data objectrequired
idstringrequired
A unique identifier generated when a custom relationship is created.
typestringrequired
This represents the type of resource object being returned. Always custom-relationship.
Possible values: [custom-relationship]
attributes objectrequired
namestringrequired
The name of the custom relationship to display to shoppers, such as Kitchen electrics.
Example: Related Products
descriptionstring
A description of the custom relationship.
Example: A list of related products shown on the PDP.
slugstringrequired
A unique slug for the custom relationship. Must match the slug specified in the request path. A slug can contain A to Z, a to z, 0 to 9, hyphen, underscore, and period. Spaces or other special characters like ^, [], *, and $ are not allowed.
Possible values: Value must match regular expression ^[A-Za-z0-9._-]+$
Example: CRP_related_products
sort_orderintegernullable
The order in which the custom relationship should be displayed in relation to others. A lower value represents a higher priority in the display order. If set to NULL, the sort order will be removed.
Example: 5
external_namestringnullable
The shopper-facing name for the custom relationship. This value will be displayed to shoppers in the store-front, replacing the internal name if present. If set to NULL, the external name will be removed.
Example: Similar items to consider
external_descriptionstringnullable
The shopper-facing description for the custom relationship. This value will be shown to shoppers in the store-front, replacing the internal description if present. If set to NULL, the external description will be removed.
Example: Check out these similar products that may also meet your needs or match your preferences.
bi_directionalboolean
Is this relationship one way or bi-directional true or false. Default is false
Default value: false
meta objectrequired
ownerstringrequired
The owner of the resource.
Example: store
timestamps objectrequired
created_atdate-timerequired
The date and time the resource is created.
Example: 2024-01-10T20:16:35.343Z
updated_atdate-timerequired
The date and time the resource is updated.
Example: 2024-01-10T20:16:35.343Z

Example (auto)

{
  "data": {
    "id": "string",
    "type": "custom-relationship",
    "attributes": {
      "name": "Related Products",
      "description": "A list of related products shown on the PDP.",
      "slug": "CRP_related_products",
      "sort_order": 5,
      "external_name": "Similar items to consider",
      "external_description": "Check out these similar products that may also meet your needs or match your preferences.",
      "bi_directional": false
    },
    "meta": {
      "owner": "store",
      "timestamps": {
        "created_at": "2024-01-10T20:16:35.343Z",
        "updated_at": "2024-01-10T20:16:35.343Z"
      }
    }
  }
}

created-basic-custom-relationship

Basic

{
  "data": {
    "id": "f3297ee8-da90-45e9-ae56-a2654aebbdfe",
    "type": "custom-relationship",
    "attributes": {
      "name": "Kitchen electrics",
      "description": "Kitchen electric devices",
      "slug": "CRP_kitchen_individual_devices",
      "bi_directional": false
    },
    "meta": {
      "owner": "store",
      "timestamps": {
        "created_at": "2024-01-10T20:16:35.343Z",
        "updated_at": "2024-01-10T20:16:35.343Z"
      }
    }
  }
}

created-custom-relationship-external-sort-order

External name and description, and sort order

{
  "data": {
    "id": "e390ff7e-efc4-4769-90d2-fceabcc1e2cd",
    "type": "custom-relationship",
    "attributes": {
      "name": "Related Products",
      "description": "A list of related products shown on the PDP",
      "slug": "CRP_related_products",
      "sort_order": 5,
      "external_name": "Similar items to consider",
      "external_description": "Check out these similar products that may also meet your needs or match your preferences.",
      "bi_directional": false
    },
    "meta": {
      "owner": "store",
      "timestamps": {
        "created_at": "2024-01-10T20:16:35.343Z",
        "updated_at": "2024-01-10T20:16:35.343Z"
      }
    }
  }
}

created-custom-relationship-bi-directional

Bi-Directional

{
  "data": {
    "id": "e390ff7e-efc4-4769-90d2-fceabcc1e2cd",
    "type": "custom-relationship",
    "attributes": {
      "name": "Related Products",
      "description": "A list of related products shown on the PDP",
      "slug": "CRP_related_products",
      "bi_directional": true
    },
    "meta": {
      "owner": "store",
      "timestamps": {
        "created_at": "2024-01-10T20:16:35.343Z",
        "updated_at": "2024-01-10T20:16:35.343Z"
      }
    }
  }
}

422

Bad request. The request failed validation.

application/json

Schema

Schema

errors undefined[]required
Array [
statusstringrequired
The HTTP response code of the error.
Example: 500
titlestringrequired
A brief summary of the error.
Example: Internal server error
detailstring
Optional additional detail about the error.
Example: An internal error has occurred.
request_idstring
Internal request ID.
Example: 00000000-0000-0000-0000-000000000000
metaobject
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 [
statusstringrequired
The HTTP response code of the error.
Example: 500
titlestringrequired
A brief summary of the error.
Example: Internal server error
detailstring
Optional additional detail about the error.
Example: An internal error has occurred.
request_idstring
Internal request ID.
Example: 00000000-0000-0000-0000-000000000000
metaobject
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/custom-relationships");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer <token>");
var content = new StringContent("{\n  \"data\": {\n    \"type\": \"custom-relationship\",\n    \"attributes\": {\n      \"name\": \"Related Products\",\n      \"description\": \"A list of related products shown on the PDP.\",\n      \"slug\": \"CRP_related_products\",\n      \"sort_order\": 5,\n      \"external_name\": \"Similar items to consider\",\n      \"external_description\": \"Check out these similar products that may also meet your needs or match your preferences.\",\n      \"bi_directional\": false\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

Body required

• Example (from schema)
• create-basic-custom-relationship
• create-custom-relationship-external-sort-order
• create-custom-relationship-bi-directional

{
  "data": {
    "type": "custom-relationship",
    "attributes": {
      "name": "Related Products",
      "description": "A list of related products shown on the PDP.",
      "slug": "CRP_related_products",
      "sort_order": 5,
      "external_name": "Similar items to consider",
      "external_description": "Check out these similar products that may also meet your needs or match your preferences.",
      "bi_directional": false
    }
  }
}

ResponseClear

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