Kibo

Kibo Commerce Developer Documentation: Product Tagging & Enrichment Pipeline

Welcome to the Helium Pulse developer documentation for Kibo Commerce integration. This guide walks you through the end-to-end setup required to enable automated product tagging and enrichment for Kibo Commerce instances. Brands using this integration will configure an API client via Kibo's Dev Center, which enables our system to securely access their store data, enrich product metadata using AI by flattening complex tag structures, and sync it back seamlessly as Kibo Product Attributes.

1. App Installation by Brands

1.1 Installation via Application Keys

To enable our integration, you will configure an API Client (Application) within your Kibo Commerce Dev Center.
From the Dev Center, you will obtain the Application (Client) ID and Client Secret associated with your application.
Helium Pulse will use these credentials to authenticate with the Kibo Commerce API, typically through an OAuth 2.0 client credentials grant flow, to obtain an access token. This access token allows us to perform enrichment and synchronization tasks.

1.2 Required Permissions (Behaviors)

Our application requires specific "behaviors" (permissions) to be granted to the API Client in Kibo Commerce. These behaviors enable us to interact with product and attribute data.

Commonly required behaviors include:

mozu.catalog.products.read: Allows fetching product information, including product details and existing properties.
mozu.catalog.products.update: Enables updating product data, including adding or modifying product attributes (properties) and native product tags.
mozu.catalog.attributes.read: Permits reading product attribute definitions (schema).
mozu.catalog.attributes.manage: Grants permissions to create, update, and delete product attribute definitions, and manage their vocabulary values. This is crucial for creating our custom enrichment attributes.
mozu.catalog.attributedefinition.producttypes.read: Allows reading product type definitions and their associated properties.
mozu.catalog.attributedefinition.producttypes.manage: Provides permissions to add or remove attributes from product types, ensuring our custom attributes are properly associated.

These behaviors collectively allow us to fetch product data, manage product attributes (our enrichment data), associate attributes with product types, and update existing products with AI-generated tags and enriched information.

2. Product Fetching

2.1 Fetch Products via Kibo Admin REST API

We use Kibo Commerce's Admin REST API to fetch your store’s products in batches, utilizing startIndex and pageSize for pagination.

GET /api/commerce/catalog/admin/products?startIndex=0&pageSize=200

2.2 Example Request (Node.js)

const axios = require('axios');

