KiboCommerce Conceptual Guide: Pricing
Developer Reference
See the Pricing API documentation for programmatic access
1. Strategic Overview
This guide provides a comprehensive conceptual overview of the Price List system in KiboCommerce. This system is the engine that drives all pricing and product entitlement strategies on the platform. It moves far beyond simple price tags, enabling businesses to execute complex, multi-layered pricing based on customer segments, purchase volume, and specific commercial agreements.- Concept Definition: A Price List is a collection of rules that can override a product’s standard catalog price and control its visibility for specific shoppers or contexts.
- Business Context: Mastering the Price List system allows a business to implement sophisticated pricing strategies for B2C (e.g., VIP tiers, scheduled sales) and B2B (e.g., negotiated contract pricing, curated catalogs) commerce, directly impacting revenue, customer loyalty, and competitive positioning.
- Scope Statement: This document covers the complete functionality of Price Lists, including their core settings, the inheritance model, the resolution logic that determines which price list applies, the use of exclusivity for product entitlement, and the detailed configuration of individual price entries.
2. Core Concepts Explained: Dynamic and Targeted Pricing
After defining your products, the next step is to determine their price. In KiboCommerce, this is managed through a flexible and hierarchical Price List system. A Price List is not just a list of prices; it’s a powerful rules engine.2.1 The Price List: A Layer of Pricing Rules
A Price List is a set of “price entries,” where each entry can override the default catalog price for a specific product under certain conditions. You can have many price lists, each designed for a different purpose, such as a “Wholesale Price List,” a “VIP Customer Price List,” or a “Holiday Sale Price List.” Business Application Example:- Industry: Direct-to-Consumer (DTC) Brand
- Scenario: A brand’s flagship product has a standard catalog price of $100. They create a “Loyalty Club” Price List. Within that list, they create a single price entry for the flagship product, setting its price to $85. Now, any customer who is part of the Loyalty Club will see the $85 price instead of the standard $100.
2.2 Inheritance: Building Tiered Pricing with Parent Price Lists
A cornerstone of the Price List architecture is inheritance. A price list can be assigned a Parent Price List, from which it will inherit all price entries. The child list can then be used to override just a few of those inherited prices, creating a tiered structure that is efficient and easy to manage. Business Application Example:- Industry: B2B Office Supply Distributor
- Scenario: The distributor creates a “Silver Tier” Price List with standard wholesale pricing. They then create a “Gold Tier” Price List and set its parent to the “Silver Tier” list. The “Gold Tier” list only needs to contain entries for the 10 products where Gold customers get an additional 5% discount. For all other thousands of products, it automatically falls back to the pricing inherited from the Silver Tier list, avoiding massive data duplication.
2.3 Resolution: How KiboCommerce Determines the Correct Price
When a shopper visits your site, KiboCommerce runs a “resolution” process to determine which price list (and therefore which price) is the correct one to show them. This is controlled by a few key settings.- Customer Segments: The primary method of targeting. A Price List can be assigned to one or more customer groups (e.g., “Wholesale Accounts”). When a user from that segment logs in, the price list is applied.
- Resolution Rank: An integer used to break ties. If a shopper belongs to two segments, each with a different price list, the list with the lowest rank number wins.
- Default Price List: A price list can be marked as the “default” for a site. This is the fallback price that is shown to anonymous visitors or any shopper who doesn’t qualify for a more specific price list.
- Scenario: A shopper is in both the “Loyalty Club” (Rank 10) and “Email Subscribers” (Rank 20) segments. Because the “Loyalty Club” Price List has a lower rank, its prices will be shown to the customer, even if the other list also applies.
2.4 Exclusivity: Using Price Lists for Product Entitlement
The Exclusive setting transforms a Price List from a pricing tool into a powerful catalog visibility and entitlement engine. When a shopper resolves to a price list marked as Exclusive, they can only view and purchase the products explicitly defined in that price list (and its parents). All other products in the catalog become invisible to them. This is a key feature for B2B commerce, as it allows you to define a complete commercial agreement—both the curated product assortment and the negotiated pricing—in a single place. Business Application Example:- Industry: Medical Device Manufacturer
- Scenario: The manufacturer has a large corporate client that is only permitted to purchase a specific set of 50 pre-approved devices. They create an Exclusive Price List named “Client ABC Contract,” add only those 50 devices with their contract pricing, and assign it to the client’s customer segment. When employees from Client ABC log in, the storefront transforms into a curated portal showing only the products they are entitled to buy, at the prices they are entitled to pay.
3. Functional Components & Configuration Deep Dive
This section details every configurable attribute for Price Lists and the Price Entries within them.3.1 Price List Configuration
These are the main settings that define a Price List’s behavior.| Name | Business Purpose | Available Options/Data Type | Concrete Example |
|---|---|---|---|
| Name / Code | Human-readable name and unique system identifier for the price list. | Text | Name: “Wholesale Tier 1”, Code: “wholesale_t1” |
| Status | Enables or disables the price list. | Active / Disabled | A disabled list is not applied but can still be inherited from by its children. |
| Parent Price List | Establishes an inheritance relationship with another price list. | Dropdown of existing price lists. | Setting “Wholesale Base” as the parent for the “Wholesale Tier 1” list. |
| Exclusive | Restricts a shopper’s view to only the products contained within this price list. | Yes/No Toggle | Setting this to “Yes” for a B2B client’s contract price list. |
| Resolvable | A master switch allowing a price list to be directly applied to a shopper. | Yes/No Toggle | Unchecking this for a parent list that only exists to be inherited from can improve performance. |
| Resolution Rank | An integer used to break ties when a shopper qualifies for multiple price lists (lower number wins). | Integer | Setting a “VIP” list to rank 5 and a “General Sale” list to rank 10 ensures VIPs always get their price. |
| Default | Designates the price list as the fallback for a site when no other list applies. | Yes/No Toggle | Setting the “Standard Retail Prices” list as the default for your main B2C site. |
3.2 Price Entry Configuration
Each line item within a Price List is a Price Entry, which contains the specific details of a price override.Conditions
| Name | Business Purpose | Available Options/Data Type | Concrete Example |
|---|---|---|---|
| Product | The specific product (or variant) whose price is being overridden. | Product Selector | Selecting the “Pro-Grade Hiking Boots - Size 10” variant. |
| Currency Code | The currency for this specific price override. | Dropdown of ISO currency codes. | Setting the price in EUR for a European price list. |
| Active Start/End Date | Schedules the price entry to be effective only for a specific period. | Date/Time Pickers | Setting a sale price to be active from Friday at 9 AM to Sunday at 11 PM for a weekend flash sale. |
Adjustments
This section specifies which pricing values are being overridden. You can adjust one or more of the following:| Attribute Name | Business Purpose | Concrete Example |
|---|---|---|
| Price | Overrides the standard list price of the product. | Changing the base price from $199 to $189. |
| Sale Price | Overrides the sale price, often used to show a “slash-through” price on the storefront. | Setting a Sale Price of $149 while leaving the list Price at $199. |
| MSRP | Overrides the Manufacturer’s Suggested Retail Price. | Adjusting the MSRP to comply with a manufacturer’s policy. |
| Cost | Overrides the internal cost of the product for reporting purposes. | Updating the cost from $50 to $52 after a supplier price increase. |
| MAP | Overrides the Minimum Advertised Price. | Setting a MAP of $179 to prevent the item from being sold below a certain threshold. |
| Volume Pricing | Allows you to set tiered pricing based on the quantity purchased. | Setting a price of $10 each for 1-9 units, $9 each for 10-49 units, and $8 each for 50+ units. |
4. Key Capabilities and Business Applications
This section details the practical value of the Price List system by exploring its core capabilities. Capability: Tiered B2B and Wholesale Pricing- Functional Explanation: The parent-child inheritance model allows for the efficient creation of complex, tiered pricing structures. A base price list can define standard wholesale pricing, and subsequent child price lists for different customer tiers (e.g., Gold, Platinum) only need to contain the specific price overrides for that tier, inheriting all other prices.
- Business Application Example:
- Industry: B2B Industrial Distributor
- Scenario: A distributor has three tiers of resellers. They create a base “Reseller” Price List. They then create a “Premier Reseller” list that inherits from the base list but overrides prices on 50 key products. Finally, they create a “Platinum Reseller” list that inherits from the “Premier” list, giving those top partners even deeper discounts on 10 specific items. This structure is easy to manage and ensures pricing is always applied correctly based on the reseller’s tier.
- Functional Explanation: Price entries can be scheduled with specific start and end dates. This allows a business to set up an entire promotion, such as a Black Friday sale, in advance. The promotional prices will automatically activate and deactivate at the scheduled times without any manual intervention.
- Business Application Example:
- Industry: DTC Brand
- Scenario: A DTC brand plans a 48-hour flash sale. A merchandiser creates a “Flash Sale” Price List and adds sale prices for 20 products. They schedule every price entry to activate at midnight on Friday and deactivate at 11:59 PM on Saturday. The sale runs automatically, and prices revert to normal after it ends, eliminating the need for staff to work overnight to manage the promotion.
- Functional Explanation: The Exclusive setting is a powerful entitlement tool. When a Price List is marked as exclusive, any customer who resolves to it can only see and purchase the products contained within that list. This effectively transforms the public storefront into a private, curated catalog for that specific customer.
- Business Application Example:
- Industry: Marketplace Operator
- Scenario: A marketplace operator has a large corporate partner who wants a private portal for their employees to buy company-approved office supplies. The operator creates an Exclusive Price List containing only the 100 approved items, with the partner’s negotiated contract pricing. When the partner’s employees log in, they see a custom portal with only the products they are allowed to buy, simplifying their purchasing process and ensuring compliance with company policy.
- Functional Explanation: The pricing for subscription products and their recurring continuity orders is determined by Price Lists. A business can create specific price lists that define the recurring price for a product, which may be different from its one-time purchase price. A recommended best practice is to create an empty parent price list for all subscription-related price lists. This allows subscription-specific discounts to be tied to the parent list, ensuring they are inherited correctly by all child price lists that govern subscription pricing.
- Business Application Example:
- Industry: DTC Coffee Retailer
- Scenario: A coffee retailer wants to offer a “Subscribe & Save 15%” incentive. They create a “Coffee Subscribers” Price List. For their most popular coffee blend, which has a standard catalog price of $20, they create a price entry in this list and set the Sale Price to $17.00. This price list is applied to any customer who chooses the subscription option for that product, ensuring they receive the discounted price on their initial order and all subsequent recurring orders.
- Functional Explanation: Price Lists serve as the starting point for the B2B quoting process. When a buyer or seller initiates a quote, the system automatically applies the B2B account’s specific Price List to populate the initial item prices. This can be a price list assigned directly to the B2B account, which takes precedence, or a price list determined by the customer segments the account belongs to. From there, the seller can make manual adjustments to the pricing within the quote as part of the negotiation process with the buyer. If changes are made to the quote (like quantity or shipping), the system can re-evaluate the price list to ensure accuracy.
- Business Application Example:
- Industry: Manufacturing
- Scenario: A sales representative for a manufacturer creates a new quote for a long-standing B2B client. The client’s account has a “Gold Tier Partner” Price List assigned to it. As the rep adds products to the quote, the prices are automatically filled in from this Gold Tier list. The client requests a quote for a very large quantity and asks for better pricing on a key component. The sales rep edits the quote, applies a manual percentage adjustment to that one line item, and submits the revised quote back to the client for approval, blending automated contract pricing with manual negotiation.
5. Platform Integration Map
Price Lists are a transactional feature that integrates deeply with catalog, customer, and order data.- Upstream Dependencies:
- Catalogs & Products: Price Lists are created within the context of a Master Catalog. Price entries can only be created for products that exist in that catalog.
- Customer Segments: To target price lists to specific groups of shoppers, Customer Segments must be created and populated first.
- Sites: A Price List can be set as the default for one or more Sites.
- Downstream Impacts:
- Storefront Experience: The resolved price list directly controls the prices a shopper sees on category and product pages. Exclusive price lists also control product visibility.
- Cart & Checkout: The prices of items added to the cart are determined by the active price list.
- Order Management: When an order is placed, the system records which price list was used. This information is visible on the order details and is important for financial reporting and customer service.
- Search & Merchandizing: Price can be used as a filter or sorting option. The price ranges displayed are based on the indexed, resolvable price lists.
- Synergistic Features:
- Discounts: While Price Lists set the base price, the KiboCommerce discount engine can apply further promotions on top of the price list price (unless explicitly restricted).
- B2B Accounts: The B2B account management feature allows you to group individual buyers under a corporate account, which can then be added to a Customer Segment to receive specific price list entitlements.
6. Real-World Example: Onboarding a New B2B Client
Let’s walk through an end-to-end scenario of a B2B distributor setting up a custom pricing and catalog experience for a new, high-value corporate client.- The Business: “SupplyCore,” a distributor of maintenance and repair parts, onboards a new national client, “MegaCorp.” MegaCorp has negotiated special pricing and wants a simplified purchasing experience for its facility managers.
- Step 1: Creating the Customer Segment The first action is to create a new Customer Segment in KiboCommerce called “MegaCorp Accounts.” The account manager then adds all of MegaCorp’s registered user accounts to this segment. This group will be the target for all special rules.
- Step 2: Building the Exclusive, Curated Price List
MegaCorp is only allowed to purchase from a list of 500 pre-approved parts. The SupplyCore pricing manager creates a new Price List named “MegaCorp Contract Pricing.”
- In the settings, they check the Exclusive box. This is the key step that will hide all other products.
- They add 500 Price Entries, one for each approved part. In the adjustments for each entry, they input the specific, negotiated contract price for MegaCorp.
- For 20 of the most frequently purchased items, they also configure Volume Pricing, offering deeper discounts for buying in bulk.
- Step 3: Assigning and Prioritizing the Price List With the price list built, the manager assigns it to the “MegaCorp Accounts” Customer Segment. They also set the Resolution Rank to 5. This is a very high priority (a low number), ensuring that even if a MegaCorp user is also part of a general “Holiday Sale” segment (which might have a rank of 20), their specific contract pricing will always win and be applied.
- The Outcome:
When a MegaCorp facility manager logs into the SupplyCore website, their experience is completely transformed:
- The public catalog of 50,000 parts disappears. They can only search for and view the 500 parts on their exclusive price list.
- For every product they see, the price displayed is their unique, negotiated contract price.
- When they add one of the 20 key items to their cart, the price per unit automatically adjusts as they increase the quantity, reflecting the volume discount. This provides a secure, compliant, and user-friendly purchasing portal for the B2B client, all managed by a single, powerful Price List.
7. Related Conceptual Guides
For foundational knowledge and to understand the full impact of your pricing setup, refer to these related guides.- Catalog & Product Architecture
- Foundational Knowledge: The Catalog guide is a prerequisite. Price Lists are created within the context of a Master Catalog, and their price entries are applied to specific products defined in that catalog. You must have a product catalog before you can create pricing rules for it.
- Downstream Impacts: The Pricing concept directly impacts the visibility of the catalog. Using an “Exclusive” Price List will hide all products from a shopper except for those explicitly defined in the price list, effectively creating a private, entitled catalog.
- Complementary Strategies: The Catalog guide explains how to set a product’s base price (e.g., in a specific currency for a Child Catalog), while this Pricing guide explains how to override that base price for specific customer segments. They work together to create complex, multi-layered pricing for B2B and international markets.
- Search and Merchandizing
- Foundational Knowledge: This Pricing guide is a prerequisite for effective price-based merchandizing. The search engine indexes the prices from your “Resolvable” Price Lists, which is what powers the shopper’s ability to filter and sort products by price on a category page.
- Downstream Impacts: Your Price List settings directly control the faceted search experience. The price ranges shown in the “Price” filter are based on the values from your indexed price lists. This also impacts merchandizing, as “Dynamic Realtime Categories” can be built using the final sale price you define in a Price List.
- Complementary Strategies: The two concepts work together to automate promotions. You can create a time-bound “Flash Sale” Price List to set temporary sale prices. A “Dynamic Realtime Category” (a merchandizing tool) can then be set to automatically find and display all products whose sale price is active, creating a “Sale” page that runs itself.
- Promotions
- Foundational Knowledge: Pricing is the foundational step. The Price List determines the product’s base price before any discounts are applied. The Promotions engine then runs and applies discounts (e.g., “10% off”) on top of the price set by the Price List.
- Downstream Impacts: The Price List has a direct downstream impact: a price entry can be set to “Restrict Discounts.” This setting will block the Promotions engine from applying any further order-level or item-level discounts to that specific product, which is often used to protect margins on already-low B2B contract prices.
- Complementary Strategies: These two systems work in tandem to create layered offers. For example, a “VIP” Price List can give a loyal customer segment a permanent 10% off. A “Weekend Sale” Promotion can then be layered on top, giving that customer an additional 15% off, resulting in a special, compounded discount that rewards loyalty.