API Reference

Products

The product as the main source in the NextChapter PIM API is represented in JSON format, and its data structure is based on a "definition". Each field or property can be represented as follows:

  • Single value such as date, string, integer, decimal, etc.
  • Multiple value such as categories and properties represented as JSON array.
  • Prices represented as JSON complex type (also inside a channel node).
  • Multilanguage value represented as JSON complex type.
  • Multichannel value represented as JSON complex type.

Product data can be retrieved using GET product and product list operations. The response is almost the same as the request body except for the field state. 

"state": "Valid"

In addition, each multichannel value can depend on languages (multiple channel and language content).

Example JSON Product response:

{
  "productId": "nike.100.0014",
  "externalId": "10",
  "name": "Nike Special T-shirt",
  "brand": "nike",
  "supplier": "nike",
  "productGroup": "nike.100",
  "metaDescription": "meta description",
  "size": [
    "Large",
    "Small",
    "Medium"
  ],
  "category": [
    "Casual"
  ],
  "season": "2023S",
  "languages": {
    "en": {
      "description": "Lorum ipsum en",
      "specifications": "Lorum ipsum en"
    },
    "nl": {
      "description": "Lorum ipsum nl",
      "specifications": "Lorum ipsum nl"
    }
  },
  "channels": {
    "shop1": {
      "languages": {
        "en": {
          "specifications": "Lorum ipsum en"
        }
      }
    },
    "shop2": {
      "languages": {
        "en": {
          "specifications": "Lorum ipsum en"
        },
        "nl": {
          "specifications": "Lorum ipsum nl"
        }
      }
    }
  },
  "variants": [
    {
      "ean": "4354623068357",
      "sku": "nike.100.0014",
      "sortOrder": 10,
      "color": "Blue",
      "size": "M",
      "price": {
        "EUR": 25.99,
        "USD": 25.99
      },
      "purchasePrice": {
        "EUR": 10.99,
        "USD": 10.99
      },
      "channels": {
        "shop1": {
          "price": {
            "EUR": 21.99
          }
        },
        "shop2": {
          "price": {
            "EUR": 22.99,
            "USD": 22.99
          }
        }
      }
    }
  ],
  "state": "Valid"
}

Definitions

The product fields are based on a definition, which you can retrieve from the GET product definitions endpoint.

Example JSON Product Definitions response:

{
  "product": {
    "productId": {
      "fieldType": "String"
    },
    "externalId": {
      "fieldType": "String",
      "required": true
    },
    "name": {
      "fieldType": "Name",
      "required": true
    },
    "brand": {
      "fieldType": "Brand",
      "required": true
    },
    "supplier": {
      "fieldType": "Supplier",
      "required": true
    },
    "description": {
      "fieldType": "Html",
      "multiLanguage": true
    },
    "specifications": {
      "fieldType": "Html",
      "multiLanguage": true,
      "multiChannel": true
    },
    "season": {
      "fieldType": "Property",
      "required": true
    }
  },
  "variant": {
    "ean": {
      "fieldType": "EanCode",
      "required": true
    },
    "sku": {
      "fieldType": "MiscCode",
      "required": true
    },
    "sortOrder": {
      "fieldType": "Integer",
      "required": true
    },
    "price": {
      "fieldType": "Price",
      "multiChannel": true,
      "required": true
    },
    "purchasePrice": {
      "fieldType": "Price",
      "required": true
    },
    "color": {
      "fieldType": "Property",
      "required": true
    }
  }
}

Product identifiers

Some operations need a product unique identifier. These identifiers are provided as the first fields when a product or product list is requested.

{  
"productId": "nike.100.0014",  
"externalId": "3",  
...  
}

Languages

Some values may depend on languages. You can include multilanguage fields in the "languages" node of the product.

"languages": {
  "en": {
    "description": "Lorum ipsum en",
    "specifications": "Lorum ipsum en"
  },
  "nl": {
    "description": "Lorum ipsum nl",
    "specifications": "Lorum ipsum nl"
  }
}

Channels

Some values can depend on channels, representing different content for different channels. You can include multichannel fields in the "channels" node.

Languages can be included in channels:

"channels": {
  "shop1": {
    "languages": {
      "en": {
        "specifications": "Lorum ipsum en"
      }
    }
  },
  "shop2": {
    "languages": {
      "en": {
        "specifications": "Lorum ipsum en"
      },
      "nl": {
        "specifications": "Lorum ipsum nl"
      }
    }
  }
}

Prices can also be included in channels within the variant of a product.

"channels": {
  "shop1": {
    "price": {
      "EUR": 30.99
    }
  },
    "shop2": {
      "price": {
        "EUR": 31.99,
        "USD": 31.99
      }
    }
}

Variants

Product variants should be defined in their own request node.

