Merchant API: custom field groups

About this article

This article explains how to create and manage custom field groups via the Merchant API, how to assign a group to specific marketplaces, and how to map the custom fields that a group contains.

Table of contents

Introduction

What a custom field group is

Overview

Requirements

Available API endpoints

• Create a custom field group
• Retrieve custom field groups
• Retrieve groups and their linked marketplaces
• Rename custom field groups
• Add custom fields to a group
• Remove custom fields from a group
• Delete a custom field group
• Assign a custom field group to specific marketplaces
• Map a custom field that belongs to a custom field group

Common issues

Next steps

Introduction

If you have a large number of custom fields in your ChannelEngine environment, they become difficult to manage and use. The custom field group feature lets you divide your attributes into groups that are easier to create, update, and map, and to link those groups to the marketplaces you work with via the Merchant API.

This article covers grouping. To create the custom fields themselves, check out Merchant API: custom fields.

What a custom field group is

A custom field group is a set of custom fields that share a common characteristic, such as language, category, or marketplace presence. E.g.: the group Dimensions may include the fields Height, Length, and Width. You can assign the group to one or more marketplaces to make mapping easier.

Depending on whether you use the feature, your custom fields belong to a global group and are visible across all of your connected channels, or belong to a specific group you create. E.g.: if you create a group called Zalando attributes and assign it to Zalando, the group is visible on Zalando in the Mappings step.

Overview

Refer to the flowchart below to visualize how custom field groups are created and exported to a channel.

Requirements

• A ChannelEngine account with a Merchant API key, found at Settings, Merchant API keys, and your base API URL: https://{your-subdomain}.channelengine.net/api.
• Your API key sent in the X-CE-KEY request header: X-CE-KEY: your-merchant-api-key
• The custom fields you want to group already exist. You can only group existing custom fields. To check which fields exist, call GET /v2/custom-fields, or go to Products, Custom fields.

Available API endpoints

• Create a custom field group: POST /v2/product-attribute-group
• Retrieve custom field groups: GET /v2/product-attribute-group
• Retrieve groups and their linked marketplaces: GET /v2/product-attribute-group/linked-channels
• Rename custom field groups: POST /v2/product-attribute-group/rename
• Add custom fields to a group: PUT /v2/product-attribute-group/{groupName}/add
• Remove custom fields from a group: PUT /v2/product-attribute-group/{groupName}/remove
• Delete a custom field group: DELETE /v2/product-attribute-group/{groupName}

Create a custom field group

Use POST /v2/product-attribute-group to create one or more groups from existing custom fields. Both fields are required:

POST /v2/product-attribute-group

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

A successful request returns 201. The endpoint returns 400 for invalid input, 404 if a custom field does not exist, and 409 if a group with that name already exists.

Retrieve custom field groups

Use GET /v2/product-attribute-group to retrieve your groups and the custom fields linked to each one. Use it to audit a group before you change it, or to collect the group names you need for the other endpoints.

GET /v2/product-attribute-group?GroupNames=Amazon%20custom%20attributes

Example response:

{
  "Content": [
    {
      "ProductAttributeGroupId": 812,
      "GroupName": "Amazon custom attributes",
      "LinkedProductExtraData": [
        {
          "ProductExtraDataId": 4412,
          "Key": "Material"
        },
        {
          "ProductExtraDataId": 4413,
          "Key": "Composition"
        }
      ]
    }
  ],
  "Count": 1,
  "TotalCount": 1,
  "ItemsPerPage": 100,
  "StatusCode": 200,
  "Success": true,
  "Message": null
}

The endpoint returns 404 if no group matches the names you provide.

Retrieve groups and their linked marketplaces

Use GET /v2/product-attribute-group/linked-channels to retrieve all groups together with the marketplaces linked to them. Call it before deleting a group, because a group can only be deleted once no marketplaces are linked to it.

The endpoint takes the same GroupNames and Page parameters as the previous one.

GET /v2/product-attribute-group/linked-channels

Example response:

{
  "Content": [
    {
      "ProductAttributeGroupId": 812,
      "GroupName": "Amazon custom attributes",
      "LinkedChannels": [
        {
          "ChannelId": 3391,
          "ChannelName": "Amazon NL",
          "IsEnabled": true,
          "GlobalChannelId": 44,
          "GlobalChannelName": "Amazon"
        }
      ]
    }
  ],
  "Count": 1,
  "TotalCount": 1,
  "ItemsPerPage": 100,
  "StatusCode": 200,
  "Success": true,
  "Message": null
}

Rename custom field groups

Use POST /v2/product-attribute-group/rename to rename one or more groups. Provide the current name and the new name for each group.

POST /v2/product-attribute-group/rename

[
  {
    "OldName": "Amazon custom attributes",
    "NewName": "Amazon NL and DE custom attributes"
  }
]

The endpoint returns 200 on success, 400 for invalid input, 404 if the group does not exist, and 409 if the new name is already taken.

Add custom fields to a group

Use PUT /v2/product-attribute-group/{groupName}/add to add existing custom fields to a group. Indicate the group name in the request path.

PUT /v2/product-attribute-group/Amazon custom attributes/add

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

The endpoint returns 200 on success, and 404 if the group or one of the custom fields does not exist.

Remove custom fields from a group

Use PUT /v2/product-attribute-group/{groupName}/remove to remove custom fields from a group. Indicate the group name in the request path.

PUT /v2/product-attribute-group/Amazon custom attributes/remove

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

Removing a custom field from a group does not delete the field itself. The field stays in your tenant but is no longer assigned to any group.

Delete a custom field group

Use DELETE /v2/product-attribute-group/{groupName} to delete a group. Indicate the group name in the request path. The endpoint deletes one group per call.

DELETE /v2/product-attribute-group/Amazon%20custom%20attributes

Deleting a group does not delete the custom fields it contains. They stay in your tenant.

The endpoint returns 200 on success, 404 if the group does not exist, and 409 if marketplaces are still linked to it.

Assign a custom field group to specific marketplaces

Assigning a group to a marketplace is done in the ChannelEngine web interface. On ChannelEngine:

1. Go to Settings, Custom fields groups. You see an overview of your existing groups.
2. Start typing or select the marketplaces from the dropdown menu.
3. Click Save.

To check the result via the API, call GET /v2/product-attribute-group/linked-channels.

Map a custom field that belongs to a custom field group

Once you create a group and assign it to one or more marketplaces, map the fields in the group to the attributes on the channel. On ChannelEngine:

1. Go to your Dashboard and select the channel the group is linked to.
2. Go to the Mappings tab and locate the attribute you need to map. E.g.: Width.
3. Under the name of the attribute, select Custom fields from the dropdown menu. In the dropdown below, locate the group and the fields it contains, then select the field that corresponds to the channel's attribute.
4. Click Save.

Common issues

Next steps

• Merchant API: custom fields: create, update, retrieve, and delete the custom fields themselves.
• ChannelEngine: custom fields: manage custom fields via a product feed or the web interface.
• Merchant API: rate limits.