Create a Product
curl -X POST "https://connect.wholechain.com/Integration/Products" \
-H "Content-Type: application/json" \
-H "X-API-KEY: example_string" \
-d '{
"Products": [
{
"Id": "12345",
"Details": {
"Name": "Sample Product",
"SimpleUnitOfMeasurement": "Kgm",
"UnitQuantity": 2,
"UnitDescriptor": "Cases",
"SharingPolicy": "Open",
"ProductIdentifierType": "Lot",
"Gtin": "12345678912343",
"Plu": "4001",
"MasterData": [
{
"name": "Gear Type",
"namespace": "custom",
"value": "TRAWL"
}
]
}
}
]
}'
import requests
import json
url = "https://connect.wholechain.com/Integration/Products"
headers = {
"Content-Type": "application/json",
"X-API-KEY": "example_string"
}
data = {
"Products": [
{
"Id": "12345",
"Details": {
"Name": "Sample Product",
"SimpleUnitOfMeasurement": "Kgm",
"UnitQuantity": 2,
"UnitDescriptor": "Cases",
"SharingPolicy": "Open",
"ProductIdentifierType": "Lot",
"Gtin": "12345678912343",
"Plu": "4001",
"MasterData": [
{
"name": "Gear Type",
"namespace": "custom",
"value": "TRAWL"
}
]
}
}
]
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
const response = await fetch("https://connect.wholechain.com/Integration/Products", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "example_string"
},
body: JSON.stringify({
"Products": [
{
"Id": "12345",
"Details": {
"Name": "Sample Product",
"SimpleUnitOfMeasurement": "Kgm",
"UnitQuantity": 2,
"UnitDescriptor": "Cases",
"SharingPolicy": "Open",
"ProductIdentifierType": "Lot",
"Gtin": "12345678912343",
"Plu": "4001",
"MasterData": [
{
"name": "Gear Type",
"namespace": "custom",
"value": "TRAWL"
}
]
}
}
]
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"bytes"
"encoding/json"
)
func main() {
data := []byte(`{
"Products": [
{
"Id": "12345",
"Details": {
"Name": "Sample Product",
"SimpleUnitOfMeasurement": "Kgm",
"UnitQuantity": 2,
"UnitDescriptor": "Cases",
"SharingPolicy": "Open",
"ProductIdentifierType": "Lot",
"Gtin": "12345678912343",
"Plu": "4001",
"MasterData": [
{
"name": "Gear Type",
"namespace": "custom",
"value": "TRAWL"
}
]
}
}
]
}`)
req, err := http.NewRequest("POST", "https://connect.wholechain.com/Integration/Products", bytes.NewBuffer(data))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-KEY", "example_string")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
require 'net/http'
require 'json'
uri = URI('https://connect.wholechain.com/Integration/Products')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['X-API-KEY'] = 'example_string'
request.body = '{
"Products": [
{
"Id": "12345",
"Details": {
"Name": "Sample Product",
"SimpleUnitOfMeasurement": "Kgm",
"UnitQuantity": 2,
"UnitDescriptor": "Cases",
"SharingPolicy": "Open",
"ProductIdentifierType": "Lot",
"Gtin": "12345678912343",
"Plu": "4001",
"MasterData": [
{
"name": "Gear Type",
"namespace": "custom",
"value": "TRAWL"
}
]
}
}
]
}'
response = http.request(request)
puts response.body
{
"message": "Success",
"result": [
{
"id": "01a0d830-e993-75f9-9b4b-551c2b35950c",
"status": "Created"
}
],
"errors": [],
"validations": []
}
{
"message": "Success",
"result": [
{
"id": "019bde0b-d8fd-7f70-9f11-7e8ba3576e7d",
"status": "Skipped"
}
],
"errors": [],
"validations": []
}
/Integration/Products
Target server for requests. Edit to use your own host.
The media type of the request body
API key used to authenticate the request.
Request Preview
Response
Response will appear here after sending the request
Responses
Overview
The Product Creation API is used to create products in Wholechain.
Products contain the master data required to identify and track an item through supply-chain events such as Commission, Receive, Ship, and Transform.
A product only needs to be created once. After creation, its Id can be referenced in subsequent event payloads.
If you would like to update an existing product, see Update a Product documentation.
Request Headers
| Header | Required | Description | Example |
|---|---|---|---|
X-API-KEY | Yes | API key used to authenticate the request. | 743e286e-c578-461d-afc6-bd82efe4e6bb |
Content-Type | Yes | Format of the request body. | application/json |
Accept | No | Requested response format. | */* |
Request Body
The request contains a Products array.
Multiple products can be submitted in the same request.
Product Fields
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
Products[].Id | String | Yes | Unique identifier for the product. This value is referenced in subsequent supply-chain events. | 12345 |
Products[].Details.Name | String | Yes | Human-readable name of the product. | Sample Product |
Products[].Details.SimpleUnitOfMeasurement | String | Yes | Unit of measurement used to represent the product. | Kgm |
Products[].Details.UnitQuantity | Decimal | No | Quantity of the simple unit of measurement contained in each commercial or packaging unit. | 2 |
Products[].Details.UnitDescriptor | String | No | Describes the commercial or packaging unit. | Cases |
Products[].Details.SharingPolicy | String | Yes | Determines how the product is shared within Wholechain. | Open |
Products[].Details.ProductIdentifierType | String | Yes | Determines how product instances are identified. | Lot |
Products[].Details.Gtin | String | No | Global Trade Item Number associated with the product. | 12345678912343 |
Products[].Details.Plu | String | No | Price Lookup Code associated with the product. | 4001 |
Products[].Details.MasterData | Array | No | Custom product data that can be stored against the product as name/value pairs. | See Product Custom Data section |
Products[].Details.MasterData[].name | String | Yes* | Name of the custom product field. | Gear Type |
Products[].Details.MasterData[].namespace | String | Yes* | Namespace used to identify the custom data field. For custom product data, use custom. | custom |
Products[].Details.MasterData[].value | String | Yes* | Value associated with the custom product field. | TRAWL |
* Required when a MasterData entry is provided for Custom Data.
Optional properties should be omitted from the request when they are not being used rather than submitted as empty values.
For detailed information on how to configure the unit of measure for your product, please view the Unit of Measurement documentation.
Sharing Policy
The following values can be used for SharingPolicy:
| Value | Description |
|---|---|
Open | When shipping a product to a customer, the customer will see all events linked to that lot. |
Restricted | When shipping a product to a customer, the customer will only see the ship event linked to that product. |
Product Identifier Type
The following values can be used for ProductIdentifierType:
| Value | Description |
|---|---|
Lot | Product instances are identified using lot or batch numbers. |
Serial | Product instances are identified using serial numbers. Each serial is one item; any Quantity sent in an event is recorded as 1. |
Example Using Only a Simple Unit of Measurement
If packaging-level information is not required, the product can simply be registered using its unit of measurement.
{
"Products": [
{
"Id": "12345",
"Details": {
"Name": "Sample Product",
"SimpleUnitOfMeasurement": "Kgm",
"SharingPolicy": "Open",
"ProductIdentifierType": "Lot"
}
}
]
}
In this example, the product is tracked directly in kilograms.
Example With Packaging Detail
If the product needs to be represented as a packaged commercial unit, UnitQuantity and UnitDescriptor can be provided.
{
"Products": [
{
"Id": "12345",
"Details": {
"Name": "Sample Product",
"SimpleUnitOfMeasurement": "Kgm",
"UnitQuantity": 2,
"UnitDescriptor": "Cases",
"SharingPolicy": "Open",
"ProductIdentifierType": "Lot"
}
}
]
}
This defines the product as:
1 Case = 2 kg
Product Custom Data
Custom product information can be added using the MasterData array within the product Details.
This allows additional product-specific data to be stored when the information is not represented by one of the standard product fields.
Each custom data entry contains:
name— the name of the custom field.namespace— usecustomfor custom product data.value— the value associated with the field.
Example
The following example adds Gear Type as custom product data:
{
"Products": [
{
"Id": "12345",
"Details": {
"Name": "Sample Product",
"SimpleUnitOfMeasurement": "Kgm",
"SharingPolicy": "Open",
"ProductIdentifierType": "Lot",
"MasterData": [
{
"name": "Gear Type",
"namespace": "custom",
"value": "TRAWL"
}
]
}
}
]
}
Multiple Custom Data Fields
Multiple custom fields can be added to the same product by adding additional objects to the MasterData array.
{
"Products": [
{
"Id": "12345",
"Details": {
"Name": "Sample Product",
"SimpleUnitOfMeasurement": "Kgm",
"SharingPolicy": "Open",
"ProductIdentifierType": "Lot",
"MasterData": [
{
"name": "Gear Type",
"namespace": "custom",
"value": "TRAWL"
},
{
"name": "Species",
"namespace": "custom",
"value": "Atlantic Salmon"
},
{
"name": "Country of Origin",
"namespace": "custom",
"value": "Norway"
}
]
}
}
]
}
Custom data should only be used for additional product information that is not already represented by a standard Wholechain product field.
Full Example With Product Custom Data
The following example creates a 10.5 kg case product with standard product identifiers and custom product data.
{
"Products": [
{
"Id": "product_id",
"Details": {
"ProductIdentifierType": "Lot",
"Name": "Sample Product",
"SimpleUnitOfMeasurement": "Kgm",
"SharingPolicy": "Open",
"UnitDescriptor": "Cases",
"UnitQuantity": 10.5,
"Gtin": "12345678912343",
"Plu": "4001",
"MasterData": [
{
"name": "Gear Type",
"namespace": "custom",
"value": "GEAR TYPE_VALUE"
}
]
}
}
]
}
Optional Product Identifiers
GTIN
Gtin can be provided when the product has a Global Trade Item Number.
Example:
{
"Gtin": "12345678912343"
}
If the product does not have a GTIN, omit the property entirely.
PLU
Plu can be provided when the product has a Price Lookup Code.
Example:
{
"Plu": "4001"
}
If the product does not have a PLU, omit the property entirely.
Important Notes
Idmust uniquely identify the product within the relevant Wholechain account.- The same product
Idshould be used when referencing the product in subsequent event payloads. - Do not create multiple product IDs for the same product unless they represent genuinely different products.
SimpleUnitOfMeasurementdefines the measurement or unit used for the product.- Standard Wholechain UOM values should be used where possible, although supported aliases can also be interpreted by the API.
UnitQuantityandUnitDescriptorcan be used when additional packaging or commercial-unit information is required.UnitDescriptorsupportsCases,Units,Totes, andPallets.UnitDescriptordoes not replaceSimpleUnitOfMeasurement.- For example,
Kgmalone represents a product measured in kilograms, whileKgm+UnitQuantity: 2+UnitDescriptor: "Cases"represents a 2 kg case product. MasterDatacan be used to add custom product-specific information.- Each
MasterDataentry should contain aname,namespace, andvalue. - Use
customas thenamespacefor custom product data. - Multiple custom fields can be submitted within the same
MasterDataarray. - Optional fields such as
Gtin,Plu,UnitQuantity,UnitDescriptor, andMasterDatashould be omitted when they are not applicable. - Ensure that the product configuration is consistent with how quantities will be submitted in subsequent supply-chain events.