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
andToLastModifiedOn
parameters follow the formatYYYY-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
andLastModifiedOn
, the format isYYYY-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
andYYYY-MM-DD
.
- For fields like
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:
-
Authentication: Ensure you have obtained a valid security token (bearer token) to authenticate your requests to the PIM API.
-
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. -
POST Request: Make a POST request to the appropriate PIM API endpoint for creating products. Include your JSON request in the request body.
-
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:
-
Authentication: Ensure you have obtained a valid security token (bearer token) to authenticate your requests to the PIM API.
-
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. -
PATCH Request: Make a PATCH request to the appropriate PIM API endpoint for updating products. Include your JSON request in the request body.
-
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:
-
Authentication: Ensure you have obtained a valid security token (bearer token) to authenticate your requests to the PIM API.
-
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:
-
Authentication: Ensure you have obtained a valid security token (bearer token) to authenticate your requests to the PIM API.
-
GET Request: Make a GET request to the endpoint
GET /v1/products
with the desired query parameters. You can include parameters liketerm
,state
,skip
,take
,FromLastModifiedOn
,ToLastModifiedOn
andchannels
to filter and paginate the results.state
allows filter for the product stateValid
,Invalid
,Deleted
orReplaced
or even by all of them without specifying a value.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
]