Kibo Catalog API Developer Guide
Catalog
Understand catalog architecture and concepts
Master Catalogs
Configure master catalogs in the Admin UI
Category Attributes
Set up category attributes in the Admin UI
Understanding Catalog in Kibo
Kibo’s approach to catalog management is built on a foundation of reusability and inheritance. Instead of defining every product’s characteristics from scratch, Kibo uses a system of Attributes that are grouped into Product Types. A Product then inherits all the characteristics from its assigned Product Type. This layered, attribute-driven architecture is what makes Kibo’s catalog so powerful and flexible. It allows you to define a characteristic once (like “Color”) and reuse it across hundreds of products, ensuring consistency and dramatically simplifying maintenance.How This Domain Fits Into Kibo
The Catalog is the heart of your Kibo e-commerce ecosystem. It’s the central repository of all product information. This data directly feeds into other key domains:- Pricing: Prices are attached to products defined in the catalog.
- Inventory: Stock levels are tracked against specific products or product variations from the catalog.
- Search: The product attributes you define are used to power faceted search and filtering on the storefront.
- Orders: When a shopper makes a purchase, the order line items reference specific products from the catalog.
Prerequisites
- Kibo API credentials and basic setup
- Node.js 16+ with TypeScript
- Familiarity with REST APIs
What You’ll Learn
After completing this guide, you’ll understand:- How Kibo structures catalog data and operations (based on official API specs)
- The key patterns Kibo uses across all Catalog APIs (verified from apidocs.kibocommerce.com)
- Common workflows for building and managing a catalog (with accurate, tested examples)
- How to avoid the most common beginner mistakes
- How to read and navigate the official API documentation effectively
Kibo Catalog Fundamentals
How Kibo Organizes Catalog Data
Kibo’s catalog is a hierarchy. Understanding this structure is the key to mastering the API.- Attribute: The smallest piece of data, defining a characteristic (e.g., “Color,” “Size,” “Brand”). Attributes have a defined input type (text box, list, radio buttons).
- Product Type: A template or a blueprint for a group of similar products. It’s a collection of Attributes. For example, a “Shirt” Product Type might contain “Color,” “Size,” and “Material” Attributes.
- Product: The actual item you sell. Each product must be assigned a Product Type, from which it inherits all its attributes. You then provide values for those attributes at the product level.
- Category: A grouping of products for storefront navigation. Categories can be static (you manually assign products) or dynamic (products are automatically assigned based on rules).
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 singleConfiguration object containing your credentials (Client ID, Shared Secret, etc.). This object is then used to instantiate specific API clients. The clients will automatically handle the OAuth 2.0 token exchange behind the scenes for every API call.
Request/Response Structure:
When you create or update an object, you’ll send a JSON object in the request body that matches the documented schema. The response will almost always be the full object you just created or updated, including server-assigned values like an id or update timestamps.
Error Handling Approach:
If a request fails, the SDK will throw an error containing a JSON response with a specific errorCode, a descriptive message, and a correlationId that you can provide to Kibo support for faster troubleshooting.
Pagination and Filtering:
When you request a list of items (like products), the API response is paginated. You’ll use parameters like startIndex and pageSize to navigate through the data. You can also use a powerful filter parameter with a specific syntax to narrow down your results.
API Documentation Reference:
Throughout this guide, we’ll reference specific endpoints. Find complete specs at:
/api-overviews/openapi_catalog_admin_overview
Common Catalog Workflows
Kibo developers typically work with the Catalog in these scenarios:- Building the Foundation: Creating the necessary attributes and product types that will define all products.
- Populating the Catalog: Creating individual products, assigning them to product types, and setting their attribute values.
- Organizing for the Storefront: Placing products into categories to control how shoppers find them.
Creating an Attribute: The Kibo Way
When You Need This
You need this anytime you want to define a new, reusable characteristic for your products. This is the first step in building your catalog’s structure. For example, if you start selling apparel, you’ll need to create attributes for “Color” and “Size.”API Documentation Reference
- Endpoint:
POST /api/commerce/catalog/admin/categoryattributedefinition/attributes - Method:
POST - API Docs:
/api-reference/categoryattributedefinition/create-attribute
Understanding the Kibo Approach
Kibo treats attributes as first-class citizens. You define them independently of any product so they can be reused everywhere. A key concept is theattributeFQN (Fully Qualified Name), which acts as a unique ID. You also define the inputType (e.g., TextBox, List) which controls how a merchandiser will interact with this attribute in the admin UI.
Code Structure Walkthrough
Before we implement, let’s understand what we’re building:Step-by-Step Implementation
Step 1: Setting Up the FoundationAttribute schema required by the API. This object will contain details like the name, type, and administration settings for our new “Brand” attribute. The SDK client will serialize this into JSON and send it in the body of the POST request.
Step 3: The Core Implementation
What Just Happened? (Code Explanation)
- The setup phase involved creating a
Configurationinstance. This object is the single source of truth for your API credentials. - The data preparation followed Kibo’s pattern of creating a structured object (
brandAttribute) that mirrors the API’s expected JSON schema. - The API call used an instance of
ProductAttributesApi. This SDK pattern separates concerns, giving you a dedicated client for each API resource. ThecreateAttribute()method maps directly to thePOSToperation on the attributes endpoint. - The response handling correctly anticipates Kibo’s structured error response, making it easy to debug.
Common Beginner Mistakes
Mistake 1: Using a single, generic API client.admin@ prefix for attributeFQN.
How This Connects to Other Kibo Operations
Creating an attribute is the foundation for everything else:- Creating Product Types: You cannot create a Product Type without first having the Attributes you want to assign to it.
- Creating Products: The attributes of a product are inherited from its Product Type. This operation defines what is available to be inherited.
Advanced Catalog Patterns
When You’ve Mastered the Basics
Now let’s explore a sophisticated, multi-step workflow: adding a new color option to an existing product and activating the new product variations that result from it.Pattern 1: Dynamically Adding an Option and Activating Variations
Business Scenario: Your supplier has introduced a new color, “Kibo Yellow,” for an existing T-shirt. You need to add this color as a selectable option on the product page and make the new variations (e.g., “Kibo Yellow, Small,” “Kibo Yellow, Medium”) available for purchase with their own unique SKUs. Kibo’s Architecture Consideration: This is a multi-step process because Kibo’s data is normalized. The new color “Kibo Yellow” must be:- Added to the master list of all possible colors (Attribute Vocabulary).
- Associated with the T-shirt’s Product Type so other future T-shirts can also use it.
- Associated with the specific T-shirt Product itself as a selectable option.
- Used to generate and activate the new Product Variations.
POST /api/commerce/catalog/admin/attributedefinition/attributes/{attributeFQN}/vocabularyvaluesPUT /api/commerce/catalog/admin/producttypes/{productTypeId}/attributes/{attributeFQN}PUT /api/commerce/catalog/admin/products/{productCode}/options/{attributeFQN}PUT /api/commerce/catalog/admin/products/{productCode}/variations
Multiple Real-World Examples
Example 1: Create a Product TypeIntegrating Catalog with Other Kibo Domains
Catalog + Orders Integration
When a customer places an order, theOrder.items array contains product details. The item.product.productCode directly links back to the unique identifier of a product or variation in your catalog.
Catalog + Customer Data Integration
Customer accounts can have wishlists or purchase histories that reference products from the catalog via theirproductCode.
Troubleshooting Your Catalog Implementation
Reading Kibo Error Messages
ATTRIBUTE_FQN_ALREADY_EXISTS: You tried to create an attribute with anattributeFQNthat is already in use.VALIDATION_ERROR: The request body is missing a required field or contains a value of the wrong data type.PRODUCT_CODE_ALREADY_EXISTS: You tried to create a product with aproductCodethat already exists.ITEM_NOT_FOUND: You referenced an item that doesn’t exist, such as a non-existentproductTypeId.
Common Development Issues
Issue 1: My new product isn’t showing up on the storefront.- Why it happens: A product must be active, have a price, have inventory (if tracked), and be in a category.
- How to fix it: Verify each of these conditions using the API.
- API Reference:
/api-reference/productsv1/update-product
VALIDATION_ERROR.
- Why it happens: Most often, your
productUsageis incorrect, or you are missing a required field on thecontentobject, likeproductName. - How to fix it: Carefully compare every field in your request body to the schema on the API documentation for the
createProductendpoint. - API Reference:
/api-reference/productsv1/add-product
Debugging Checklist
When your Catalog implementation isn’t working:- Verify your
Configurationobject has the correct credentials. - Confirm your request body exactly matches the schema in the API docs.
- Check the
correlationIdin the error response. It’s the most useful piece of information for Kibo support. - Ensure you are instantiating and using the correct API client (e.g.,
ProductTypesApifor product types). - Validate that prerequisite objects exist (e.g., the attribute exists before you add it to a product type).

