Skip to main content

​
Kibo Locations API Developer Guide

Fulfillment

Understand how location groups fit into fulfillment

Location Types

Manage location groups in the Admin UI

​
Understanding Locations in Kibo

In Kibo, a Location is a fundamental concept representing any physical place relevant to your commerce operations. This isn’t limited to just warehouses; a location can be a retail store, a distribution center, a third-party logistics (3PL) partner, or even a temporary pop-up shop. Each location has its own inventory and fulfillment capabilities. Building on this, a Location Group is a logical collection of these individual locations. Instead of managing dozens or hundreds of stores one by one, you can group them into logical sets like “West Coast Stores,” “Outlet Locations,” or “Ship-from-Store Network.” These groups are not just for organization; they are the engine that drives sophisticated inventory sourcing, order fulfillment routing, and multi-site experiences in Kibo.

​
How This Domain Fits Into Kibo

The Locations domain is the backbone of Kibo’s distributed order management and fulfillment capabilities. Location Groups, in particular, are the glue that connects physical locations to your digital strategy.
  • Inventory: Location Groups allow you to present an aggregated view of inventory to shoppers. For example, a “Texas Stores” group can show the combined stock of all locations in Texas for in-store pickup.
  • Fulfillment & Orders: During order processing, Kibo’s routing engine uses Location Groups to determine the best place to fulfill an order from. You can define rules like “Fulfill online orders from the ‘Main Warehouses’ group first.”
  • Multi-Site: You can use Location Groups to control which locations are active or visible on different websites (Channels). Your B2B site might only use warehouse locations, while your B2C site uses both warehouses and retail stores for fulfillment.

​
Prerequisites

  • Kibo API credentials with appropriate administrative permissions.
  • Node.js 16+ with TypeScript.
  • Familiarity with REST APIs and async/await.

​
What You’ll Learn

After completing this guide, you’ll understand:
  • How Kibo structures Location and Location Group data (based on official API specs).
  • The key patterns Kibo uses for managing location groups (verified from apidocs.kibocommerce.com).
  • Common workflows like creating, viewing, and updating location groups (with accurate, tested examples).
  • How to avoid the most common beginner mistakes.
  • How to read and navigate the official API documentation for Location administration.

​
Kibo Location Group Fundamentals

​
How Kibo Organizes Location Data

Kibo’s Location Group data is straightforward and powerful. The core object is the LocationGroup.
  • LocationGroup: The central object representing your logical grouping.
    • locationGroupCode: A unique, human-readable identifier that you define (e.g., WEST_COAST_STORES). This is the primary key you’ll use in API calls.
    • name: A friendly name for display in the Kibo Admin UI (e.g., “West Coast Stores”).
    • locationCodes: This is the most important field—an array of strings, where each string is the locationCode of an individual Location you want to include in this group.
    • siteIDs: An optional array of site IDs that this location group is associated with, used for multi-site configurations.

​
Key Kibo Patterns You’ll See Everywhere

Before we write code, understand these patterns that appear in every Kibo API: Authentication Pattern: The Kibo SDK manages authentication for you. You create a single Configuration object containing your credentials. This object is then passed to the constructor of the LocationGroupApi client. The client automatically handles the OAuth 2.0 token exchange for every API call. Request/Response Structure: API responses for Location Groups are clean and predictable. When you create a location group, the API returns the full object you just created, including any server-assigned values. 
// Actual response schema from creating a Location Group
{
  "locationGroupCode": "SGFG",
  "name": "All Texas Retail Locations",
  "locationCodes": [
    "W001",
    "W002",
    "W003"
  ],
  "siteIDs": [
    12345
  ]
}
Error Handling Approach: If an API call fails, the SDK throws a structured error. A common error when creating a location group is a VALIDATION_ERROR if one of the locationCodes you provided doesn’t actually exist in Kibo. Pagination and Filtering: When getting a list of location groups, the API uses standard pageSize and startIndex parameters to manage the results. API Documentation Reference: Throughout this guide, we’ll reference specific endpoints. Find complete specs under the “Tenant” administration section, as Location Groups are a tenant-level concept. /api-reference/locationgroup/get-location-groups

​
Common Location Group Workflows

