Getting Started with Business Units

This guide walks you through creating Business Units and Business Unit Groups on the Hii Retail platform. By the end of this guide, you will understand the core concepts and be able to programmatically create and manage your organizational structure.

Overview

What is a Business Unit?

A Business Unit represents a physical or logical location within your business. This could be:

• A retail store
• A webshop
• A warehouse
• A distribution center

Each Business Unit has a unique identifier and can be assigned articles, prices, configurations, and more. Business Units are the foundational building blocks for organizing your retail operations on the Hii Retail platform.

info

Business Units are never fully deleted. When you delete a Business Unit, it is soft-deleted and removed from list and get requests. You can restore a deleted Business Unit, but you cannot create a new one with the same ID as a soft-deleted unit.

What is a Business Unit Group?

A Business Unit Group allows you to organize multiple Business Units together for easier management. Instead of configuring each store individually, you can:

• Create groups based on store size (small, medium, large)
• Create groups based on branding or profile
• Create groups based on geographic region
• Create groups for price zones

Groups are hierarchical, meaning:

• Data added to a parent group is inherited by all child groups and Business Units below
• Child groups can override inherited data when needed

Why Use Groups?

Consider a retail chain with 500 stores. Without groups, you would need to:

• Assign product assortments to each store individually
• Set prices for each store individually
• Configure settings for each store individually

With Business Unit Groups, you can:

• Create a "Base Assortment" group that applies to all stores
• Create regional price groups that override base prices where needed
• Assign stores to groups once, and they automatically inherit the correct configuration

Prerequisites

Before you begin, ensure you have:

1. API Access: Valid credentials for the Hii Retail platform
2. Authentication Token: A valid JWT bearer token with the bum.business-unit.create permission
3. Tenant ID: Your organization's tenant identifier

Authentication

For details on obtaining an access token, see the OAuth2 Authentication documentation.

API Base URL

All Business Unit Management API requests should be sent to:

https://business-unit.retailsvc.com/api/v1

Step 1: Create a Business Unit

A Business Unit requires at minimum a name and status. The businessUnitId is provided in the URL path.

Request

PUT /api/v1/business-units/{businessUnitId}

Fields

Field	Type	Required	Description	Comment
name	string	Yes	Name of the Business Unit (max 200 characters)	The name is both used for presentation purposes but also as a variable in receipt text for compliance purposes
status	string	Yes	Created, Active, or Closed	Set the status to Created when you add it. It will become active once it has also been assigned data
type	string		PHYSICAL_STORE or WAREHOUSE
countryCode	string		ISO country code	The country code is important as it will determine certain configuration for compliance purposes
groups	array		Group IDs this unit belongs to
addresses	array		Physical addresses	It is highly recommended to assign the address that should be present on the receipt/invoice for compliance purposes
gln	string		Global Location Number
timeOffset	string		Timezone offset	TODO does this actually do anything?
organizationNumber	string		Legal organization number	This is also highly recommended to assign as it is legally required for the receipts in most countries
vatNumber	string		VAT registration number	Some countries use more than one registration number with the tax authorities, if so this is to be used

Code Examples

cURL

curl -X PUT 'https://business-unit.retailsvc.com/api/v1/business-units/{{business-unit-id}}' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "{{your-bu-name}}",
    "status": "{{bu-status}}",
    "type": "{{bu-type}}",
    "countryCode": "{{iso-cc}}",
    "addresses": [
      {
        "addressType": "PHYSICAL",
        "street": "{{your-street}}",
        "city": "{{your-city}}",
        "zipCode": "{{your-postcode}}",
        "country": "{{your-country}}"
      }
    ]
  }'

Python

response = requests.put(
    "https://business-unit.retailsvc.com/api/v1/business-units/{{business-unit-id}}",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "name": "{{your-bu-name}}",
        "status": "{{bu-status}}",
        "type": "{{bu-type}}",
        "countryCode": "{{iso-cc}}",
        "addresses": [{
            "addressType": "PHYSICAL",
            "street": "{{your-street}}",
            "city": "{{your-city}}",
            "zipCode": "{{your-postcode}}",
            "country": "{{your-country}}"
        }]
    }
)

Node.js

const response = await fetch('https://business-unit.retailsvc.com/api/v1/business-units/{{business-unit-id}}', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '{{your-bu-name}}',
    status: '{{bu-status}}',
    type: '{{bu-type}}',
    countryCode: '{{iso-cc}}',
    addresses: [{
      addressType: 'PHYSICAL',
      street: '{{your-street}}',
      city: '{{your-city}}',
      zipCode: '{{your-postcode}}',
      country: '{{your-country}}'
    }]
  })
});

Java

