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 incomingIdentifier of the company (banner) unit whose products and groups you are managing. This is used in the path of every API request.
  • A group id, name and type decided for your first group.
  • Your product IDs (e.g UPC or SKU), names and the id of the group each product belongs to.
  • No more than 100 products per bulk request.

šŸ“¤ Outputs

Output NamePurpose
incomingIdentifierIdentifies the company (banner) unit whose products and groups you are managing. Used in the path of every API request.
Parent group idUsed as the parentId when you create child groups beneath it.
Child group idUsed as the groupId on every product you create in that group, and to retrieve or delete the group later.
Group level, parentId, hasChildrenSystem-generated values describing where each group sits in the hierarchy. Use them to confirm the hierarchy was created as intended.
Product idIdentifies 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.

{
  "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.

{
  "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 set lastSoldDate, it must be in ISO 8601 / ATOM format, for example 2026-10-01T09:30:00+00:00. Use null for 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.

[
    {
        "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. Check failed.results for the id, errorCode and errorMessage of 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.

{
    "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, name and type match your requests. See Create an Inventory Group for the group fields.

  • Confirm dept1 has parentId of null and hasChildren of true.

  • Confirm fresh-fruit has parentId of dept1 and sits one level below its parent.

  • Confirm the Step 6 response status. If it was 207, review every entry in failed.results and re-submit the failed products once the cause is fixed. See Bulk create Inventory Products.

  • Confirm successful.total in the Step 6 response matches the number of products you sent.

  • Confirm every product returns groupId of fresh-fruit, and that tags contain 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

IssuePossible Cause & Resolution
400 Bad Request when creating a groupid, 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 foundThe 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 productA 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 sizeMore than 100 products were sent. Split the list into batches of 100 or fewer.
401 UnauthorizedCheck 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 callThe 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 ingestionA full ingestion replaces previously ingested products and overwrites API changes. Choose one approach per unit, or re-apply API changes after each ingestion.

Did this page help you?