Items

Item use cases

Below you will find some common use cases for Items. Before you get started please make sure to read up on the minimum requirements for an Item here and that you have a valid token for your service as described here

Add Item

Add Mandatory Item

A mandatory Item is an Item that should be in assortment for all relevant Business Units. This is the default behavior in Hii Retail. When adding an Item to a Business Unit we explicitly expect the Item to be in assortment. When adding an Item to a Business Unit Group we explicitly set the Item to IN_ASSORTMENT for ALL underlying Business Units.

There is one exception to this and that is when there is a specific Assortment Policy or Item assignment on a Business Unit Group below.

How to

1. Make sure your service has the needed access rights to the API endpoints. This is defined by roles in the IAM management.
   1. To add data you need the Create access verb on the role your service is using.
2. Create the JSON payload as described in the minimum requirements here
   1. The Item must have type set to STOCK
   2. Be sure to set the assortmentType to IN-ASSORTMENT
   3. Make sure to set the correct businessUnitGroupId or businessUnitId for the business unit(s) you want this change to a apply to.
   4. You may also need to add additional information depending on the type of Item and what you want the Item to contain.
   5. For a complete payload, check out the API examples here
3. Construct the needed headers for your integration
   1. A valid token must be provided in the Authorization header as described here
   2. We recommend that you also provide a Correlation-Id header as described here
4. Make sure to provide the correct content type for your payload. It must be application/json
5. Use the POST endpoint for sending your data.
   1. API description can be found here
   2. OpenAPI specification can be found here
6. You will receive a 202 - Accepted response if the message was successful.
7. Please follow the guideline here to create an Additional Item Id (EAN barcode) for this Item
8. Please follow the guideline here to create Price Specifications for the Item

Add Non-Mandatory Item

A non-mandatory Item is an Item that should not be in your active assortment, but be available to include if needed.

A non-mandatory Item can be deemed mandatory in other parts of the organization.

How to

1. Make sure your service has the needed access rights to the API endpoints. This is defined by roles in the IAM management.
   1. To add data you need the Create access verb on the role your service is using.
2. Create the JSON payload as described in the minimum requirements here
   1. The Item must have itemType set to STOCK
   2. Be sure to set the assortmentType to AVAILABLE_ASSORTMENT
   3. Make sure to set the correct businessUnitGroupId or businessUnitId for the business unit(s) you want this change to a apply to.
   4. You may also need to add additional information depending on the type of Item and what you want the Item to contain.
   5. For a complete payload, check out the API examples here
3. Construct the needed headers for your integration
   1. A valid token must be provided in the Authorization header as described here
   2. We recommend that you also provide a Correlation-Id header as described here
4. Make sure to provide the correct content type for your payload. It must be application/json
5. Use the POST endpoint for sending your data.
   1. API description can be found here
   2. OpenAPI specification can be found here
6. You will receive a 202 - Accepted response if the message was successful.
7. Please follow the guideline here to create an Additional Item Id (EAN barcode) for this Item
8. Please follow the guideline here to create Price Specifications for the Item

Replace Item

Updating an existing Item can be done in two ways. Either as a replacement or as an update. A replacement will replace the previous version of the Item with whatever you send to the PUT API endpoint.

This is important since nothing of the previous version of the Item will be preserved.

How to

1. Make sure your service has the needed access rights to the API endpoints. This is defined by roles in the IAM management.
   1. To add data you need the Replace access verb on the role your service is using.
2. Create the complete JSON payload as described in the minimum requirements here
   1. Make sure to set the correct businessUnitGroupId or businessUnitId for the business unit(s) you want this change to a apply to.
   2. You may also need to add additional information depending on the type of Item and what you want the Item to contain.
   3. For a complete payload, check out the API examples here
3. Construct the needed headers for your integration
   1. A valid token must be provided in the Authorization header as described here
   2. We recommend that you also provide a Correlation-Id header as described here
4. Make sure to provide the correct content type for your payload. It must be application/json
5. Use the PUT endpoint for sending your data.
   1. API description can be found here
   2. OpenAPI specification can be found here
6. You will receive a 202 - Accepted response if the message was successful.

Update Item

An update differs from replace since it uses JSON Patch input to modify specific properties on the Item.

This means that the existing Item will remain as it is, except for the provided patches that will be applied to the Item.

How to

1. Make sure your service has the needed access rights to the API endpoints. This is defined by roles in the IAM management.
   1. To add data you need the Update access verb on the role your service is using.
2. Create the JSON Patch payload for the properties you want to modify. JSON Patch format is described here
   1. JSON Patch supports the following operations: Add, Remove, Replace, Move, Copy, Test.
   2. Make sure to set the correct businessUnitGroupId or businessUnitId for the business unit(s) you want this change to a apply to.
   3. For a complete payload, check out the API examples here
3. Construct the needed headers for your integration
   1. A valid token must be provided in the Authorization header as described here
   2. We recommend that you also provide a Correlation-Id header as described here
4. Make sure to provide the correct content type for your payload. It must be application/json
5. Use the PATCH endpoint for sending your data.
   1. API description can be found here
   2. OpenAPI specification can be found here
6. You will receive a 202 - Accepted response if the message was successful.

