Skip to main content

Item Use Cases

This guide covers common use cases for managing Items in Hii Retail. Before starting, review the mandatory Item requirements and ensure your service has a valid token as described here.

Add Item​

Add Mandatory Item​

A mandatory Item is included in the assortment for all relevant Business Units by default. Assigning an Item to a Business Unit Group sets it as IN_ASSORTMENT for all underlying Business Units.

Exception: If a specific Assortment Policy or Item assignment exists on a lower-level Business Unit Group, it takes precedence.

How to
  1. Ensure your service has the required API access rights (role with Create verb).
  2. Create the JSON payload as per mandatory requirements:
    • Set type to STOCK
    • Set assortmentType to IN-ASSORTMENT
    • Set the correct businessUnitGroupId or businessUnitId
    • Add any additional required information
    • See API examples
  3. Set headers:
    • Authorization header with a valid token
    • Optional: Correlation-Id header
  4. Set Content-Type to application/json
  5. Use the POST endpoint to send data.
  6. On success, you receive 202 - Accepted.
  7. Create one or more Item Identifiers (GTIN/EAN barcode)
  8. Create Price Specifications

Add Non-Mandatory Item​

A non-mandatory Item is not in the active assortment by default but is available for inclusion.

How to
  1. Ensure your service has the required API access rights (role with Create verb).
  2. Create the JSON payload as per mandatory requirements:
    • Set itemType to STOCK
    • Set assortmentType to AVAILABLE_ASSORTMENT
    • Set the correct businessUnitGroupId or businessUnitId
    • Add any additional required information
    • See API examples
  3. Set headers as above.
  4. Use the POST endpoint.
  5. On success, you receive 202 - Accepted.
  6. Create one or more Item Identifiers (GTIN/EAN barcode)
  7. Create Price Specifications

Replace Item​

Replacing an Item overwrites the previous version. All previous data is replaced.

How to
  1. Ensure your service has the required API access rights (role with Replace verb).
  2. Create the complete JSON payload as per mandatory requirements.
  3. Set headers as above.
  4. Use the PUT endpoint.
  5. On success, you receive 202 - Accepted.

Update Item​

Updating an Item uses JSON Patch to modify specific properties, preserving other data.

How to
  1. Ensure your service has the required API access rights (role with Update verb).
  2. Create a JSON Patch payload for the properties to modify. See JSON Patch format.
  3. Set headers as above.
  4. Use the PATCH endpoint.
  5. On success, you receive 202 - Accepted.

Example JSON Patch payload​

[
  { "op": "replace", "path": "/name", "value": "New Name" },
  { "op": "add", "path": "/additionalProperties/-", "value": {"Code": "G-22", "DataType": "STRING", "Name": "New Additional Property", "UniqueId": "Acme.CustomProperty10", "Value": "G-22" } },
  { "op": "replace", "path": "/additionalProperties/4", "value": {"DataType": "INT", "Name": "Existing Additional Property", "UniqueId": "Acme.CustomProperty4", "Value": "246" } },
  { "op": "remove", "path": "/description" }
]

Create Deposit Item​

A Deposit Item adds a reverse vending deposit amount to the sales receipt. Usually, only one such Item is needed.

How to
  1. Ensure your service has the required API access rights (role with Create verb).
  2. Create the JSON payload as per mandatory requirements:
  3. Set headers as above.
  4. Use the POST endpoint.
  5. On success, you receive 202 - Accepted.
  6. Create a reverse vending Additional Item Id

Move Item into Assortment​

To move an Item into assortment for a Business Unit, update its assortmentType.

Update assortment for an individual Item
  1. The Item must already exist.
  2. Ensure your service has the required API access rights (role with Update or Replace verb).
  3. Replace or update the Item:
  4. Set headers as above.
  5. Use the PUT or PATCH endpoint.
  6. On success, you receive 202 - Accepted.
Update assortment for several Items at once

Use the Assortment Profile input API to update multiple Items.

  1. Items must already exist.
  2. Ensure your service has the required API access rights (role with Create, Update, or Replace verb).
  3. Create the Assortment Policy payload, including all Items to update.
    • Set assortmentType to IN-ASSORTMENT
    • Set the correct businessUnitGroupId or businessUnitId
    • See API examples
  4. Set headers as above.
  5. Use the API endpoint.
  6. On success, you receive 202 - Accepted.

Set Age Restriction​

How to
  1. Replace or update the Item as needed.
  2. Add the Additional Property Pos.SalesRestrictionCode with the appropriate age restriction code.

Define Replacement Item​

A replacement Item takes over for an existing Item (e.g., when an Item is discontinued).

How to
  1. Update the old Item's Status as needed.
  2. Create the new Item as described above.
  3. Create an Item Link between the two Items:
    • Ensure your service has the required API access rights (role with Create verb).
    • Create the Item Link payload:
      • Set linkType to REPLACEMENT
      • Set the correct businessUnitGroupId or businessUnitId
      • See API examples
    • Set headers as above.
    • Use the CREATE endpoint.
    • On success, you receive 202 - Accepted.
  • API description can be found here
  • OpenAPI specification can be found here