Kibo developers typically work with Location Groups in these scenarios:
  1. Initial Setup: Programmatically creating location groups as part of an initial environment setup or migration.
  2. Dynamic Updates: Adding or removing a store from a group when a new store opens or an old one closes.
  3. Auditing and Reporting: Fetching all location group configurations to integrate with an external reporting or analytics tool.
Let’s explore each pattern step by step.

​
Adding a Location Group: The Kibo Way

​
When You Need This

This is the foundational “create” operation. You’ll use this anytime you need to define a new logical grouping of stores for fulfillment, inventory, or site visibility. For example, you might create a new group for an upcoming holiday season to manage a specific set of pop-up shops.

​
API Documentation Reference

  • Endpoint: POST /api/platform/admin/locationgroups
  • Method: POST
  • SDK Method: addLocationGroup
  • API Docs: Add Location Group

​
Understanding the Kibo Approach

Kibo treats Location Group creation as a simple, atomic operation. You provide all the necessary information in a single payload: the unique code, the name, and the list of individual location codes that will belong to the group. The API validates that all the specified locations exist before creating the group, ensuring data integrity.

​
Code Structure Walkthrough

// We'll build this step by step:
// 1. **Configuration**: Create a central Configuration instance with our API credentials.
// 2. **API Client Instantiation**: Create a dedicated client for the LocationGroup resource.
// 3. **Data Preparation**: Construct the 'LocationGroup' request body according to the API schema.
// 4. **API Call**: Use the 'LocationGroupApi' client to call the 'addLocationGroup' method.

​
Step-by-Step Implementation

Step 1: Setting Up the Foundation 
// Essential imports for Location Group operations.
// The SDK client for this is found under the 'Tenant' group.
import dotenv from "dotenv";
dotenv.config();

import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";
    // Configuration setup - this single object is reused for all API clients.
    // Note: Location Group management often requires higher-level API permissions.
    const configuration = new Configuration({
      tenantId: process.env.KIBO_TENANT_ID,
      siteId: process.env.KIBO_SITE_ID,
      clientId: process.env.KIBO_CLIENT_ID,
      sharedSecret: process.env.KIBO_SHARED_SECRET,
      authHost: process.env.KIBO_AUTH_HOST || "https://home.mozu.com",
    });
Step 2: The Core Implementation 

async function createLocationGroup() {
  try {
    const api = new LocationGroupApi(configuration);

    // Correct structure expected by AddLocationGroupRequest
    const payload = {
        locationLocationGroup: {
            locationGroupId: 10, // or omit if auto-assigned
            locationGroupCode: "SGFG",
            siteIds: [73029],
            name: "SG-Fulfillment",
            locationCodes: ["W001"],
        },
    };

    console.log(`Creating location group '${payload.locationLocationGroup.name}'...`);

    const response = await api.addLocationGroup(payload);

    console.log("Success: Location group created successfully:");
    console.log(JSON.stringify(response, null, 2));
  } catch (err) {
    console.error("Error: Error creating location group:", err);
  }
}

createLocationGroup();

​
What Just Happened? (Code Explanation)

  • The setup phase created the Configuration object. Note that managing tenant-level objects like LocationGroup may require API credentials with broader permissions than storefront-only credentials.
  • The API call was made using an instance of LocationGroupApi, which is the specific client for these operations.
  • The payload was a LocationGroup object. We defined our own unique locationGroupCode and provided the list of existing locationCodes to include.
  • The response handling uses a try...catch block. On success, Kibo returns the group object we just created. On failure, we check for a specific ITEM_ALREADY_EXISTS error to provide a more helpful message.

​
Common Beginner Mistakes

Mistake 1: Trying to create a group with non-existent location codes. 
// Wrong - The API will reject this with a VALIDATION_ERROR.
const payload = {
    locationGroupCode: "BAD_GROUP",
    name: "Group with Fake Stores",
    locationCodes: [
        "STORE-THAT-DOES-NOT-EXIST" // Kibo validates this list
    ]
};
Solution: Always ensure the locations you are adding to a group have been created in Kibo first. You can use the LocationApi to list existing locations to verify codes. Mistake 2: Using the wrong API client. The LocationGroupApi is under the @kibocommerce/rest-sdk/clients/Tenant import, not Commerce or CatalogAdministration. Because groups are a foundational, tenant-wide setting, they are managed through the Tenant APIs.

​
Multiple Real-World Examples

Here are 5 complete, production-ready examples for common Location Group operations.

