Hii retail pos
Integrating to use a legacy Extenda POS or Retail Suite POS solution
To integrate Items and Item related master data with Hii Retail, to continue to use a legacy POS solution, you will need to provide the following entities:
- Items (aka Article, Product, Service, SKU, ...)
- Item Categories (aka Merchandise Structure, Article Hierarchy, ...)
- Item Identifiers (aka Barcodes, PLU and SKU, ...)
- Deposit Rules (aka Deposit amounts, Reverse Vending amount, ...)
- Price Specifications (aka Price, Sales Price, Purchase Price, Default Price, ...)
Additionally you might want to integrate the following entities to provide further functionality in the POS:
- Promotion (aka Campaign, Mix and Match, ...)
- Item Links (aka Item connections, Related Items, Models, Bundles, Replacements, ...)
You also need to provide a specific set of Additional Properties to support the legacy POS. This is described in further detail below.
Mandatory Item information for any type of Item
Below we have listed the properties of an Item that are needed for the Item to be valid and sellable in the POS. There is also a requirement that other entities are provided for the POS to be able to have a complete data structure. See Price Specification and Item Identifier for a complete picture.
Mandatory Item information
| Property | Member of | Description |
|---|---|---|
id | Item | The internal Id of the Item. This can be the same as the GTIN for the Item, but we recommend keeping them separate as the Barcodes and GTINs tend to change over time. Hence it can be any type of Id, but make sure it is unique for all Items in your system. |
businessUnitGroupId or businessUnitId | Item | The Business Unit Group this item is placed in or the Business Unit the Item belongs to. See Business Units for more details. |
itemCategoryId | Item | The Id of the Item Category this Item is placed in. Not mandatory in the input API, but defaults to 0 if not provided. See Item Category for more details. |
identifiers | Item | This is a list of Item Identifiers, or primarily barcodes (GTIN). This is required when creating an Item as it needs to have an identifier the POS can use. See Item Identifier for more details. |
description | Item | The textual description of the Item. |
name | Item | The name of the Item. This will be the name used in the Receipt, in search and when visualizing the item in lists. |
status | Item | This is the operational status of the item. Set to Active if the item is in general use. See Item Statuses for more details |
itemType | Item | The Item Type this Item should be considered as. The Type will trigger different business logic in some systems, and you should be careful to set this to the correct type. See Item Types for more details. |
salesUnitOfMeasurement | Item | The unit of measure this item is sold in. Default value is EA but should be set to the appropriate Unit of Measurement for this Item. |
netContent | Item | The net content of the Item. This is a decimal value as needed, and should be evaluated together with SalesUnitOfMeasurement to make sense. Not mandatory in the input API, but defaults to 1. |
referencePriceUnitOfMeasurement | Item | A unit of measurement describing the content of the Item and how it can be priced per unit. Example: Price per kg or price per tablet. Must be evaluated in correspondence with ReferencePriceConversionFactor and the Sales Price. The property is not mandatory in the input API, but defaults to EA. |
referencePriceConversionFactor | Item | A factor for how to convert the sales price to "price per unit of measurement". Example: Price per kg or price per tablet. The property is not mandatory in the input API, but defaults to 1. |
Mandatory Price Specification information
Below we have listed the properties of a Price Specification that are needed for the Item to be valid and sellable in the POS. There is also a requirement that other entities are provided for the POS to be able to have a complete data structure. See Item Identifier and Item for a complete picture.
Details
| Property | Member of | Description |
|---|---|---|
id | Price Specification | The internal Id of the Price Specification. |
itemId | Price Specification | The id of the Item this Price Specification references. |
value | Price Specification | The decimal value for the Price Specification. |
priceType | Price Specification | The type of Price Specification. Must be of type "Sales" |
taxRuleId | Price Specification | The Id of the Tax Rule that applies to the Price Specification. This must be provided so that POS is able to calculate the correct Tax amount when the Item is sold. |
validFrom | Price Specification | The Price Specification must have a date and time that it is valid from. |
currencyId | Price Specification | The Id for the Currency the Price Specification is provided in. |
businessUnitGroupId or businessUnitId | Price Specification | The Business Unit Group this Price Specification is placed in or the Business Unit the Price Specification belongs to. See Business Units for more details. |
Mandatory Item Identifier (Additional Item Id) information
Below we have listed the properties of an Item Identifier that are needed for the Item to be valid and sellable in the POS. There is also a requirement that other entities are provided for the POS to be able to have a complete data structure. See Price Specification and Item for a complete picture.
The Extenda POS only supports GTIN (8-13) and PLU identifiers, so for integrating with the POS you need to provide at least one such Item Identifiers for all your items. You can of course have others too, but they will not be usable in the POS application.
Please also note that for management of Item Identifiers, there is a separate API for this, should your use-case require it.
Details
| Property | Member of | Description |
|---|---|---|
id | Item Identifier | The internal Id of the Item Identifier. This can be the same as the Value, but it is not a requirement. Hence it can be any type of Id, but make sure it is unique for all Additional Item Ids in your system. Also note that if you start to use 2D barcodes or DataMatrix you MUST use something else as the Id. |
value | Item Identifier | The actual value that identifies the Item. If GTIN this is the 8-14 digit numeric value with correct check digit. |
type | Item Identifier | The type of identifier you want. Usually GTIN-13 is used, but 2D barcodes are becoming mainstream in most retail domains. It is important that you select the correct type. |
itemId | Item Identifier | The Id of the Item entity. This is the Id property of the Item, so make sure they are the same. |
businessUnitGroupId or businessUnitId | Item Identifier | The Business Unit Group this Item Identifier is placed in or the Business Unit the Item Identifier belongs to. See Business Units for more details. |
Weight/Volume/Length Items
An Item that needs to have additional input before it can be checked out in a POS is often referred to as a Weight Item, Volume Item or Length Item.
It very often needs to be placed on a scale, or requires automatic or manual input to get the correct price for the item.
Such an item is basically the same as any other Item, except for the SalesUnitOfMeasurement. If this property is set to a Unit Of Measurement of a weight/volume/length type, the Item will be considered to need additional input in the POS.
Examples are: Fruit (
KGM), freshly cut meat (GRM), petrol or diesel (LTR), lumber (MTR), electrical wires (MTR), etc.
Most times these items will also have an Item Identifier of a particular kind that allows for the weight/volume/length or the price to become part of the barcode.
Additional Properties to trigger certain actions in the POS
The following examples all extend the mandatory information above.
Please contact your POS delivery team for questions regarding the usage and restrictions linked to the "Pos.XXX" additional properties.
Cashier control action in POS
The Control Flag can be used to facilitate a manual cashier control specific for this one item.
| Property | Member of | Description |
|---|---|---|
Pos.ControlFlag | AdditionalProperty | Flag instructs the cashier to control something. This Property is often used together with Pos.ItemText.Control.x which provides more information about what to control. |
Pos.ItemText.Control.0 | AdditionalProperty | ItemText of this type is used to instruct the cashier to perform an action. It might be to remember to remove an electronic tag from clothing or to remember to get a personal ID from the consumer. |
Example: The sale of a microwave might ask the cashier to open the device and look inside to make sure the customer has not placed other items inside it.
Allow/prevent promotion reward points
If this flag is false, there can be no promotion reward associated with this item. It can, however, still be part of a promotion condition.
| Property | Member of | Description |
|---|---|---|
Pos.DiscountFlag | AdditionalProperty | Flag that allows the item to earn reward points. |
Allow/prevent cashier markdown
This property can be used to allow or prevent ad-hoc markdown by a cashier for this particular item.
| Property | Member of | Description |
|---|---|---|
Pos.MarkdownFlag | AdditionalProperty | Flag that allows the Item to be marked down in the store. Used for "replacing" the normal price with a reduced one to remove it from stock because of expiry date or removed from assortment. |
Allow/prevent Item in a promotion
This property can be used to allow or prevent an Item from being part of a promotion.
| Property | Member of | Description |
|---|---|---|
Pos.PromotionFlag | AdditionalProperty | If this flag is false, this item is always excluded from promotions. This includes the condition part of a promotion. |
Allow/prevent Item to be returned
This property can be used to allow or prevent an Item from being returned.
| Property | Member of | Description |
|---|---|---|
Pos.RefundFlag | AdditionalProperty | Flag to allow the Item to be returned in exchange for a refund of the purchase amount. |
Force price to be entered manually
This property can be used to force the price to be entered manually even if there are other means to obtain it.
| Property | Member of | Description |
|---|---|---|
Pos.PriceEntryRequiredFlag | AdditionalProperty | Flag that requires a price to be entered instead of the price associated with the Item. |
Prohibit keyboard repeat key
This property can be used to prevent the repeat key of the keyboard in POS to be used. Some items should not be possible to add multiple times to the receipt. Often used together with other Additional Properties.
| Property | Member of | Description |
|---|---|---|
Pos.ProhibitRepeatKeyFlag | AdditionalProperty | Flag restricting the repeat key in the POS application. This might be used on particularly expensive Items, or Items that require warranty information, etc. This is to reduce the risk of adding multiple Items to the sales transaction, or to prevent several Items to be added that would all need warranty information filled out. |
Require a quantity from the cashier
This property can be used to require a quantity to be entered manually by the cashier.
| Property | Member of | Description |
|---|---|---|
Pos.QuantityEntryRequiredFlag | AdditionalProperty | Flag that instructs the POS to require a quantity to be provided by the cashier. |
Prevent a quantity to be entered
This property can be used to prevent a quantity from being entered manually by the cashier.
| Property | Member of | Description |
|---|---|---|
Pos.QuantityKeyProhibitFlag | AdditionalProperty | Flag that prevents a quantity to be provided by the cashier. |
Require a tare weight from the cashier
This property can be used to require a tare to be entered manually by the cashier.
| Property | Member of | Description |
|---|---|---|
Pos.TareEntryRequiredFlag | AdditionalProperty | Flag that instructs the POS to ask for a Tare weight to be provided. This is the weight of the packaging or wrapping of the actual item, and should be deducted from the weight before calculating a price. |
Require warranty information
This property can be used to require a tare to be entered manually by the cashier.
| Property | Member of | Description |
|---|---|---|
Pos.WarrantyFlag | AdditionalProperty | Flag that instructs the cashier to inform about and potentially fill out warranty information for the Item. |
Restricted number of items per sale
These properties can be used to restrict the maximum or minimum number of items to buy per sale.
| Property | Member of | Description |
|---|---|---|
Pos.MaximumRegistrationSaleUnitCount | AdditionalProperty | The maximum number possible to sell of this particular item. Very often used on pharmaceutical items to restrict sale to one item per customer. |
Pos.MinimumRegistrationSaleUnitCount | AdditionalProperty | The minimum number possible to sell of this particular item. |
Negative price on an item
This property can be used to allow an Item to be sold with a negative price. Can be used for Deposit Items etc.
| Property | Member of | Description |
|---|---|---|
Pos.NegativePriceFlag | AdditionalProperty | Flag that allows a negative price on the Item. |
Earn bonus points on this Item
This property can be used when a bonus program exists and this Item should produce bonus points to that program.
| Property | Member of | Description |
|---|---|---|
Pos.FrequentShopperPointsEligibilityFlag | AdditionalProperty | Flag that indicates if this Item should give the customer "bonus points" in a customer loyalty program. |
Receipt and customer display information
These properties can be used when additional information is needed on the receipt or on a customer display. They have different purposes, and all are not needed. Use the one(s) that serve the purpose you need.
Also note that they have a numerical value at the end. This is to allow multiple statements as needed.
Example:
Pos.ItemText.Receipt.1,Pos.ItemText.Receipt.2,Pos.ItemText.Receipt.3will provide 3 extra lines on the receipt for this Item.
| Property | Member of | Description |
|---|---|---|
Pos.ItemText.Promotional.0 | AdditionalProperty | Promotional ItemText. Text will be visible on the receipt if this item is used as part of a promotion. |
Pos.ItemText.Receipt.0 | AdditionalProperty | Receipt ItemText. Text will be visible on the receipt. |
Pos.ItemText.CustomerDisplay.0 | AdditionalProperty | Text will be shown on a customer facing screen, if one exists. This is information to the consumer that would be needed to show during the sale. |
Pos.ItemText.DescriptionExtension.0 | AdditionalProperty | Extra text that will be added to the item description. |
Pos.ItemText.PermanentMarkdown.0 | AdditionalProperty | Extra text describing an Item that is on permanent markdown. |
Prevent the price in the barcode from being used
| Property | Member of | Description |
|---|---|---|
| Pos.ProhibitPriceInBarCode | AdditionalProperty | Ignore the price in the barcode and use item price instead. |
Extended information in POS
The need for custom information is always present. This is a core concept of the Hii Retail entities. When integrating with a POS application, this application also has a possibility for extending it's data model. To achieve we need to provide the information according to a naming convention. For POS to consider this as extended information it is required to name the information as "Pos.Extra.xxx" The "Extra" is the identifier that allows the POS to place this information in the correct place.
For complete details on what is possible to provide, please contact your account manager in Extenda Retail.
| Property | Member of | Description |
|---|---|---|
Pos.Extra.ElectronicItem | AdditionalProperty | Indicates if this item is an electronic item. |