Merchant API: custom fields

About this article

This article explains how to add, update, and delete custom fields on products via the Merchant API, using the extra data endpoints.

Table of contents

Introduction

Overview

Requirements

Available API endpoints

Custom field properties

Manage a custom field on one product

Manage custom fields on multiple products

Include custom fields when creating a product

Retrieve custom fields

Delete custom fields

Use case: market-specific prices

Common issues

Next steps

Introduction

Custom fields, also called extra data or custom attributes, store product information that falls outside ChannelEngine's standard fields. Common uses include attributes a specific marketplace requires, such as Heel height or Sleeve length, market-specific prices, and internal metadata such as supplier codes.

In the Merchant API, custom fields are managed as product extra data through their own endpoints. They are independent of the product payload and are not overwritten by POST /v2/products.

You can also manage custom fields via a product feed or the ChannelEngine web interface. See ChannelEngine: custom fields.

Overview

Refer to the flowchart below to visualize how custom field values travel from your system to a channel.

Requirements

• A ChannelEngine account with a Merchant API key, found under Settings, Merchant API keys, and your base API URL: https://{your-subdomain}.channelengine.net/api.
• The products already exist on ChannelEngine. Each is identified by its unique Merchant product number.

Available API endpoints

• Add, update, or delete a custom field: PATCH /v2/products/extra-data
  Use this endpoint to manage custom fields on a single product.
• Add, update, or delete custom fields in bulk: PATCH /v2/products/extra-data/bulk
  Use this endpoint to manage custom fields on several products in one call.
• Retrieve custom fields: GET /v2/custom-fields
  Use this endpoint to fetch all custom field names, including whether each field is public and whether it is currently in use.
• Delete custom fields: DELETE /v2/custom-fields
  Use this endpoint to delete custom fields by their IDs. You cannot delete a custom field that is assigned to a product or used elsewhere on ChannelEngine, such as in mappings.

If you work with a large number of custom fields, group them and assign each group to specific marketplaces. See Merchant API: custom field groups.

Custom field properties

The set of properties below applies to the ExtraData array in a POST /v2/products payload. The extra data endpoints accept only Op, Key, and Value.

Manage a custom field on one product

Use PATCH /v2/products/extra-data with the Merchant product number and an array of operations.

The endpoint uses JSON Patch conventions. The supported operations are add, replace, and remove.

Add two market-specific prices:

{
  "MerchantProductNo": "SKU-001",
  "Operations": [
    {
      "Op": "add",
      "Key": "Price_NL",
      "Value": "79.99"
    },
    {
      "Op": "add",
      "Key": "Price_DE",
      "Value": "74.99"
    }
  ]
}

Update an existing key:

{
  "MerchantProductNo": "SKU-001",
  "Operations": [
    {
      "Op": "replace",
      "Key": "Price_NL",
      "Value": "84.99"
    }
  ]
}

Remove a key:

{
  "MerchantProductNo": "SKU-001",
  "Operations": [
    {
      "Op": "remove",
      "Key": "Price_NL"
    }
  ]
}

Manage custom fields on multiple products

The PATCH /v2/products/extra-data/bulk endpoint follows the same structure but accepts an array of products, each with its own operations.

The endpoint also uses JSON Patch conventions. The supported operations are add, replace, and remove.

[
  {
    "MerchantProductNo": "SKU-001",
    "Operations": [
      { "Op": "replace", "Key": "Price_NL", "Value": "84.99" }
    ]
  },
  {
    "MerchantProductNo": "SKU-002",
    "Operations": [
      { "Op": "add", "Key": "Price_DE", "Value": "69.99" },
      { "Op": "replace", "Key": "SupplierCode", "Value": "SUP-9945" }
    ]
  }
]

Group all products that need the same fields updated into one call rather than sending a call per product.

Include custom fields when creating a product

You can also set custom fields directly in a POST /v2/products payload, using the ExtraData array. This is useful when you create a product and want to set everything in one call.

[
  {
    "MerchantProductNo": "SKU-003",
    "Name": "Green Yoga Mat",
    "Price": 39.99,
    "ExtraData": [
      { "Key": "Price_NL", "Value": "39.99" },
      { "Key": "Price_DE", "Value": "36.99" },
      { "Key": "Material", "Value": "Natural rubber" }
    ]
  }
]

Retrieve custom fields

Use GET /v2/custom-fields to fetch every custom field that exists in your ChannelEngine tenant, whichever way it was created: via a product feed, the Merchant API, or the web interface.

The response returns each field's name, whether it is public, and whether it is actively used. Call it before you add a new custom field to avoid creating near-duplicates, and to collect the IDs you need to delete fields.

GET /v2/custom-fields

The response is paginated. Example response:

{
  "Content": [
    {
      "Id": 4412,
      "Key": "Price_NL",
      "FieldType": "DECIMAL",
      "Description": "Selling price for the Dutch market",
      "IsPublic": true,
      "IsUsed": true,
      "IsReadonly": false
    },
    {
      "Id": 4413,
      "Key": "SupplierCode",
      "FieldType": "TEXT",
      "Description": "Internal supplier reference",
      "IsPublic": false,
      "IsUsed": true,
      "IsReadonly": false
    },
    {
      "Id": 4414,
      "Key": "Sleeve length",
      "FieldType": "INTEGER",
      "Description": null,
      "IsPublic": true,
      "IsUsed": false,
      "IsReadonly": false
    }
  ],
  "Count": 3,
  "TotalCount": 3,
  "ItemsPerPage": 100,
  "StatusCode": 200,
  "Success": true,
  "Message": null
}

Delete custom fields

Use DELETE /v2/custom-fields to delete one or more custom fields. Pass the custom fields IDs in the CustomFieldsIds query parameter. To get the IDs, call GET /v2/custom-fields.

Repeat the parameter once per ID:

DELETE /v2/custom-fields?CustomFieldsIds=4414&CustomFieldsIds=4415

The endpoint returns 404 if a given custom field ID does not exist in your tenant.

If you attempt to delete a field that is currently in use on ChannelEngine, such as in a mapping or a rule, the warning "some of custom fields are used" is returned. Remove the mappings before deleting the custom field.

Deleting a custom field removes the definition from your tenant. It does not remove its values from products: to do that, send a remove operation to PATCH /v2/products/extra-data.

Use case: market-specific prices

The Price field in the product payload holds a single default price. If you sell on several markets at different prices, do not create duplicate products or extra price fields. Store each market price as a custom field instead, using keys such as Price_NL, Price_DE, and Price_FR.

Then map each channel to the right price key in the channel's offer settings. One product, one record, and the correct price per market.

Common issues

Next steps

• ChannelEngine: custom fields: manage custom fields via a product feed or the web interface.
• ChannelEngine: AI attribute builder: generate new attributes from your existing product content.