"variants": [
  {
    "ean": "4354623068356",
    "sku": "nike.100.0014",
    "sortOrder": 10,
    "color": "Blue",
    "size": "M",
    "price": {
      "EUR": 25.99,
      "USD": 25.99
    },
    "purchasePrice": {
      "EUR": 20.99,
      "USD": 20.99
    },
    "channels": {
      "shop1": {
        "price": {
          "EUR": 23.99
        }
      },
      "shop2": {
        "price": {
          "EUR": 26.99,
          "USD": 26.99
        }
      }
  },
  ...
]

Exceptions

The NextChapter PIM API returns exceptions in the HTTP response body when something goes wrong.

A business exception usually returns a 400 bad request or 404 not found status code and has up to three properties:

  • Error code.
  • Message.
  • Value or values that causes the exception.
{
    "code": "CURRENCY_NOT_FOUND",
    "message": "Unable to find currency",
    "values": [
        "Eu"
    ]
}

An authentication exception returns a 401 unauthorized status code when the request has an invalid token.

An authorization exception returns a 403 forbidden status code when the client doesn't have operation permissions on the resource.

{
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
    "title": "Unauthorized",
    "status": 401,
    "traceId": "00-2e53cd6ac4051fced66edf85bf6c4046-7603703ec39d3f7c-00"
}

Data formats

Understanding the data formats used in the NextChapter PIM API is essential for processing and interpreting responses correctly. Here's a detailed overview of the data formats you'll encounter:

Date & Datetime

This section outlines the data formats related to dates and times used.

  • Filters. The FromLastModifiedOn and ToLastModifiedOn parameters follow the format YYYY-MM-DD.
  • Datetime. Definition input fields follow the recommended format YYYY-MM-DDTHH:MM:SS.FFFFFFF in UTC (Coordinated Universal Time) standard. For example, 6:13 PM PDT on August 19th, 2010, would be represented as '2010-08-19T18:13:00.8957280'.
  • Date. Definition input fields (no time specified) the recommended format is YYYYY-MM-DD.
  • Outputs.
    • For fields like CreatedOn and LastModifiedOn, the format is YYYY-MM-DDTHH:MM:SS.FFFFFFF in UTC (Coordinated Universal Time) standard. For example, 6:13 PM PDT on August 19th, 2010, would be represented as '2010-08-19T18:13:00.8957280'.
    • For custom definition output fields the format is also the same YYYY-MM-DD HH:MM:SS and YYYY-MM-DD.

Decimal and Prices

Decimal values, including prices, are represented in the format dd.dd or dd.d, or even dd when there is no decimal, using a dot as the decimal separator. For instance:

  • A price of 20.22 EUR would be expressed as '20.22'.
  • Another example is a price of 20.20 EUR, which would be expressed as '20.2'.

How to Create a New Product

Creating a new product in the NextChapter PIM API is a straightforward process, allowing you to quickly add products. This section provides you with step-by-step guidance on how to create a new product using the PIM API.

To create a product, you'll need to submit a JSON request to the PIM API endpoint with the product details. Below, we outline the essential steps and provide an example JSON request for your reference.

Follow these steps to successfully create a new product:

  1. Authentication: Ensure you have obtained a valid security token (bearer token) to authenticate your requests to the PIM API.

  2. JSON Request: Prepare a JSON request that includes the necessary product information. This should include attributes such as productId, externalId, name, brand, and any variants you want to associate with the product.

  3. POST Request: Make a POST request to the appropriate PIM API endpoint for creating products. Include your JSON request in the request body.

  4. Response: The PIM API will respond with a confirmation or error message, indicating whether the product was successfully created or if there were any issues.

Before creating a product, it's recommended to retrieve the product definitions to identify which fields are required. To do this, execute a GET request to the endpoint GET /v1/products/definitions. The response will provide information about required fields for both the product and variants.

Here is an example of how to retrieve the product definition:

# Retrieve the product definitions
curl -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://pim.api.nextchapter-ecommerce.com/v1/products/definitions

The response will contain details about the fields, including whether they are required or optional. See Definitions section for more detail.

To help you get started, below is a minimal JSON request example for creating a new product. You could use this as a definition (always regarding to you required fields), replacing the sample data with your product details:

{
    "productId": "nike.100.0025",
    "externalId": "25",
    "name": "New Nike 25",
    "brand": "nike",
    "variants": [
        {
            "ean": "4004833068381",
            "sku": "nike.100.0025",
            "sortOrder": 10,
            "color": "Blue",
            "price": {
                "EUR": 25.99
            },
            "purchasePrice": {
                "EUR": 10.99
            }
        }
    ]
}

Note: If some required fields are not included, the product will be created but with an Invalid state. Later you can update it to include the missed ones. You can filter by state at How to Retrieve a list of Products with Filters

The response for this request sample is:

{
    "id": "86",
    "timestamp": "2023-09-18T15:15:52.0466599Z"
}

How to Update a Product

Updating an existing product in the NextChapter PIM API allows you to modify product details, prices, or other attributes to keep your product data up to date. This section provides a step-by-step guide how to update a product using the PIM API.

To update a product, you'll need to submit a JSON request to the PIM API endpoint with the updated product information. Below, we outline the essential steps and provide an example JSON request:

  1. Authentication: Ensure you have obtained a valid security token (bearer token) to authenticate your requests to the PIM API.

  2. JSON Request: Prepare a JSON request that includes the updated product information. You should include the productId of the product you want to update and provide the modified attributes, including any changes to variants, prices, or other product details.

  3. PATCH Request: Make a PATCH request to the appropriate PIM API endpoint for updating products. Include your JSON request in the request body.

  4. Response: The PIM API will respond with a confirmation or error message, indicating whether the product was successfully updated or if there were any issues.

Here is an example of how to update a product, including:

  • A content channel for an existing channel "shop1"
  • A new price ("price") for an existing channel "shop2", for two available currencies: "EUR" and USD".
{
  "productId": "nike.100.0025",
  "externalId": "25",
  "name": "New Nike 25",
  "brand": "nike",
  "channels": {
    "shop1": {
      "languages": {
        "en": {
          "specifications": "Lorum ipsum en"
        }
      }
    }
  },
  "variants": [
    {
      "ean": "4004833068381",
      "sku": "nike.100.0025",
      "sortOrder": 10,
      "color": "Blue",
      "price": {
        "EUR": 20.99
      },
      "purchasePrice": {
        "EUR": 10.99
      },
      "channels": {
        "shop2": {
          "price": {
            "EUR": 19.99,
            "USD": 19.99
          }
        }
      }
    }
  ]
}

In this example, we are updating the product with the productId "nike.100.0025" and variant with ean "4004833068381", which must exist and has to be unique for all your products.

How to Retrieve Product Information

To retrieve product information from the NextChapter PIM API, you can use a GET request to the endpoint GET /v1/products/{productId}, where {productId} is the unique identifier of the product you want to retrieve.

Follow these steps to successfully retrieve product information:

  1. Authentication: Ensure you have obtained a valid security token (bearer token) to authenticate your requests to the PIM API.

  2. GET Request: Make a GET request to the appropriate PIM API endpoint with the productId of the product you want to retrieve. The PIM API will respond with the product details in JSON format.

Here is an example of how to retrieve product information for a product with the productId "nike.100.0025":

# Retrieve product information
curl -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://pim.api.nextchapter-ecommerce.com/v1/products/nike.100.0025

The response will contain the product details, including attributes such as productId, name, brand, price and more. For example, the output for the product is:

{
  "productId": "nike.100.0025",
  "externalId": "25",
  "name": "New Nike 25",
  "brand": "nike",
  "channels": {
    "shop1": {
      "languages": {
        "en": {
          "specifications": "Lorum ipsum en"
        }
      }
    }
  },
  "variants": [
    {
      "ean": "4004833068381",
      "sku": "nike.100.0025",
      "sortOrder": 1,
      "color": "Blue",
      "price": {
        "EUR": 20.99
      },
      "purchasePrice": {
        "EUR": 10.99
      },
      "channels": {
        "shop2": {
          "price": {
            "EUR": 19.99,
            "USD": 19.99
          }
        }
      }
    }
  ],
  "state": "Valid"
}

How to Retrieve a list of Products with Filters

You can use the NextChapter PIM API to retrieve a list of products based on specific filters and paging parameters. To do this, make a GET request to the endpoint GET /v1/products with the desired query parameters.

Follow these steps to successfully retrieve products with filters:

  1. Authentication: Ensure you have obtained a valid security token (bearer token) to authenticate your requests to the PIM API.

  2. GET Request: Make a GET request to the endpoint GET /v1/products with the desired query parameters. You can include parameters like term, state, skip, take, FromLastModifiedOn, ToLastModifiedOn and channels to filter and paginate the results.

    1. state allows filter for the product stateValid, Invalid, Deleted or Replaced or even by all of them without specifying a value.
    2. channels to filter by channel if it exists. If not so, no filter will be applied. You can set this parameter multiple times if you want to apply the filter for more than one channel.

Here is an example of how to retrieve products with specific filters and pagination:

# Retrieve products with filters
curl -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://pim.api.nextchapter-ecommerce.com/v1/products?term=&state=valid&skip=0&take=50&FromLastModifiedOn=2023-09-18&ToLastModifiedOn=2023-09-19

The response will contain a list of products that match the specified filters and pagination criteria. Each product will be represented as a JSON object.

Here is an example of a response containing product data:

[
    {
        "productId": "nike.100.0025",
        "name": "New Nike 25",
        "brand": "nike",
        "price": {
            "EUR": 20.99
        },
        //...
        "variants": {
          //...
        },
        "state": "Valid"
    },
    {
        "productId": "adidas.200.0030",
        "name": "Adidas Sneakers",
        "brand": "adidas",
        "price": {
            "EUR": 50.99
        },
        // ...
        "variants": {
          //...
        },
        "state": "Valid"
    },
    // ... other product entries
]