The JSON Patch payload

A JSON Patch payload allows you to do multiple operations on many properties at once, while keeping the existing content on the Item. You can add and remove properties at the same time as you update others.

Details

[
{ "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 is an Item used to add a reverse vending deposit amount to your sales receipt. Normally you only need one such Item.

How to

1. Make sure your service has the needed access rights to the API endpoints. This is defined by roles in the IAM management.
   1. To add data you need the Create access verb on the role your service is using.
2. Create the JSON payload as described in the minimum requirements here
   1. Make sure the type is set to DEPOSIT
   2. Make sure to set the correct businessUnitGroupId or businessUnitId for the business unit(s) you want this change to a apply to.
   3. Provide an Item Identifier according to the reverse vending machine specifications in the identifiers property
   4. You may also need to add additional information depending on what you want the Item to contain.
   5. For a complete payload, check out the API examples here
3. Construct the needed headers for your integration
   1. A valid token must be provided in the Authorization header as described here
   2. We recommend that you also provide a Correlation-Id header as described here
4. Make sure to provide the correct content type for your payload. It must be application/json
5. Use the POST endpoint for sending your data.
   1. API description can be found here
   2. OpenAPI specification can be found here
6. You will receive a 202 - Accepted response if the message was successful.
7. Please follow the guideline here to create an Additional Item Id (EAN barcode) for reverse vending machines

Move Item into assortment

If an Item is not in assortment for a Business Unit there are a couple of ways to move it into assortment. Below we will cover the most relevant uses cases:

Updating assortment for an individual Item

1. The Item must exist prior to this update
2. Make sure your service has the needed access rights to the API endpoints. This is defined by roles in the IAM management.
   1. To update data you need the Update or the Replace access verb on the role your service is using.
3. If you choose to replace the existing Item, make sure to create the complete payload for the Item as you want it represented in your Business Unit. If you update, follow the description here
   1. Make sure to set the assortmentType to IN-ASSORTMENT
   2. Make sure to set the correct businessUnitGroupId or businessUnitId for the business unit(s) you want this change to a apply to.
   3. For a complete payload, check out the API examples here (PUT) and here (PATCH)
4. Construct the needed headers for your integration
   1. A valid token must be provided in the Authorization header as described here
   2. We recommend that you also provide a Correlation-Id header as described here
5. Make sure to provide the correct content type for your payload. It must be application/json
6. Use the PUT endpoint for replacing your data. Use the PATCH endpoint for individual property updates.
   1. API description can be found here
   2. OpenAPI specification can be found here
7. You will receive a 202 - Accepted response if the message was successful.

Updating assortment for several Items at once

To update several Items and moving them into assortment you should use the Assortment Profile input API. This will change the assortment for multiple Items at once.

1. The Items must exist prior to this update
2. Make sure your service has the needed access rights to the API endpoints. This is defined by roles in the IAM management.
   1. To assign Assortment Policies you need the Create, Update or the Replace access verb on the role your service is using.
3. Create the payload for Assortment Policy. It is important that you include the Items that you want updated to the same assortment in one payload.
   1. Make sure to set the assortmentType to IN-ASSORTMENT
   2. Make sure to set the correct businessUnitGroupId or businessUnitId for the business unit(s) you want this change to a apply to.
   3. For a complete payload, check out the API examples here
4. Construct the needed headers for your integration
   1. A valid token must be provided in the Authorization header as described here
   2. We recommend that you also provide a Correlation-Id header as described here
5. Make sure to provide the correct content type for your payload. It must be application/json
6. API description can be found here
   1. OpenAPI specification can be found here
7. You will receive a 202 - Accepted response if the message was successful.

Set age restriction

How to

1. Decide if you want to update the Item by replacing the existing content or updating one individual property and follow the provided description accordingly.
2. In addition you need to make sure to provide the following details:
   1. The Additional Property called Pos.SalesRestrictionCode must have the code for the age restriction you intend to apply to the Item.

Define replacement Item

A replacement Item is an Item that is intended to take over for an existing Item. This means that if an Item is going out of assortment or is no longer in production, but there is another Item that will take over its place, you would like to automatically find this new Item if a customer asks for it. Likewise you want to find this new item if a customer returns an outdated Item.

Details

1. Make sure the old Item is updated to its correct Status according to your needs.
2. Create the new Item according to the procedure found here.
3. Create an Item Link between the two items:
   1. Make sure your service has the needed access rights to the API endpoints. This is defined by roles in the IAM management.
      1. To create Item Links you need the Create access verb on the role your service is using.
   2. Create the payload for Item Link
      1. Make sure to set the linkType to REPLACEMENT
      2. Make sure to set the correct businessUnitGroupId or businessUnitId for the business unit(s) you want this change to a apply to.
      3. For a complete payload, check out the API examples here
   3. Construct the needed headers for your integration
      1. A valid token must be provided in the Authorization header as described here
      2. We recommend that you also provide a Correlation-Id header as described here
   4. Make sure to provide the correct content type for your payload. It must be application/json
4. Use the CREATE endpoint for Item Links.
   1. API description can be found here
   2. OpenAPI specification can be found here
5. You will receive a 202 - Accepted response if the message was successful.