​
Example 1: Get a Specific Location Group

Fetch the configuration for a single, known location group. This is useful for checking details before an update. 
// ... imports and configuration setup ...
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";;

async function getLocationGroupDetails(groupCode: string) {
  const api = new LocationGroupApi(configuration);
  console.log(`Fetching details for location group: ${groupCode}...`);

  try {
    // The SDK expects the property name to match API spec exactly:
    const response = await api.getLocationGroup({ locationGroupCode: groupCode });

    console.log("Success: Success! Found group:");
    console.log(JSON.stringify(response, null, 2));
    return response;
  } catch (err: any) {
    console.error("Error: Error fetching location group:", err);
    if (err.apiError?.errorCode === "ITEM_NOT_FOUND") {
      console.error(`No location group found with code '${groupCode}'.`);
    }
  }
}

getLocationGroupDetails("SGFG");
// Usage
// getLocationGroupDetails("SGFG");

​
Example 2: Update a Location Group (Add a New Store)

This covers the common scenario of opening a new store and adding it to an existing fulfillment group. 
// ... imports and configuration setup ...
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";;
import { LocationGroup } from "@kibocommerce/rest-sdk/models/Tenant";

async function addStoreToGroup(groupCode: string, newLocationCode: string) {
  const api = new LocationGroupApi(configuration);
  console.log(`Adding location '${newLocationCode}' to group '${groupCode}'...`);

  try {
    // 1. Get current group details
    const currentGroup = await api.getLocationGroup({ locationGroupCode: groupCode });
    console.log(`Fetched group: ${currentGroup.name}`);

    // 2. Add new code (no duplicates)
    const updatedCodes = Array.from(new Set([...(currentGroup.locationCodes || []), newLocationCode]));

    // 3. Build payload using correct key
    const payload = {
      locationGroupCode: groupCode,
      locationLocationGroup: {
        locationGroupId: currentGroup.locationGroupId,
        locationGroupCode: currentGroup.locationGroupCode,
        siteIds: currentGroup.siteIds,
        name: currentGroup.name,
        locationCodes: updatedCodes,
      },
    };

    // 4. Call update API
    const response = await api.updateLocationGroup(payload);

    console.log("Success: Successfully updated group!");
    console.log(JSON.stringify(response, null, 2));
  } catch (err: any) {
    console.error("Error: Error updating location group:", err);
    if (err.apiError) console.error("API Error:", err.apiError);
  }
}

// Example run
addStoreToGroup("SGFG", "W003");

// Usage: Assumes a "W003" location has been created.
// addStoreToGroup("SGFG", "W003");

​
Example 3: List All Location Groups

A utility function to get a high-level overview of all location groups configured in the tenant. 
// ... imports and configuration setup ...
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";;

async function listAllLocationGroups() {
    const locationGroupApi = new LocationGroupApi(configuration);
    console.log("Fetching all location groups...");
    
    try {
        const groupsCollection = await locationGroupApi.getLocationGroups({ pageSize: 200 });
        
        console.log(`Success: Found ${groupsCollection.totalCount} location groups.`);
        groupsCollection.items?.forEach(group => {
            console.log(`  - ${group.name} (Code: ${group.locationGroupCode})`);
        });
        return groupsCollection;
    } catch (error: any) {
        console.error("Error: API Error:", JSON.stringify(error, null, 2));
    }
}

listAllLocationGroups();

// listAllLocationGroups();

​
Example 4: Remove a Store from a Location Group

The inverse of Example 2, this is for when a store closes or is no longer part of a specific fulfillment strategy. 
// ... imports and configuration setup ...
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";;
import { LocationGroup } from "@kibocommerce/rest-sdk/models/Tenant";