async function getAccessToken(authHost, clientId, clientSecret, tenantId) {
  const tokenUrl = `https://${authHost}/api/platform/applications/authtickets/oauth`;
  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString('base64');

  const response = await axios.post(tokenUrl, 'grant_type=client_credentials', {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${credentials}`,
      'x-vol-tenant': tenantId // Tenant ID is often required
    }
  });
  return response.data.access_token;
}

async function fetchProducts(apiHost, accessToken, tenantId, siteId, startIndex = 0, pageSize = 200) {
  const url = `https://${apiHost}/api/commerce/catalog/admin/products?startIndex=${startIndex}&pageSize=${pageSize}`;
  const response = await axios.get(url, {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-vol-tenant': tenantId, // Tenant ID is crucial
      'x-vol-site': siteId,     // Site ID is often crucial
      'Content-Type': 'application/json',
    }
  });
  return response.data.items; // Kibo typically returns results in an 'items' array
}

// Example usage
// const accessToken = await getAccessToken('home.mozu.com', 'YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET', 'YOUR_TENANT_ID');
// const products = await fetchProducts('t1234-s1234.sandbox.mozu.com', accessToken, 'YOUR_TENANT_ID', 'YOUR_SITE_ID');

3. Change Detection & Sync Triggers

3.1 Webhook Support (Optional)

We optionally subscribe to Kibo Commerce webhook events to detect product changes in near real-time.

Relevant event categories/events include:

product.created
product.updated

When a webhook event is triggered, Kibo sends an HTTP POST notification with a limited payload. We then use the provided entityId (product code) to fetch the full product details via the Kibo API.

3.2 Daily Sync Option

For instances not utilizing webhooks, we perform a scheduled full or incremental sync once a day. Kibo products include a lastModifiedDate field which can be used for incremental updates. We typically fetch all products updated since the last sync.

GET /api/commerce/catalog/admin/products?filter=lastModifiedDate gt 'YYYY-MM-DDTHH:MM:SSZ'&startIndex=0&pageSize=200

4. Enrichment Pipeline & Data Flattening

Once products are fetched, our AI pipeline:

Analyzes product title, product code, product type, attributes, descriptions, and images.
Generates a rich, structured JSON object containing tags related to persona, usage, functional aspects, and visual details (see example below).
Flattens this JSON object: Nested keys are combined with underscores. The Kibo attribute FQN (Fully Qualified Name) will then be constructed using tenant~h_your_flattened_key. For example, tags.visual.color.primary.value becomes tenant~h_tags_visual_color_primary_value.

Example AI-Generated Tag Object:

{
    "sector": "apparel",
    "subcategory": "kurta",
    "category": "tops",
    "tags": {
        "persona": {
            "age_group": ["young adults", "adults"],
            "price_range": "mid-range",
            "gender": ["female"]
        },
        "usage": {
            "season": ["spring", "summer"],
            "occasions": ["everyday", "casual"]
        },
        "functional": {
            "eco_friendly": false
        },
        "visual": {
            "pattern": "checked",
            "material": ["viscose"],
            "color": {
                "primary": {
                    "value": "green",
                    "shade": "medium"
                }
            }
        }
    }
}

Flattened Kibo Attribute FQNs and Values:

tenant~h_sector: "apparel"
tenant~h_subcategory: "kurta"
tenant~h_category: "tops"
tenant~h_tags_persona_age_group: ["young adults", "adults"] (Handled as multi-value attribute)
tenant~h_tags_persona_price_range: "mid-range"
tenant~h_tags_persona_gender: ["female"]
tenant~h_tags_usage_season: ["spring", "summer"]
tenant~h_tags_usage_occasions: ["everyday", "casual"]
tenant~h_tags_functional_eco_friendly: false (Boolean, stored as per Kibo attribute type)
tenant~h_tags_visual_pattern: "checked"
tenant~h_tags_visual_material: ["viscose"]
tenant~h_tags_visual_color_primary_value: "green"
tenant~h_tags_visual_color_primary_shade: "medium"

5. Sync to Kibo (Product Attributes)

5.1 Attribute Structure and Definitions

In Kibo Commerce, enriched data is stored as custom "product attributes." These attributes (e.g., tenant~h_category, tenant~h_tags_persona_age_group) must first be defined in the Kibo Admin UI under System > Schema > Product Attributes or via the Attributes API. Once defined, they can be assigned values to products.

Creating/Ensuring Attribute Definitions: Before updating products, Helium Pulse ensures these attributes exist. Example API call to create an attribute:

POST /api/commerce/catalog/admin/attributedefinition/attributes

Example 1: Text Attribute (tenant~h_tags_visual_color_primary_value)

{
  "namespace": "tenant", // Or your specific namespace
  "attributeCode": "h_tags_visual_color_primary_value",
  "adminName": "Helium - Visual Primary Color",
  "inputType": "TextBox", // For single text values
  "dataType": "String",
  "valueType": "AdminEntered",
  "isProperty": true,
  "isOption": false
}

Example 2: Multi-Value Text Attribute (tenant~h_tags_persona_age_group)

{
  "namespace": "tenant",
  "attributeCode": "h_tags_persona_age_group",
  "adminName": "Helium - Persona Age Group",
  "inputType": "List", // Or other appropriate multi-value input type like "Checkbox" if predefined options are managed
  "dataType": "String", // If storing free-form strings
  "valueType": "AdminEntered", // Or "Predefined" if managing vocabulary values
  "isProperty": true,
  "isOption": false
  // For "List" with "Predefined" values, vocabulary values would be managed.
  // If "AdminEntered", the values are directly set on the product.
}

Example 3: Boolean Attribute (tenant~h_tags_functional_eco_friendly)

{
  "namespace": "tenant",
  "attributeCode": "h_tags_functional_eco_friendly",
  "adminName": "Helium - Functional Eco-Friendly",
  "inputType": "YesNo", // For boolean values
  "dataType": "Bool",
  "valueType": "AdminEntered",
  "isProperty": true,
  "isOption": false
}
```> The `attributeFQN` (Fully Qualified Name) will be `tenant~h_your_flattened_key`. The `namespace` part of the FQN is typically `tenant` but can be customized.

### 5.2 Create/Update Product Attributes (Properties)

We use the `PUT /api/commerce/catalog/admin/products/{productCode}` endpoint to update a product, including its custom attributes (referred to as `properties` in the product payload).

```http
PUT /api/commerce/catalog/admin/products/PRODUCT_CODE_123

{
  "productCode": "PRODUCT_CODE_123",
  "productName": "Example Enriched Product",
  // ... other existing product fields ...
  "properties": [
    // Example of existing properties (if any)
    // {
    //   "attributeFQN": "tenant~some_other_attribute",
    //   "values": [{"value": "existing_value"}]
    // },
    // Helium Pulse added/updated properties:
    {
      "attributeFQN": "tenant~h_sector",
      "values": [
        {"value": "apparel"}
      ]
    },
    {
      "attributeFQN": "tenant~h_tags_persona_age_group",
      "values": [ // For multi-value attributes
        {"value": "young adults"},
        {"value": "adults"}
      ]
    },
    {
      "attributeFQN": "tenant~h_tags_persona_price_range",
      "values": [
        {"value": "mid-range"}
      ]
    },
    {
      "attributeFQN": "tenant~h_tags_functional_eco_friendly",
      "values": [ // For boolean attributes
        {"value": false}
      ]
    },
    {
      "attributeFQN": "tenant~h_tags_visual_color_primary_value",
      "values": [
        {"value": "green"}
      ]
    }
    // ... other Helium attributes based on the flattened data
  ]
}

When updating, we typically send the complete list of properties for the product, including existing ones we don't manage and the Helium-managed ones with their new values. Alternatively, individual property updates can be done via POST or PUT to /api/commerce/catalog/admin/products/{productCode}/properties/{attributeFQN}.

6. Optional: Native Tag Injection

Kibo Commerce does not have a distinct "tags" field in the same way as some other platforms. The primary method for adding descriptive keywords or tags is by using Product Attributes as described in Section 5. For searchability, these attributes should be configured as searchable within Kibo.

If a generic "keywords" or "tags" attribute (e.g., tenant~h_general_keywords) is desired, we would treat it like any other multi-value attribute:

Ensure tenant~h_general_keywords attribute is defined (likely as a multi-value text attribute).
Populate it with the top 2-3 most salient keywords.

Example in product update payload:

    // ... inside "properties" array
    {
      "attributeFQN": "tenant~h_general_keywords",
      "values": [
        {"value": "kurta"},
        {"value": "green top"},
        {"value": "casual apparel"}
      ]
    }

7. Daily Enrichment Summary

7.1 Delta CSV & Summary Report

Every enrichment cycle creates a CSV with the delta changes.
Includes: Product Code, updated attribute FQNs (e.g., tenant~h_tags_visual_pattern), new values, timestamp.

7.2 Email Notification

An automated summary email is sent daily to your brand team.
It includes the number of products enriched and a downloadable CSV report.

8. Best Practices

Rate Limits: Kibo Commerce APIs have rate limits. We implement robust throttling and exponential backoff strategies to ensure we remain within permissible API usage limits.
Redundant Sync Avoidance: We hash each product’s relevant metadata and skip updates unless content has demonstrably changed, reducing unnecessary API calls.
Error Resilience: We incorporate comprehensive retry logic with exponential backoff and circuit breakers to handle transient API errors.
Tenant and Site Context: All API calls are made with the appropriate x-vol-tenant and x-vol-site headers to ensure operations are performed within the correct tenant and site context.
Attribute Management: Using the h_ prefix within the attribute code (e.g., tenant~h_sector) ensures Helium Pulse-generated attributes are easily identifiable. Proper definition of attribute types (text, boolean, list for multi-value) is crucial.
Testing: Our systems are validated on Kibo Commerce sandbox environments and development instances to ensure seamless integration before production deployment.

9. Technical References

This documentation can be extended to include:

Detailed management of attribute vocabulary values for predefined list attributes.
Client-side SDK integration for deeper brand-side observability.
Webhook signature validation.
Advanced error logging and structured retry handling.

For any questions, please contact your Helium Pulse onboarding engineer.

PreviousShopify NextBigCommerce

Last updated 14 days ago