Download the PHP package orangecat/module-prices-list without Composer

Orangecat_PricesList

Customer-specific B2B price lists with volume tiers, multi-list resolution, and import support.

Module: Orangecat_PricesList Version: 1.0.0 License: OSL-3.0 Author: Oliverio Gombert [email protected]

Table of Contents

1. Overview
2. Theme Compatibility
3. Requirements
4. Installation
5. What Gets Installed
6. Configuration
7. Store Admin Guide
8. Developer Guide
9. REST API
10. Frontend Routes Reference
11. DevOps & Integrator Notes

Overview

Orangecat_PricesList provides a named, reusable price list system for Magento 2 B2B stores. Each price list contains per-SKU pricing rules (fixed price, percentage discount, or fixed amount discount) with optional volume tiers based on minimum quantity. Price lists are assigned to companies with a numeric priority that controls which list wins when a customer belongs to a company with multiple assigned lists.

The module also exposes a CSV import pipeline for bulk price management and a full REST API for integrations.

Responsibilities:

• Create and manage named price lists with date-bounded validity windows
• Define per-SKU pricing rules supporting three discount types and volume tiers
• Assign one or more price lists to a company with individual priority values
• Resolve the effective price for a SKU/company/qty combination via Cascade or Weight mode
• Register a PricesListCalculator into the Orangecat_Prices calculator pool
• Provide CSV bulk import for price list items via the native Magento import pipeline
• Expose a complete REST API for price list, item, and company-association management

Position in the Orangecat B2B Dependency Chain

Price Resolution Modes

When a company has more than one price list, the calculator resolves the effective price using the configured mode:

In both modes, a list entry only qualifies if the cart quantity is ≥ the entry's qty threshold. Higher priority value = higher precedence.

Discount Types

All computed prices are floor-clamped to 0.

Theme Compatibility

This module has no frontend (storefront) templates. Price calculation happens server-side inside Orangecat_Prices; the rendered price on the product page depends on how Orangecat_Prices injects the calculated price into the theme. No theme-specific work is required in this module.

Requirements

Installation

This module ships as a git submodule inside the B2B SDK repository.

What Gets Installed

Database Tables

priceslist

Unique constraint on code.

priceslist_item

Unique constraint on (price_list_id, sku, qty) — enables volume tiers per SKU.

priceslist_company

Unique constraint on (company_id, price_list_id).

EAV Attributes

None.

Data Patches

None. No default records, roles, or CMS pages are created on install.

Configuration

Section: Prices > Price Lists Configuration

Navigate to Stores → Configuration → Prices → Price Lists Configuration.

Config paths:

Both settings are scoped to Default / Website / Store View.

Store Admin Guide

Navigating to Price Lists

Catalog → Manage Price Lists (added by this module under the Orangecat_Prices::base parent menu).

Creating a Price List

1. Go to Catalog → Manage Price Lists.
2. Click Add New Price List.
3. Fill in:
   • Name — human-readable label.
   • Code — unique slug used in the API and CSV import (e.g. B2B-WHOLESALE).
   • Is Active — set to Active to make this list available for assignment.
   • Description — optional internal note.
   • Start Date / End Date — optional validity window (leave blank for no limit).
4. Click Save and Continue Edit to save and remain on the form.

Adding Products to a Price List

After saving the price list (so an entity_id exists):

1. Inside the price list form, scroll to the Items section.
2. Click Add Products to open the product selection grid.
3. Select one or more products and click Add Selected.
4. A dialog appears for each selected product. For each row:
   • Choose Discount Type (Fixed Price Override, Percentage Discount, Fixed Amount Discount).
   • Enter Amount (the price, percentage, or discount value).
   • Enter Qty — the minimum cart quantity required to unlock this tier. Use 1 for the base price.
5. Click Confirm & Add to persist the rows.

To add a volume tier for the same SKU, add the same SKU again with a higher Qty value.

Existing items can be edited inline in the items grid or deleted individually with Delete or in bulk with Delete Selected.

Assigning Price Lists to a Company

1. Go to Companies → (select a company) → Edit.
2. Open the Price Lists tab.
3. The grid shows currently assigned lists. Click Reset Filter to see all available lists.
4. Check the checkbox next to each list to assign it.
5. Set the Priority value for each assigned list. Higher values take precedence.
6. Click Save Company. The assignments are persisted atomically.

Bulk Import via CSV

1. Go to System → Import.
2. Set Entity Type to Price List Items.
3. Select a Behavior: Add/Update, Replace, or Delete.
4. Upload a CSV file with columns: price_list_code, sku, qty, discount_type, amount.
5. Click Check Data to validate, then Import to execute.

Sample CSV (Files/Sample/priceslist_item.csv):

Validation rules:

• price_list_code must exist in priceslist.
• sku must exist in the product catalog.
• discount_type must be one of fixed_price, fixed_amount, percentage.
• qty and amount are required numeric fields.

Developer Guide

Module Structure

Key Classes

Service Contracts

Calculator

Model\Calculator\PricesListCalculator implements Orangecat\Prices\Api\PriceCalculatorInterface and is registered into Orangecat\Prices\Model\CalculatorPool via di.xml. The orchestrator in Orangecat_Prices calls calculate(sku, qty, companyId, basePrice) on each registered calculator.

Returns null when:

• The module is disabled in config.
• The company has no price lists assigned.
• No price list contains the requested SKU.
• No entry satisfies the quantity threshold.

Observers

None. This module registers no event observers.

Plugins

Admin JS Components

Email Templates

None.

ACL Resources

There is no etc/acl.xml in this module. All admin controllers and REST API routes reference the resource Orangecat_PricesList::priceslist. This resource must be defined in a parent module or added manually if fine-grained ACL control is required. Admin users with full access will have access to all price list actions.

Adding Custom Logic

• Custom discount type: Add a new constant to Model\Config\Source\DiscountType and handle the new value in Model\Calculator\PricesListCalculator::calculate() and getTiers().
• Custom calculator: Implement Orangecat\Prices\Api\PriceCalculatorInterface and register it in Orangecat\Prices\Model\CalculatorPool via your module's di.xml. No changes to this module are needed.
• Post-assignment hook: Add an afterExecute plugin on Model\PriceListCompanyManagement::associate to trigger downstream events (cache warm-up, ERP sync, etc.).

REST API

All endpoints require an admin integration token with the Orangecat_PricesList::priceslist ACL resource.

Price List CRUD

Price List Items

Company Associations

Examples

Create a price list:

Add items with a volume tier:

Assign to a company with priority:

Frontend Routes Reference

This module has no frontend (storefront) routes. All controllers are under the adminhtml area.

Admin route prefix: orangecat_priceslist

DevOps & Integrator Notes

Deployment Checklist

Integration Token Scope

Minimum ACL permission required for all REST API operations: Orangecat_PricesList::priceslist.

Disabling Without Uninstalling

When disabled, PricesListCalculator::calculate() returns null immediately, so the Orangecat_Prices orchestrator falls back to the next registered calculator or the native Magento price. No data is removed.

Data Integrity Notes

• Deleting a price list cascades to all priceslist_item rows for that list.
• Deleting a company (from mycompany) cascades to all priceslist_company rows for that company.
• Deleting a price list cascades to all priceslist_company rows linking it to companies.
• The unique constraint on priceslist_item(price_list_id, sku, qty) enforces that each price list has at most one price entry per SKU/quantity tier. The import uses INSERT ON DUPLICATE KEY UPDATE to upsert entries cleanly.
• The code field on priceslist is unique across the entire installation (no store-scope). Use descriptive, stable codes in integrations — the REST API and CSV import both reference price lists by code.