Merchant API: custom fields

About this article

This article describes how to create and manage custom fields groups via the Merchant API and the ChannelEngine web interface. 

Table of contents

Introduction

Custom fields

• Add, update, or delete a custom field
• Bulk add, update, or delete a custom field

Custom fields groups

• Create a custom fields group
• Rename one or more custom fields groups
• Add a custom field to a group
• Remove a custom field from a group
• Retrieve an overview of custom fields groups
• Delete custom fields groups

Assign a custom fields group to specific marketplaces

Map a custom field that belongs to a custom fields group

Additional information

Introduction

Custom fields enable you to map values from your product feed that fall outside of ChannelEngine's set of default attributes. Create custom fields in bulk via the Merchant API. Optionally, create and manage your custom fields in groups, and make those groups exclusively visible to specific channels. 

Custom fields

Manage custom fields via the Merchant API, as product extra data.

Available endpoints

• Add, update, and delete a custom field:  PATCH /v2/products/extra-data 

Example payload:

"ExtraData": 
  [ 
    { 
      "Key": "string",         
      "Value": "string",         
      "Type": "TEXT",         
      "IsPublic": true
    }     
  ] 	

• Bulk add, update, and delete custom fields: PATCH /v2/products/extra-data/bulk 

  Add, update, and delete custom fields in bulk by sending multiple sets of data in the payload at once. 

Custom fields groups

If you have a large number of custom fields in your ChannelEngine environment, it can become difficult to manage and use them. The custom fields 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, via the Merchant API. 

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 fields group feature, your custom fields are either:

• Global custom fields - visible across all of your marketplaces. If you do not use the custom fields group feature, or you do use the custom fields group feature without assigning your custom field group to any given marketplaces, your custom fields are global.
• Custom fields group - only visible on the marketplace to which you assign it. E.g.: if you create a group called Zalando attributes and assign the group to Zalando, custom attributes within this group are only visible on the Zalando marketplace.

Available endpoints

• Create a custom fields group: POST /v2/product-attribute-group

  Indicate the name of the group and the names of custom fields:

  • GroupName - the name of the custom fields 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 - the name(s) of existing custom fields that you want to group. To check what your existing custom fields are, go to Products, Custom fields, and study the overview.

Example payload:

[
  {
    "GroupName":"Amazon custom attributes",
    "ProductExtraDataKeys":["Material", "Composition"]
  }
]

• Rename one or more custom fields groups: POST /v2/product-attribute-group/rename 

  Indicate the name of the custom fields group that you want to change, as well as the new name. 

Example payload:

[
  {
    "old_GroupName":"Amazon custom attributes",
    "new_GroupName":"Amazon NL and DE custom attributes"
  }
]

• Add a custom field to a group: 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.

Example payload:

{"ProductExtraDataKeys":["Sleeve length", "Collar type"]}

• Remove a custom field from a group: PUT /v2/product-attribute-group/{groupName}/remove

  Indicate the name of the custom fields group in the request path. 

Example payload:

{"ProductExtraDataKeys":["Sleeve length", "Collar type"]}

• Retrieve an overview of custom fields groups: GET /v2/product-attribute-group/linked-channels 

  This overview includes the list of marketplaces to which the custom fields groups are mapped. 

• Delete custom fields groups: DELETE /v2/product-attribute-group

  Bear in mind that a custom fields group can only be deleted if no marketplaces are linked to it. On ChannelEngine, first go to Settings, Custom field groups, and remove any marketplace references by clicking the x next to the names of the marketplaces.

Assign a custom fields group to specific marketplaces

To assign a custom fields group to one or more marketplaces, on ChannelEngine:

1. Go to Settings, Custom fields groups. You are presented with an overview of your existing custom fields groups.
2. Start typing or select the name of the marketplace(s) from the dropdown menu.
3. When you are done selecting the marketplaces, click Save.

Map a custom field that belongs to a custom fields group

Once you create a custom fields group and assign the group to one or more marketplace(s), map the attributes from the group to the attributes on the marketplace. 

1. Go to your Dashboard and select the marketplace to which your custom fields group is linked.
2. Go to the Mappings tab and locate the attribute(s) that you need to map. E.g.: Width.
3. Under the name of the attribute, select Custom fields from the dropdown menu. In the dropdown that appears below, locate the corresponding custom fields group and the fields that are contained in it. Select the custom field that corresponds to the marketplace's attribute.
4. Click Save.

Additional information

When working with the Merchant API, pay attention to the rate limits that are communicated in the response headers. For custom fields groups, the rate limits and the corresponding time intervals are as follows: