Additional item ids

Item Identifier (Additional Item Id) use cases

Item Identifiers are usually EAN or GTIN barcodes, but 2D barcodes are becoming more popular in most retail areas. According to GS1, they will have taken over as the primary barcode within the next 5 years (2021).

In Hii Retail we support multiple Item Identifier types to accommodate different needs in different retail domains.

Below we will list some common use case scenarios describing how to maintain your Item Identifiers of different types.

Hii Retail processing will validate inputs of any GTIN type. This means that we will verify that the GTIN:

• has the correct length (GTIN13 must have 13 digits, GTIN8 must have 8 digits, etc.)
• has a valid check-digit according to the provided content
• validate that the GTIN-value is not already in use on a different Item (5017726180034 must be associated with the same item across your entire tenant)
  • A Global Trade Identification Number is assigned to a specific Item and can not be used for anything else. We do not validate that the GTIN is used on the correct Item, but we validate that it is only used on a single Item.

Variable measure GTIN ranges are not checked for duplicates. (GTINs with prefixes 02, 20-29)

A duplicate input will be logged, but the data will be ignored for further processing in Hii Retail. A Customer Notification event will be sent when this happens, and we recommend all tenants to subscribe to these events. See more about this in the External Events service

Create GTIN or EAN

A GTIN or EAN barcode is mainly used for scanning Items in a POS or mobile application with scanner. A GTIN can be of different lengths where 13 digits is the most common (and also the default in Hii Retail).

How to create a new GTIN

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 AdditionalItemIdType is set to GTIN8, GTIN12, GTIN13 or GTIN14.
   2. Make sure to provide the correct Value according to AdditionalItemIdType for the Item you want to associate this GTIN/EAN with.
      1. You may use the same content in Id as in Value for GTINs/EANs, but it is not required.
      2. If you have a GTIN that is shorter than the specified GTIN-type, you need to apply the correct number of leading zeros or choose another GTIN-type that matches your GTIN length.
   3. Make sure to set the correct BusinessUnitGroupId for the business unit(s) you want this change to a apply to.
   4. Provide the ItemId to link the GTIN/EAN to the Item.
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.

Example GTIN-13/EAN code: 5017726180034

Create reverse vending GTIN or EAN

A reverse vending EAN or GTIN is usually a normal GTIN-13, linear barcode that most scanners can read. If your country or reverse vending machine supplier has any specific requirements beyond this description, you must always follow regulations in your country.

How to create a reverse vending identifier

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 AdditionalItemIdType is set to GTIN13 or what the reverse vending machine supplier requires.
   2. Provide the correct Value according to the reverse vending machine provider
   3. Make sure to set the correct BusinessUnitGroupId for the business unit(s) you want this change to a apply to.
   4. Make sure to use the correct ItemId for the Deposit Item you want this GTIN/EAN to be associated with.
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.

Example GTIN-13/EAN code: 9802235003500

    980 2235 00350 0

    980   -> the ID or prefix identifying that this is a reverse vending barcode
    2235  -> deposit receipt ID
    00350 -> deposit price or the deposit amount that will be returned
    0     -> check digit

2D identifiers

2D identifiers can be of several different types. In Hii Retail we support DataMatrix and QR codes.

DataMatrix identifier

DataMatrix 2D barcodes are two dimensional barcodes that can hold a large amount of information. DataMatrix comes in 2 flavours, ECC140 and ECC220. More info here

How to create a DataMatrix identifier

Creating a ECC220 identifier

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 AdditionalItemIdType is set to ECC220
   2. Provide the correct Value according to the content you need in the DataMatrix.
   3. Make sure to set the correct BusinessUnitGroupId for the business unit(s) you want this change to a apply to.
   4. Make sure to use the correct ItemId for the Item you want this DataMatrix code to be associated with.
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.

Creating a ECC140 identifier

This version is considered outdated and the ECC220 should be preferred. The same procedure as for ECC200 applies except for the AdditionalItemType should be ECC140, however this type has some length restrictions.

QR code identifier

QR Codes can be used for many useful purposes. It might be used in promotional or other marketing material to provide a link to your website, or it might be used as a normal 2D barcode for identification purposes.

QR Codes can hold a lot of information and be useful in a number of scenarios. Please read more here. GS1 recommendations for QR Codes can be found here.

How to create a QR identifier

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 AdditionalItemIdType is set to QR
   2. Provide the correct Value according to the content you need in the QR Code.
   3. Make sure to set the correct BusinessUnitGroupId for the business unit(s) you want this change to a apply to.
   4. Make sure to use the correct ItemId for the Item you want this DataMatrix code to be associated with.
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.