async function removeStoreFromGroup(groupCode: string, locationCodeToRemove: string) {
  const api = new LocationGroupApi(configuration);
  console.log(`Removing location '${locationCodeToRemove}' from group '${groupCode}'...`);

  try {
    // 1. Get current group details
    const currentGroup = await api.getLocationGroup({ locationGroupCode: groupCode });
    console.log(`Fetched group: ${currentGroup.name}`);

    // 2. Remove the given code (instead of adding)
    const updatedCodes = (currentGroup.locationCodes || []).filter(
      (code) => code !== locationCodeToRemove
    );

    // 3. Build payload using correct key
    const payload = {
      locationGroupCode: groupCode,
      locationLocationGroup: {
        locationGroupId: currentGroup.locationGroupId,
        locationGroupCode: currentGroup.locationGroupCode,
        siteIds: currentGroup.siteIds,
        name: currentGroup.name,
        locationCodes: updatedCodes,
      },
    };

    // 4. Call update API
    const response = await api.updateLocationGroup(payload);

    console.log("Success: Successfully updated group (location removed)!");
    console.log(JSON.stringify(response, null, 2));
  } catch (err: any) {
    console.error("Error: Error updating location group:", err);
    if (err.apiError) console.error("API Error:", err.apiError);
  }
}

// Example run
removeStoreFromGroup("SGFG", "W002");

// Usage
// removeStoreFromGroup("SGFG", "W002");

​
Example 5: Delete a Location Group

Permanently remove a location group. This does not delete the individual locations within it. 
// ... imports and configuration setup ...
import { Configuration } from "@kibocommerce/rest-sdk";
import { LocationGroupApi } from "@kibocommerce/rest-sdk/clients/LocationAdmin/apis/LocationGroupApi.js";;

async function deleteLocationGroup(groupCode: string) {
  const api = new LocationGroupApi(configuration);
  console.log(`Deleting location group '${groupCode}'...`);

  try {
    // Call delete endpoint — no body is returned
    await api.deleteLocationGroup({ locationGroupCode: groupCode });

    console.log(`Successfully deleted location group '${groupCode}'.`);
  } catch (err: any) {
    console.error("Error: Error deleting location group:", err);
    if (err.apiError?.errorCode === "ITEM_NOT_FOUND") {
      console.error(`No location group found with code '${groupCode}'.`);
    }
  }
}

// Example run
deleteLocationGroup("SGFG");

// Usage
// deleteLocationGroup("SGFG");

​
Troubleshooting Your Location Group Implementation

​
Reading Kibo Error Messages

// Actual error structure from Kibo API documentation
interface KiboApiError {
  body: {
    message: string;
    errorCode: string;           // e.g., "ITEM_NOT_FOUND"
    correlationId: string;
  }
}
Common Error Codes for Location Groups:
  • ITEM_NOT_FOUND: You tried to get, update, or delete a location group using a locationGroupCode that does not exist.
  • ITEM_ALREADY_EXISTS: You tried to addLocationGroup with a locationGroupCode that is already in use. Codes must be unique.
  • VALIDATION_ERROR: The request body is invalid. The most common cause is including a locationCode in the locationCodes array that does not correspond to an existing Location in your Kibo tenant.
  • REQUIRED_FIELD_MISSING: You tried to create a group without a locationGroupCode or name.

​
Common Development Issues

Issue 1: My updateLocationGroup call is wiping out other settings.
  • Why it happens: The PUT operation for updating a location group expects the entire LocationGroup object in the payload. If you send only the field you want to change (e.g., { "locationCodes": [...] }), Kibo will interpret the missing fields (like name) as null and clear them.
  • How to fix it: Always perform a GET on the location group first, modify the retrieved object in your code, and then PUT the complete, modified object back.
  • How to avoid it: Follow the “Read-Modify-Write” pattern shown in Examples 2 and 4.
Issue 2: I created a group, but it’s not being used for fulfillment.
  • Why it happens: Creating a LocationGroup is just step one. You also need to configure Kibo’s Order Management system to use that group in its fulfillment logic.
  • How to fix it: In the Kibo Admin, navigate to Main > Orders > Settings. Here you can configure Order Routing and define which location groups should be used for sourcing inventory.
  • API Reference: The APIs for managing fulfillment settings are separate from the LocationGroupApi. Look under the Commerce/Settings and Commerce/Orders API groups for more advanced configuration.

​
Debugging Checklist

  1. Check the locationGroupCode: Is it an exact string match, including case?
  2. Validate locationCodes: Before creating or updating a group, are you sure every single locationCode in your array exists in the Kibo tenant?
  3. Verify API Client: Are you using LocationGroupApi from the @kibocommerce/rest-sdk/clients/Tenant package?
  4. Check Permissions: Do your API credentials have the necessary administrative permissions to manage tenant-level settings?
  5. Use the Read-Modify-Write Pattern: For updates, are you fetching the object first to avoid accidental data loss?