Item Identifier Validation

GTIN Validation

When a GTIN is submitted, Hii Retail validates it against the following rules:

• Correct length — the value must match the digit count of its type (GTIN8 = 8 digits, GTIN13 = 13 digits, etc.)
• Check digit — validated using the GS1 standard algorithm, unless the matching prefix definition has validateCheckDigit: false
• GS1 prefix definitions — the GTIN prefix is looked up to determine its PrefixType, which governs duplicate checking, embedded data handling, and whether the GTIN is allowed at all
• Uniqueness — a GTIN must be unique within the configured duplication check scope; see Duplication Check Configuration below

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

GS1 Prefix Types and Their Effect on Validation

GS1 prefixes are allocated by GS1 Member Organizations and identify the type and purpose of a GTIN. See the GS1 Company Prefix standard for more information.

The PrefixType of the matching prefix definition determines how the GTIN is handled:

Prefix Type	Duplicate Check	Description
NORMAL	Yes	Regular GTIN with no special handling.
PRICE	Forced to BUSINESS_UNIT	Variable measure GTIN encoding a price in defined barcode positions.
WEIGHT	Forced to BUSINESS_UNIT	Variable measure GTIN encoding a weight in defined barcode positions.
PRICE_WEIGHT	Forced to BUSINESS_UNIT	Variable measure GTIN encoding price or weight.
PIECE	Forced to BUSINESS_UNIT	Variable measure GTIN encoding a piece count.
LENGTH	Forced to BUSINESS_UNIT	Variable measure GTIN encoding a length.
PIECE_WEIGHT	Forced to BUSINESS_UNIT	Variable measure GTIN encoding piece count or weight.
DEPOSIT	Yes	Reverse vending / refund GTINs.
ISSN	Yes	Serial publications (maps to ISSN identifier type).
ISBN	Yes	Books (maps to ISBN identifier type).
COUPONS	Forced to BUSINESS_UNIT	Coupons and vouchers.
RESTRICTED	—	GS1-restricted prefix; not assignable to products. Submission is rejected.
RESERVED_GS1	—	Reserved for GS1 internal use. Submission is rejected.
RESERVED_GTIN8	—	Reserved for GTIN-8 ranges only; invalid for GTIN-12/13/14.
BLOCKED	—	Explicitly blocked prefix. Submission is rejected.

Variable measure GTINs (PRICE, WEIGHT, PRICE_WEIGHT, PIECE, LENGTH, PIECE_WEIGHT, COUPONS) always have their duplication check scope forced to BUSINESS_UNIT, regardless of any tenant configuration. This is because the same barcode encodes different data (price, weight, etc.) per context, making it valid across different business units.

For these types, dataStartPosition and dataEndPosition in the prefix definition specify where the variable data is encoded in the barcode.

Querying Prefix Definitions

You can retrieve the full list of configured GS1 prefix definitions via the Item Identifier Query API:

query {
  prefixDefinitions(first: 100) {
    nodes {
      prefix
      prefixType
      countryCode
      issuingCountryCode
      validateCheckDigit
      dataStartPosition
      dataEndPosition
      description
    }
  }
}

See the prefixDefinitions query and the PrefixDefinition type for the full schema reference.

Duplication Check Configuration

Default Behavior

By default, Hii Retail enforces a tenant-wide duplication check for all GTIN types (GTIN8, GTIN12, GTIN13, GTIN14). A GTIN value can only be linked to one item across your entire tenant.

Tenant Override

The default can be overridden using the upsert tenant duplication check config operation in the Item Identifier Input API.

Once a tenant-specific configuration is active, it fully replaces the default — only the tenant configuration is applied.

A configuration consists of one or more rules. Each rule defines which identifier types it covers and the scope at which duplicates are checked:

Scope	Description
TENANT	Uniqueness enforced across the entire tenant.
BUSINESS_UNIT_GROUP	Uniqueness enforced within a specific business unit group hierarchy. businessUnitGroupId is required.
BUSINESS_UNIT	Uniqueness enforced per business unit only. The same value may exist in different business units.
NONE	No duplication check performed for the specified types.

Multiple rules in a configuration are applied with AND logic — all rules must pass for the identifier to be accepted.

To inspect the currently active configuration for your tenant:

query {
  duplicationCheckConfig {
    rules {
      itemIdentifierTypes
      duplicationCheckScope
      businessUnitGroupId
    }
  }
}

See the duplicationCheckConfig query for the full schema reference.

Risks of Changing the Scope of Duplication Checks

Recommendation: Do not change the default duplication check configuration without careful consideration.

Reducing the check scope (e.g. from TENANT to BUSINESS_UNIT) or disabling checks with NONE allows the same identifier value to be linked to different items. This can lead to:

• Incorrect item resolution at POS — a barcode scan may return the wrong item depending on store context
• Inconsistent data in downstream systems that consume item identifier events
• Reporting errors when aggregating data across business units

Consequences of Changing Rules

Changing the duplication check configuration takes effect for new identifier inputs only — it does not affect identifiers already in the system:

• Tightening rules — existing identifiers are not removed, but any new input of a value that now violates the new scope will be rejected
• Loosening rules — identifier inputs that were previously rejected as duplicates will now be accepted, potentially linking the same identifier value to different items

Before changing the configuration, communicate the change to teams managing item data integrations, as inputs that were previously accepted may now be rejected, or vice versa.