ProductsCreate a Product

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"
          }
        ]
      }
    }
  ]
}'
{
  "message": "Success",
  "result": [
    {
      "id": "01a0d830-e993-75f9-9b4b-551c2b35950c",
      "status": "Created"
    }
  ],
  "errors": [],
  "validations": []
}
POST
/Integration/Products
POST
Base URLstring

Target server for requests. Edit to use your own host.

Content-Typestring
Required

The media type of the request body

Options: application/json
header
X-API-KEYstring
Required

API key used to authenticate the request.

Request Preview
Response

Response will appear here after sending the request

Responses

messagestring
Required
resultarray
Required
errorsobject[]
Required
validationsobject[]
Required

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

HeaderRequiredDescriptionExample
X-API-KEYYesAPI key used to authenticate the request.743e286e-c578-461d-afc6-bd82efe4e6bb
Content-TypeYesFormat of the request body.application/json
AcceptNoRequested response format.*/*

Request Body

The request contains a Products array.

Multiple products can be submitted in the same request.

Product Fields

FieldTypeRequiredDescriptionExample
Products[].IdStringYesUnique identifier for the product. This value is referenced in subsequent supply-chain events.12345
Products[].Details.NameStringYesHuman-readable name of the product.Sample Product
Products[].Details.SimpleUnitOfMeasurementStringYesUnit of measurement used to represent the product.Kgm
Products[].Details.UnitQuantityDecimalNoQuantity of the simple unit of measurement contained in each commercial or packaging unit.2
Products[].Details.UnitDescriptorStringNoDescribes the commercial or packaging unit.Cases
Products[].Details.SharingPolicyStringYesDetermines how the product is shared within Wholechain.Open
Products[].Details.ProductIdentifierTypeStringYesDetermines how product instances are identified.Lot
Products[].Details.GtinStringNoGlobal Trade Item Number associated with the product.12345678912343
Products[].Details.PluStringNoPrice Lookup Code associated with the product.4001
Products[].Details.MasterDataArrayNoCustom product data that can be stored against the product as name/value pairs.See Product Custom Data section
Products[].Details.MasterData[].nameStringYes*Name of the custom product field.Gear Type
Products[].Details.MasterData[].namespaceStringYes*Namespace used to identify the custom data field. For custom product data, use custom.custom
Products[].Details.MasterData[].valueStringYes*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:

ValueDescription
OpenWhen shipping a product to a customer, the customer will see all events linked to that lot.
RestrictedWhen 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:

ValueDescription
LotProduct instances are identified using lot or batch numbers.
SerialProduct 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 — use custom for 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

  • Id must uniquely identify the product within the relevant Wholechain account.
  • The same product Id should 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.
  • SimpleUnitOfMeasurement defines 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.
  • UnitQuantity and UnitDescriptor can be used when additional packaging or commercial-unit information is required.
  • UnitDescriptor supports Cases, Units, Totes, and Pallets.
  • UnitDescriptor does not replace SimpleUnitOfMeasurement.
  • For example, Kgm alone represents a product measured in kilograms, while Kgm + UnitQuantity: 2 + UnitDescriptor: "Cases" represents a 2 kg case product.
  • MasterData can be used to add custom product-specific information.
  • Each MasterData entry should contain a name, namespace, and value.
  • Use custom as the namespace for custom product data.
  • Multiple custom fields can be submitted within the same MasterData array.
  • Optional fields such as Gtin, Plu, UnitQuantity, UnitDescriptor, and MasterData should 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.