Getting Started with Hii Retail
Welcome to the Hii Retail Getting Started guide. This series of tutorials will walk you through setting up a complete retail product catalog, from creating your organizational structure to configuring products ready for sale.
What You'll Build
By the end of this guide series, you'll have configured a fully functional retail setup including:
- Stores and organizational hierarchy - Business Units and Groups
- Product taxonomy - Item Categories for organizing products
- Product catalog - Items with descriptions and attributes
- Scannable identifiers - Barcodes (GTINs, PLUs, SKUs) for POS scanning
- Pricing - Sales prices, purchase costs, and historic prices
- Tax configuration - Regional tax rules and taxable groups
- Deposit rules - Refundable deposits for bottles and containers
- Sales restrictions - Age verification for regulated products
┌───────────────────────────────────────────────────────────────────────────┐
│ Your Retail Setup Journey │
├───────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Business │───▶│ Item │───▶│ Items │ │
│ │ Units │ │ Categories │ │ │ │
│ └──────────────┘ └──────────────┘ └──────┬───────┘ │
│ │ │
│ ┌─────────────────┬───────────────────┼───────────────┐ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Identifiers │ │ Prices │ │ Deposits │ │ Sales │ │
│ │ (Barcodes) │ │ + Tax │ │ & Fees │ │ Restrictions │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────┘
The Learning Path
Each guide builds on the previous one, introducing new concepts while reinforcing what you've learned:
| Step | Guide | What You'll Learn |
|---|---|---|
| 1 | Business Units | Create stores and organizational groups that form your retail hierarchy |
| 2 | Item Categories | Set up product categories using industry standards (GS1 GPC) |
| 3 | Items | Create products and assign them to categories and business units |
| 4 | Item Identifiers | Add barcodes and other scannable identifiers to your products |
| 5 | Prices | Configure sales prices, purchase costs, and price history |
| 6 | Tax | Set up tax regions and apply correct tax rates to products |
| 7 | Deposits | Configure refundable deposits and environmental fees |
| 8 | Sales Restrictions | Add age restrictions for alcohol, tobacco, and other regulated products |
Prerequisites
Before you begin, ensure you have:
- API Access - Valid credentials for the Hii Retail platform
- Authentication Token - A JWT bearer token obtained via OAuth2 (see Authentication guide)
- Basic REST API knowledge - Familiarity with HTTP methods and JSON
All code examples are provided in multiple languages: cURL, Python, Node.js, Java, and .NET. Choose the one that best fits your stack.
Key Concepts
Asynchronous Processing
Most Hii Retail APIs process requests asynchronously. When you create or update an entity, you'll receive a 202 Accepted response indicating the request has been queued. The actual processing happens in the background.
Business Unit Groups vs Business Units
- Business Unit Groups are organizational containers (e.g., "ACME Retail", "North Region")
- Business Units are physical or logical stores within groups
- Data configured at the group level automatically inherits to all units within that group
Entity Relationships
Entities in Hii Retail are interconnected:
Business Unit Group
└── Business Unit (Store)
└── Item
├── Item Identifiers (barcodes)
├── Price Specifications
├── Tax Rules (via taxRuleId)
├── Deposit Rules (via depositAndFeeRuleId)
└── Sales Restrictions (via additionalProperties)
Complete Items and Missing Dependencies
A common question is: "Why did my API call succeed but the item doesn't appear at the POS?"
This happens because Hii Retail uses eventual consistency. A 202 Accepted response means your data was received and queued for processing—not that it's ready for use at the point of sale.
For an item to be distributed to POS systems, it must be complete. A Complete Item requires at minimum:
- Item - The product definition
- Sales Price - At least one active
SALEStype Price Specification - Identifier - At least one scannable barcode (GTIN, PLU, etc.)
┌───────────────────────────────────────────────────────────────────────────┐
│ Complete Item Requirements │
├───────────────────────────────────────────────────────────────────────────┤
│ │
│ Item Definition ──────┐ │
│ │ │
│ Sales Price ──────────┼──────▶ Complete Item ──────▶ POS │
│ │ │
│ Identifier ───────────┘ │
│ │
│ ⚠️ Missing any piece = Item NOT distributed to POS │
│ │
└───────────────────────────────────────────────────────────────────────────┘
If any required piece is missing, Hii Retail emits a Customer Notification event after 10 minutes. Subscribe to these notifications via the External Events service to receive alerts about incomplete items.
We strongly recommend setting up External Events subscriptions before you start creating items. This gives you immediate feedback when something is misconfigured.
For more details, see the Complete Items concept and Error Handling documentation.
Ready to Start?
Begin your journey by setting up your organizational structure with Business Units.
Next: Business Units - Create your first store and organizational hierarchy.