var payload = """
    {
      "name": "{{your-bu-name}}",
      "status": "{{bu-status}}",
      "type": "{{bu-type}}",
      "countryCode": "{{iso-cc}}",
      "addresses": [{
        "addressType": "PHYSICAL",
        "street": "{{your-street}}",
        "city": "{{your-city}}",
        "zipCode": "{{your-postcode}}",
        "country": "{{your-country}}"
      }]
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://business-unit.retailsvc.com/api/v1/business-units/{{business-unit-id}}"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .PUT(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

.NET

var payload = new {
    name = "{{your-bu-name}}",
    status = "{{bu-status}}",
    type = "{{bu-type}}",
    countryCode = "{{iso-cc}}",
    addresses = new[] {
        new {
            addressType = "PHYSICAL",
            street = "{{your-street}}",
            city = "{{your-city}}",
            zipCode = "{{your-postcode}}",
            country = "{{your-country}}"
        }
    }
};

var content = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");
var response = await httpClient.PutAsync("https://business-unit.retailsvc.com/api/v1/business-units/{{business-unit-id}}", content);

Response

A successful request returns 201 Created (for new units) or 200 OK (for updates):

{
  "id": "{{business-unit-id}}",
  "name": "{{your-bu-name}}",
  "status": "{{bu-status}}",
  "type": "{{bu-type}}",
  "countryCode": "{{iso-cc}}",
  "addresses": [
    {
      "addressType": "PHYSICAL",
      "street": "{{your-street}}",
      "city": "{{your-city}}",
      "zipCode": "{{your-postcode}}",
      "country": "{{your-country}}"
    }
  ],
  "groups": [],
  "created": "2024-01-15T10:30:00Z",
  "modified": "2024-01-15T10:30:00Z"
}

Step 2: Create a Business Unit Group

Business Unit Groups help you organize stores and apply configurations at scale.

Request

POST /api/v1/groups

Fields

Field	Type	Required	Description
name	string	Yes	Name of the group
parentGroupId	string		Parent group ID for hierarchies

Code Examples

cURL

curl -X POST 'https://business-unit.retailsvc.com/api/v1/groups' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "{{group-name}}"
  }'

Python

response = requests.post(
    "https://business-unit.retailsvc.com/api/v1/groups",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"name": "{{group-name}}"}
)

Node.js

const response = await fetch('https://business-unit.retailsvc.com/api/v1/groups', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: '{{group-name}}' })
});

Java

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://business-unit.retailsvc.com/api/v1/groups"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""{"name": "{{group-name}}"}"""))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

.NET

var content = new StringContent(JsonSerializer.Serialize(new { name = "{{group-name}}" }), Encoding.UTF8, "application/json");
var response = await httpClient.PostAsync("https://business-unit.retailsvc.com/api/v1/groups", content);

Response

A successful request returns 200 OK:

{
  "id": "{{group-id}}",
  "name": "{{group-name}}",
  "parentGroupId": null,
  "created": "2024-01-15T10:35:00Z",
  "modified": "2024-01-15T10:35:00Z"
}

Step 3: Assign a Business Unit to a Group

To assign a Business Unit to one or more groups, update the Business Unit with the group IDs.

Code Examples

cURL

curl -X PUT 'https://business-unit.retailsvc.com/api/v1/business-units/{{business-unit-id}}' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "{{your-bu-name}}",
    "status": "{{bu-status}}",
    "type": "{{bu-type}}",
    "countryCode": "{{iso-cc}}",
    "groups": ["{{group-id}}"]
  }'

Python

# Get current data, add groups, then update
current_data = requests.get(
    "https://business-unit.retailsvc.com/api/v1/business-units/{{business-unit-id}}",
    headers={"Authorization": f"Bearer {access_token}"}
).json()

current_data["groups"] = ["{{group-id}}"]

response = requests.put(
    "https://business-unit.retailsvc.com/api/v1/business-units/{{business-unit-id}}",
    headers={"Authorization": f"Bearer {access_token}"},
    json=current_data
)

Node.js

// Get current data, add groups, then update
const url = 'https://business-unit.retailsvc.com/api/v1/business-units/{{business-unit-id}}';
const headers = { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' };

const currentData = await (await fetch(url, { headers })).json();
currentData.groups = ['{{group-id}}'];

const response = await fetch(url, {
  method: 'PUT',
  headers,
  body: JSON.stringify(currentData)
});

Java

// Get current data, add groups, then update
var payload = """
    {
      "name": "{{your-bu-name}}",
      "status": "{{bu-status}}",
      "type": "{{bu-type}}",
      "countryCode": "{{iso-cc}}",
      "groups": ["{{group-id}}"]
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://business-unit.retailsvc.com/api/v1/business-units/{{business-unit-id}}"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .PUT(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());

.NET

// Get current data, add groups, then update
var url = "https://business-unit.retailsvc.com/api/v1/business-units/{{business-unit-id}}";
var currentData = JsonSerializer.Deserialize<Dictionary<string, object>>(
    await httpClient.GetStringAsync(url));

currentData["groups"] = new[] { "{{group-id}}" };

var content = new StringContent(JsonSerializer.Serialize(currentData), Encoding.UTF8, "application/json");
var response = await httpClient.PutAsync(url, content);

Next Steps

Now that you understand the basics of Business Units and Groups, you can:

1. Explore the full API: See all available endpoints in the Business Unit Management API reference
2. Set up hierarchies: Create complex group structures for different use cases (pricing, assortment, configuration)
3. Learn about inheritance: Understand how data flows through group hierarchies in the Business Unit Management concepts

Related Resources

• Business Unit Management API Reference
• Business Unit Management Concepts
• OAuth2 Authentication

---

Next: Item Categories - Learn how to create and manage item categories for organizing your products.