Create a Product Item Group

The request body is a single product item group object, not an array. identifier and name are required; description is optional and is stored as an empty string when omitted.

curl -X POST "https://connect.wholechain.com/Integration/ItemGroup" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: example_string" \
  -H "accept: */*" \
  -d '{
  "identifier": "ITEMGROUP-001",
  "name": "Atlantic Salmon",
  "description": "Farmed Atlantic salmon"
}'

import requests
import json

url = "https://connect.wholechain.com/Integration/ItemGroup"
headers = {
  "Content-Type": "application/json",
  "X-API-KEY": "example_string",
  "accept": "*/*"
}
data = {
  "identifier": "ITEMGROUP-001",
  "name": "Atlantic Salmon",
  "description": "Farmed Atlantic salmon"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch("https://connect.wholechain.com/Integration/ItemGroup", {
  method: "POST",
  headers: {
  "Content-Type": "application/json",
  "X-API-KEY": "example_string",
  "accept": "*/*"
},
  body: JSON.stringify({
  "identifier": "ITEMGROUP-001",
  "name": "Atlantic Salmon",
  "description": "Farmed Atlantic salmon"
})
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
    "bytes"
    "encoding/json"
)

func main() {
    data := []byte(`{
  "identifier": "ITEMGROUP-001",
  "name": "Atlantic Salmon",
  "description": "Farmed Atlantic salmon"
}`)

    req, err := http.NewRequest("POST", "https://connect.wholechain.com/Integration/ItemGroup", bytes.NewBuffer(data))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-KEY", "example_string")
    req.Header.Set("accept", "*/*")

    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/ItemGroup')
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['accept'] = '*/*'
request.body = '{
  "identifier": "ITEMGROUP-001",
  "name": "Atlantic Salmon",
  "description": "Farmed Atlantic salmon"
}'

response = http.request(request)
puts response.body

{
  "identifier": "ITEMGROUP-001",
  "name": "Atlantic Salmon",
  "description": "Farmed Atlantic salmon"
}

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "X-API-KEY": [
      "The apiKey field is required."
    ]
  },
  "traceId": "…"
}

POST

/Integration/ItemGroup

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

Your Wholechain API key.

header

acceptstring

Response content type.

Options: */*

identifierstring

Required

Required. Your identifier for the product item group. Must not already be used by another product item group.

namestring

Required

Required. Name of the product item group.

descriptionstring

Optional. Description of the product item group. Stored as an empty string when omitted.

Request Preview

Response

Response will appear here after sending the request

Responses

Introduction

This API creates a product item group in Wholechain.

A product item group organizes products by a business category you choose, such as a commodity. In the Wholechain app, item groups are managed as Trade Item Groups, and a product's group is shown as Commodity.

A product references an item group through the productItemGroup object in the product Details. See Create a Product and Update a Product.

To manage item groups in the Wholechain app, see Trade Item Groups.

Endpoint

Method	URL
`POST`	`https://connect.wholechain.com/Integration/ItemGroup`

Request Headers

Header	Description	Example Value
`X-API-KEY`	Your Wholechain API key.	`<YOUR_API_KEY>`
`Content-Type`	Content type of the request. `application/json` and `application/xml` are accepted.	`application/json`
`accept`	Response content type.	`/`

Request Body

The request body is a single product item group object.

Column Name	Data Type	Description	Required
`identifier`	STRING	Your identifier for the product item group. Must not already be used by another product item group.	Yes
`name`	STRING	Name of the product item group.	Yes
`description`	STRING	Description of the product item group. If omitted, it is stored as an empty string.	No

Example Request

{
  "identifier": "ITEMGROUP-001",
  "name": "Atlantic Salmon",
  "description": "Farmed Atlantic salmon"
}

cURL

curl -X 'POST' \
  'https://connect.wholechain.com/Integration/ItemGroup' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -d '{
    "identifier": "ITEMGROUP-001",
    "name": "Atlantic Salmon",
    "description": "Farmed Atlantic salmon"
  }'

Responses

201 — Created

The product item group is created. The response body is a product item group object with the same fields as the request: identifier, name, and description.

{
  "identifier": "ITEMGROUP-001",
  "name": "Atlantic Salmon",
  "description": "Farmed Atlantic salmon"
}

409 — Conflict

A product item group with the same identifier already exists.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "Product commodity external identifier already exists: ITEMGROUP-001",
  "status": 409,
  "traceId": "<trace-id>"
}

422 — Unprocessable Entity

identifier or name is missing. The title is Identifier is required. or Name is required.

{
  "type": "https://tools.ietf.org/html/rfc4918#section-11.2",
  "title": "Name is required.",
  "status": 422,
  "traceId": "<trace-id>"
}

400 — Bad Request

The X-API-KEY header is missing, or the request body is not valid JSON.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "X-API-KEY": [
      "The apiKey field is required."
    ]
  },
  "traceId": "<trace-id>"
}

Important Notes

The request body is a single object, not an array. Create one product item group per request.
identifier and name are required. description is optional.
A product item group is also created automatically when a product references a new identifier in its productItemGroup object. See Create a Product.
To change an existing product item group, see Update a Product Item Group. To remove one, see Delete a Product Item Group.
In the Update a Product response, the item group assigned to a product is returned as productCommodity (with id, name, description, and externalIdentifier).

Was this page helpful?