Create Product Groups and Products Recipe
š Purpose
Product groups define the hierarchy your products sit in, and products are the individual items that campaigns and offers can target. This recipe sets up a small product hierarchy via API rather than file ingestion. You will create a group, add products to it in bulk, and then add a single product. This is useful when only a small number of products change between full catalog loads, or when you need to add products quickly without waiting for a file to be processed.
For more options, see the Create an Inventory Group, Bulk create Inventory Products and Create an Inventory Product API references.
š¼ Recipe Overview
After completing this recipe you will have:
- Multi-level product group hierarchy, ready to hold products.
- Multiple products created in a single bulk call and assigned to a group.
- One additional product created individually in the same group.
Products must always reference a group that already exists, which is why the group is created first. Once the setup is complete, the products and group can be used for product and group qualification in campaigns.
If you also load products using file ingestion, be aware that a full ingestion replaces products ingested previously and will overwrite changes made via these API calls. Decide which approach is the source of truth for the unit.
š Prerequisites
- API credentials
- The
incomingIdentifierof the company (banner) unit whose products and groups you are managing. This is used in the path of every API request. - A group
id,nameandtypedecided for your first group. - Your product IDs (e.g UPC or SKU), names and the
idof the group each product belongs to. - No more than 100 products per bulk request.
š¤ Outputs
| Output Name | Purpose |
|---|---|
incomingIdentifier | Identifies the company (banner) unit whose products and groups you are managing. Used in the path of every API request. |
Parent group id | Used as the parentId when you create child groups beneath it. |
Child group id | Used as the groupId on every product you create in that group, and to retrieve or delete the group later. |
Group level, parentId, hasChildren | System-generated values describing where each group sits in the hierarchy. Use them to confirm the hierarchy was created as intended. |
Product id | Identifies each product created. Used to retrieve, update or delete the product. |
successful and failed blocks (bulk) | Show which products were created and which were rejected, with an errorCode and errorMessage for each failure. |
š Steps
Step 1: Define the top-level group
1.1 Choose a unique id for the group, for example dept1. You will use this value as parentId when you create child groups, and it cannot be changed after the group is created.
1.2 Set name to the display name of the group, for example Produce Dept.
1.3 Set type to a label that classifies the group, for example department. type is required. If it is missing, blank or null the request is rejected.
1.4 Optionally set description to explain what the group contains.
1.5 Set parentId to null. This makes the group a top-level group with no parent.
1.6 Include incomingIdentifier in the request path.
Step 2: Call POST /products/{incomingIdentifier}/groups
{
"id": "dept1",
"name": "Produce Dept",
"type": "department",
"description": "All produce products"
}{
"id": "dept1",
"name": "Produce Dept",
"type": "department",
"description": "All produce products",
"parentId": null,
"level": 1,
"hasChildren": false,
"parent": null
}The response includes system-generated values for level and hasChildren.
Step 3: Define the child group
3.1 Choose a unique id for the child group, for example fresh-fruit. You will use this value as groupId when you create products.
3.2 Set name to Fresh Fruit.
3.3 Set type to a label that classifies this group, for example category. This can differ from the type of the parent group.
3.4 Set parentId to the group id from Step 2 (dept1). The parent group must already exist. This nests Fresh Fruit beneath Produce Dept.
3.5 Optionally set description to explain what the group contains.
Step 4: Call POST /products/{incomingIdentifier}/groups
{
"id": "fresh-fruit",
"name": "Fresh Fruit",
"type": "category",
"description": "All fresh fruit products",
"parentId": "dept1"
}{
"id": "fresh-fruit",
"name": "Fresh Fruit",
"type": "category",
"description": "All fresh fruit products",
"parentId": "dept1",
"level": 2,
"hasChildren": false,
"parent": {
"id": "dept1",
"name": "Produce Dept",
"type": "department",
"description": "All produce products",
"parentId": null,
"level": 1,
"hasChildren": true,
"parent": null
}
}In the response, confirm that parentId is dept1 and that level is one deeper than the parent group.
Step 5: Define the bulk products
5.1 Add one object to the request array for each product. Each object needs an id and a groupId. Set groupId to the child group id from Step 4 (fresh-fruit).
5.2 Set name for every product. It is optional in the schema, but a product without a name is hard to identify later.
5.3 Add any optional fields you have: description, imageUrl, supplierId, supplierName, brand, brandType, lastSoldDate and tags.
- If you set
imageUrl, it must be a valid HTTP URL. If you setlastSoldDate, it must be in ISO 8601 / ATOM format, for example2026-10-01T09:30:00+00:00. Usenullfor either field if you have no value.
5.4 Send a maximum of 100 products per request. For larger loads, split the products across several requests.
Step 6: Call POST /products/{incomingIdentifier}/bulk
[
{
"id": "4135",
"groupId": "fresh-fruit",
"name": "Gala Apples",
"tags": [
"fruit",
"seasonal"
]
},
{
"id": "4011",
"groupId": "fresh-fruit",
"name": "Bananas",
"tags": [
"fruit"
]
},
{
"id": "3017",
"groupId": "fresh-fruit",
"name": "Conference Pears",
"tags": [
"fruit",
"seasonal"
]
}
]{
"successful": {
"total": 3,
"results": [
{
"id": "4135",
"groupId": "fresh-fruit",
"brand": "",
"brandType": "",
"description": "",
"name": "Gala Apples",
"supplierId": "",
"supplierName": "",
"tags": [
"fruit",
"seasonal"
],
"imageUrl": null,
"group": null,
"lastSoldDate": null
},
{
"id": "4011",
"groupId": "fresh-fruit",
"brand": "",
"brandType": "",
"description": "",
"name": "Bananas",
"supplierId": "",
"supplierName": "",
"tags": [
"fruit"
],
"imageUrl": null,
"group": null,
"lastSoldDate": null
},
{
"id": "3017",
"groupId": "fresh-fruit",
"brand": "",
"brandType": "",
"description": "",
"name": "Conference Pears",
"supplierId": "",
"supplierName": "",
"tags": [
"fruit",
"seasonal"
],
"imageUrl": null,
"group": null,
"lastSoldDate": null
}
]
},
"failed": {
"total": 0,
"results": []
}
}The response always contains a successful block and a failed block. The status code tells you the overall outcome:
201: all products were created.207: some products were created and some failed. Checkfailed.resultsfor theid,errorCodeanderrorMessageof each rejected product.400: every product failed, or the payload did not pass schema validation.
Step 7: Define the single product
7.1 Set id to a product ID that does not already exist for this unit.
7.2 Set groupId to the child group id from Step 4 (fresh-fruit). The group must already exist.
7.3 Set name and any optional fields as described in Step 5.
Step 8: Call POST /products/{incomingIdentifier}
{
"id": "4028",
"groupId": "fresh-fruit",
"name": "Strawberries Pint Container",
"tags": [
"fruit",
"summer"
]
}{
"id": "4028",
"groupId": "fresh-fruit",
"brand": "",
"brandType": "",
"description": "",
"name": "Strawberries Pint Container",
"supplierId": "",
"supplierName": "",
"tags": [
"fruit",
"summer"
],
"imageUrl": null,
"group": null,
"lastSoldDate": null
}ā
Business Readiness Checklist
-
Retrieve the groups you created in Steps 2 and 4 and confirm
id,nameandtypematch your requests. See Create an Inventory Group for the group fields. -
Confirm
dept1hasparentIdofnullandhasChildrenoftrue. -
Confirm
fresh-fruithasparentIdofdept1and sits onelevelbelow its parent. -
Confirm the Step 6 response status. If it was
207, review every entry infailed.resultsand re-submit the failed products once the cause is fixed. See Bulk create Inventory Products. -
Confirm
successful.totalin the Step 6 response matches the number of products you sent. -
Confirm every product returns
groupIdoffresh-fruit, and thattagscontain the values you intend to use for campaign qualification. -
Confirm the single product from Step 8 was created with the expected values. See Create an Inventory Product.
š§ Troubleshooting Tips
| Issue | Possible Cause & Resolution |
|---|---|
400 Bad Request when creating a group | id, name or type is missing, blank or null. All three are required. Add the missing value and resend. |
| Child group creation fails because the parent cannot be found | The parentId does not match an existing group. Create the parent first (Step 2) and check the parentId spelling. |
409 Conflict when creating a group or product | A group or product with that id already exists for this unit. Use a different id. |
Bulk response is 207 with GNF (Group Not Found) | The groupId on that product does not match an existing group. Create the group first (Step 4) and check the groupId spelling. |
Bulk response has IPC (Product already exists) | A product with that id already exists for this unit. Use a different id, or use the update endpoint to change the existing product. |
| Bulk request rejected for size | More than 100 products were sent. Split the list into batches of 100 or fewer. |
401 Unauthorized | Check X-EES-AUTH-CLIENT-ID and the X-EES-AUTH-HASH calculation. The hash is built from the full request path, the payload and your client secret. |
404 Not Found on any call | The incomingIdentifier in the path does not match a unit you manage. Confirm the value and that the URL uses /products/{incomingIdentifier}/groups for groups and /products/{incomingIdentifier}/bulk for bulk products. |
| Products or groups you created via API disappear after a file ingestion | A full ingestion replaces previously ingested products and overwrites API changes. Choose one approach per unit, or re-apply API changes after each ingestion. |
Updated about 4 hours ago

