Skip to main content

Item Identifiers

Item Identifier (Additional Item Id) Use Cases

Item Identifiers are usually EAN or GTIN barcodes, but 2D barcodes are becoming more common. Hii Retail supports multiple identifier types for different retail needs.

Below are common use cases for managing Item Identifiers.

Hii Retail validates all GTIN types:

  • Correct length (GTIN13 = 13 digits, etc.)
  • Valid check digit
  • Uniqueness within your tenant (a GTIN can only be used for one Item)

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

Duplicate GTINs are logged and ignored. A Customer Notification event is sent. Subscribe to the External Events service for alerts.

Create GTIN or EAN​

GTIN/EAN barcodes are used for scanning Items in POS or mobile apps. GTINs can be 8, 12, 13, or 14 digits.

How to create a new GTIN
  1. Ensure your service has the required API access rights (role with Create verb).
  2. Create the JSON payload as per mandatory requirements:
    • Set AdditionalItemIdType to GTIN8, GTIN12, GTIN13, or GTIN14
    • Provide the correct Value for the Item
    • Optionally, use the same value for Id
    • Pad with leading zeros if needed, or choose the correct GTIN type
    • Set the correct BusinessUnitGroupId
    • Provide the ItemId
  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.
  6. On success, you receive 202 - Accepted.

Example GTIN-13/EAN: 5017726180034

Create Reverse Vending GTIN or EAN​

Reverse vending EAN/GTIN is usually a standard GTIN-13 barcode. Follow local regulations as needed.

How to create a reverse vending identifier
  1. Ensure your service has the required API access rights (role with Create verb).
  2. Create the JSON payload as per mandatory requirements:
    • Set AdditionalItemIdType to GTIN13 (or as required)
    • Provide the correct Value
    • Set the correct BusinessUnitGroupId
    • Use the correct ItemId for the Deposit Item
  3. Set headers as above.
  4. Use the POST endpoint.
  5. On success, you receive 202 - Accepted.

Example GTIN-13/EAN: 9802235003500

    980 2235 00350 0

    980   -> prefix for reverse vending
    2235  -> deposit receipt ID
    00350 -> deposit amount
    0     -> check digit

2D Identifiers​

Hii Retail supports DataMatrix and QR codes.

DataMatrix Identifier​

DataMatrix barcodes can hold large amounts of data. ECC140 is outdated; ECC220 is preferred.

How to create a DataMatrix identifier

Creating an ECC220 identifier​

  1. Ensure your service has the required API access rights (role with Create verb).
  2. Create the JSON payload as per mandatory requirements:
    • Set AdditionalItemIdType to ECC220
    • Provide the correct Value
    • Set the correct BusinessUnitGroupId
    • Use the correct ItemId
  3. Set headers as above.
  4. Use the POST endpoint.
  5. On success, you receive 202 - Accepted.

Creating an ECC140 identifier​

ECC140 is outdated; use ECC220 if possible. Otherwise, set AdditionalItemType to ECC140 (length restrictions apply).

QR Code Identifier​

QR Codes can be used for identification, promotions, or marketing. See GS1 QR Code recommendations.

How to create a QR identifier
  1. Ensure your service has the required API access rights (role with Create verb).
  2. Create the JSON payload as per mandatory requirements:
    • Set AdditionalItemIdType to QR
    • Provide the correct Value
    • Set the correct BusinessUnitGroupId
    • Use the correct ItemId
  3. Set headers as above.
  4. Use the POST endpoint.
  5. On success, you receive 202 - Accepted.