ChannelEngine: custom attributes (a.k.a. custom fields/product extra data)
About this article
This article describes custom attributes (a.k.a. custom fields product extra data) on ChannelEngine, how to create them, and how to manage them.
Table of contents
- Create a custom attribute group
- Update a custom attribute group
- Assign a custom attribute group to a marketplace
- Map a custom attribute that belongs to a custom attribute group
- Delete a custom attribute group
- Additional information
Introduction
There are two types of product attributes on ChannelEngine:
- Default attributes - such as Name, Description, Price, Image URL, etc. If used in replacement tags, these have a {CE:[ATTRIBUTE_NAME]} label.
- Custom attributes - which can be anything like Number of wheels, Warranty period, Weight, etc. If used in replacement tags, these have a {MY:[ATTRIBUTE_NAME]} label.
Custom attributes, also known as custom fields or extra data fields, can be added via a product feed, ChannelEngine's API, or the ChannelEngine interface. Once these extra attributes are added to ChannelEngine, you can manage them by going to Products, Custom fields.
Add custom attributes
-
ChannelEngine's Merchant API - you can add custom fields via the
POST /v2/products
endpoint.
"ExtraData": [ { "Key": "string", "Value": "string", "Type": "TEXT", "IsPublic": true } ]
- Product feed - you can add custom fields as extra columns in your product feed. If you have several feeds, make sure to add the unique product identifier, which is the Merchant product number.
- ChannelEngine's interface - you can add custom fields by going to Products, Custom fields, and selecting Add custom field.
Manage custom attributes
-
ChannelEngine's Merchant API - you can update as well as delete custom fields via the
PATCH /v2/products/extra-data/bulk
endpoint. - Product feed - you can update custom fields by changing the values directly in the product feed. ChannelEngine imports the feed and recognizes the changes.
-
ChannelEngine's interface - you can update and delete custom fields under Products, Custom fields. In the Custom fields overview, you can see your custom fields in a list.
There are four columns:
- Name - the name of the custom field. It is possible to change this, but note that any changes made in this section are reflected in many other parts of the system, including advanced mapping rules.
- Type - the attribute's data type. There are currently four types: Text, Number, URL, and Image URL. These data types are currently not in use, as all custom fields are considered strings of data, but may become relevant in future.
- Is public? - defines if an attribute is considered public or not. If its value is true (i.e.: yes), this attribute is included in feeds for custom channels or click-and-ad channels. If its value is false (i.e.: no), the attribute can still be used for channel mappings but is not included in exports for custom product feeds and custom channels.
-
Actions - there are three types of actions available:
-
Information - shows if and where a custom field is in use, and if it can be deleted.
-
Edit - allows you to change the name, type, and public status of the attribute. Make sure to select the Save icon to store any changes made.
- Delete - allows you to delete custom fields. If a custom field is in use in mappings or rules, it cannot be deleted.
-
Information - shows if and where a custom field is in use, and if it can be deleted.
Custom attribute groups
If you have a large number of custom attributes (a.k.a. custom fields) in your ChannelEngine environment, it can become difficult to manage and use them. The Custom attribute group feature allows you to divide your attributes into groups that are easier to create, update, and map – as well as to link these groups to the marketplaces you work with.
A custom attribute group is a set of custom attributes that share a common characteristic (e.g.: language, category, marketplace presence). E.g.: the custom attribute group Dimensions may include attributes such as Height, Length, and Width. You can assign the custom attribute group to one or more marketplaces for easier mapping of custom attributes.
Depending on whether you make use of the Custom attribute group feature or not, your custom attributes are either:
- Global custom attributes - visible across all of your marketplaces. If you do not use the Custom attribute group feature or use it without assigning your custom attribute group to any particular marketplaces, your custom fields are global.
- Custom attribute group - only visible on the marketplace you assigned them to. E.g.: if you create a group called Zalando attributes and assign it to Zalando, custom attributes within this group are only visible on the Zalando marketplace.
To enable the Custom attribute group feature, get in touch with your customer success manager or a member of the Support team.
Create a custom attribute group
To create a custom attribute group, you need to use ChannelEngine’s Merchant API endpoint POST /v2/product-attribute-group
to create a custom attribute group. Below is an example of payload:
[{"GroupName":"Amazon custom attributes","ProductExtraDataKeys":["Material", "Composition"]}]
Indicate the name of the group and the names of custom attributes:
-
GroupName
- the name of the custom attribute group. The maximum number of characters allowed is 256. The name can only contain letters, digits, and white spaces. Special characters, such as !@#$%, are not allowed. -
ProductExtraDataKeys
- tthe name(s) of existing custom attributes that you want to group. To check your existing custom attributes, go to Products, Custom fields.
To rename one or more product attribute groups, use this endpoint POST /v2/product-attribute-group/rename
. Make sure to indicate the name of the custom attribute group you want to change, as well as the new name. Below is an example of payload:
[{"old_GroupName":"Amazon custom attributes","new_GroupName":"Amazon NL and DE custom attributes"}]
Update a custom attribute group
Adding custom attributes to the custom group or removing them from the group can also only be done via ChannelEngine's Merchant API.
Add a custom attribute
To add new custom attributes to the group, use this endpoint PUT /v2/product-attribute-group/{groupName}/add
. In the request path, indicate the name of the custom attribute group, e.g.: PUT /v2/product-attribute-group/Amazon custom attributes/add
. Below is an example of payload:
{"ProductExtraDataKeys":["Sleeve length", "Collar type"]}
Remove a custom attribute
To remove custom attributes from the group, use this endpoint PUT /v2/product-attribute-group/{groupName}/remove
. Similarly, indicate the name of the custom attribute group in the request path. Below is an example of payload:
{"ProductExtraDataKeys":["Sleeve length", "Collar type"]}
Assign a custom attribute group to a marketplace
To assign a custom attribute group to one or more marketplaces:
- Go to Settings, Custom field groups. You are presented with an overview of your existing custom attribute groups.
- Start typing or select the name of the marketplace(s) from the dropdown menu.
- When you are done, click Save.
To get an overview of custom attributes groups and the marketplaces linked to them via ChannelEngine's Merchant API, use the endpoint GET /v2/product-attribute-group/linked-channels
.
Map a custom attribute that belongs to a custom attribute group
Once you create a custom attribute group and assign marketplace(s) to it, you can map the attributes within the group to those required on the marketplace.
- Go to your Dashboard and select the marketplace that your custom attribute group is linked to.
- Proceed to the Mapping tab and locate the attribute(s) you need to map. E.g.: Width.
- Under the name of the attribute, select Custom fields from the dropdown menu. In the dropdown that appears below, locate the corresponding custom attribute group and the attributes that are part of it. Select the corresponding attribute.
- Click Save.
Delete a custom attribute group
Deleting custom attribute groups can only be done via ChannelEngine's Merchant API. Use this endpoint DELETE /v2/product-attribute-group
to delete a custom attribute group from ChannelEngine. Bear in mind that a product attribute group can only be deleted if no marketplaces are linked to it. Make sure you first go to Settings, Custom field groups; and remove the marketplace references by clicking the Remove icon next to the names of marketplaces.
Additional information
When working with the Merchant API, pay attention to the rate limits communicated in the response headers. For custom attribute groups, the rate limits and the corresponding time intervals are as follows:
Endpoint | Time interval | Rate limit |
POST /v2/product-attribute-group |
15 minutes | 15 |
DELETE /v2/product-attribute-group |
15 minutes |
15 |
PUT /v2/product-attribute-group/{groupName}/add |
15 minutes | 15 |
PUT /v2/product-attribute-group/{groupName}/remove |
15 minutes | 15 |
GET /v2/product-attribute-group |
15 minutes | 5 |
GET /v2/product-attribute-group/linked-channels |
15 minutes | 15 |
POST /v2/product-attribute-group/rename |
60 minutes | 10 |
Comments
0 comments
Article is closed for comments.