Download the PHP package orangecat/module-prices without Composer

Orangecat_Prices

B2B pricing engine orchestrator — calculator pool, conflict resolution, and frontend price injection.

Module: Orangecat_Prices 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. Buyer Guide (Frontend)
9. Developer Guide
10. REST API
11. Frontend Routes Reference
12. DevOps & Integrator Notes

Overview

Orangecat_Prices is the B2B pricing engine of the Orangecat suite. It does not store prices itself — it provides the infrastructure that downstream pricing modules (e.g., Orangecat_PricesList, Orangecat_PricesCompany) plug into to deliver company-specific prices to B2B buyers.

The module handles:

• A Calculator Pool that aggregates price calculators registered by downstream modules
• A Price Resolver that applies configurable conflict-resolution logic when multiple calculators return a price for the same product
• A Tier Price Resolver that aggregates quantity-based discount tiers across all calculators
• PHP-level price injection at three Magento hooks: product final price display, cart add, and quote-to-order conversion
• FPC/Varnish cache segmentation per company via HTTP context
• A frontend AJAX endpoint that resolves B2B prices for batches of products
• JavaScript widget mixins for Luma/RequireJS, Breeze, and Hyvä that update price displays without page reload

Position in the Orangecat B2B Dependency Chain

Orangecat_Prices depends on Orangecat_Company to resolve the company a logged-in customer belongs to. Orangecat_PricesList and Orangecat_PricesCompany register their calculators into this module's pool and provide the actual pricing data.

The Calculator Pool Pattern

This is the central architectural concept of the module. No prices are stored here. Downstream modules implement Orangecat\Prices\Api\PriceCalculatorInterface and register themselves in the CalculatorPool via di.xml. The PriceResolver calls each calculator for a given (SKU, qty, company) context and determines the winning price based on the configured Conflict Resolution Mode.

Two resolution modes are supported:

The same resolution logic applies to quantity tiers in TierPriceResolver.

Theme Compatibility

Requirements

Installation

Via Git Submodule (recommended for this project)

Enable the Module

Run inside the PHP container (reward shell):

Orangecat_Company must be installed and enabled before this module.

What Gets Installed

Database Tables

None. Orangecat_Prices introduces no database tables or schema changes. All pricing data is owned by downstream modules (Orangecat_PricesList, Orangecat_PricesCompany).

EAV Attributes

None.

Data Patches

None. No default records, roles, CMS pages, or seed data are created by this module.

Configuration

Path: Admin menu → Prices → Settings, or Stores > Configuration > Orangecat > Prices (B2B)

Global B2B Pricing Engine

Config paths:

Store Admin Guide

Enabling / Disabling the B2B Pricing Engine

1. Navigate to Admin menu → Prices → Settings (or Stores > Configuration > Orangecat > Prices (B2B)).
2. Set Enable B2B Pricing Engine to Yes or No.
3. Save configuration and flush cache.

When disabled, every B2B price override — flat prices and volume tiers — is suppressed for all users, including company members. All downstream pricing modules are silently ignored.

Choosing a Conflict Resolution Mode

This setting matters when more than one pricing module (e.g., Orangecat_PricesList plus a custom calculator) returns a price for the same product in the same company context:

• Lowest Price — always gives the buyer the best discount. Recommended default.
• Priority — the calculator with the highest sortOrder value in di.xml wins, regardless of which price is lower. Use when a specific pricing source must override all others unconditionally.

Tier Prices Toggle

When Use Company Tier Prices is enabled, the AJAX endpoint includes quantity tiers in its response and the frontend renders a "Buy X for $Y each" list on product detail pages. Disabling this setting reduces AJAX response size and database load when volume discounts are not configured.

Buyer Guide (Frontend)

B2B prices are applied automatically for any logged-in customer who belongs to a company. No buyer action is required.

• Product listing pages (PLP): A single batch AJAX request resolves prices for all products visible on the page. A brief loading state is applied to price boxes while the request is in flight.
• Product detail pages (PDP): The resolved B2B final price replaces the catalog price after page load. Volume tier prices ("Buy 5 for $9.00 each") appear below the main price block when configured. On configurable products, tier prices update automatically when the buyer selects a variant or swatch.
• Cart and checkout: The B2B price is enforced at the PHP level when items are added to the cart and when the quote is converted to an order. The correct company price is recorded on the order regardless of frontend state.

Logged-in customers who are not members of any company see standard catalog prices.

Developer Guide

Module Structure

Service Contract

PriceCalculatorInterface (Orangecat\Prices\Api\PriceCalculatorInterface)

Key Models

Config

PriceResolver

TierPriceResolver

Observers

Plugins

JS Components

Luma / RequireJS

Breeze Evolution

Hyvä

Email Templates

None. This module sends no transactional emails.

ACL Resources

Adding Custom Logic

• Register a new pricing source: Implement PriceCalculatorInterface, then register the class in Orangecat_Prices's CalculatorPool via your module's di.xml:

  The sortOrder value controls resolution order when resolution_mode is set to priority.

• Override resolution mode per scope: The prices/general/resolution_mode config supports website and store view scope. Override it in Stores > Configuration to apply different conflict strategies per store.
• Extend the AJAX response: Plugin afterExecute on Orangecat\Prices\Controller\Ajax\AjaxPrices to add extra keys to the JSON payload without modifying the core controller.

REST API

This module exposes no REST API endpoints. There is no webapi.xml. The AJAX pricing endpoint (prices/ajax/ajaxprices) is a standard frontend controller intended for storefront use only.

Frontend Routes Reference

AJAX Price Endpoint

URL: POST /prices/ajax/ajaxprices

Request body (JSON):

• All three arrays are optional. Pass tier_product_ids only on pages where tier price display is needed (PDP).
• Maximum 200 entries per array.

Response (JSON):

• configurable_prices is only present when configurable products are in the request.
• tier_prices is only present when tier_product_ids are passed and Use Company Tier Prices is enabled.
• bundle_prices is only present when bundle products are in the request.
• Guests receive { "is_logged_in": false, "prices": {} }.

DevOps & Integrator Notes

Deployment Checklist

Integration Token Scope

This module exposes no REST API endpoints. No integration token ACL permissions are required for this module specifically.

FPC / Varnish Cache Segmentation

HttpContextPlugin injects orangecat_company_id into Magento's HTTP Vary context. Both Varnish and Magento's built-in FPC automatically create separate cache buckets per company ID — no custom Varnish VCL is required. The plugin also fixes a core Magento FPC bug where Kernel::load and Kernel::process produce different cache keys for logged-in customers, causing perpetual cache misses.

Disabling Without Uninstalling

Downstream modules that register calculators must be disabled first:

When disabled, all B2B price overrides are inactive. Standard catalog prices are shown to all users, including company members.

Data Integrity

This module introduces no database tables or schema changes. Disabling or uninstalling it leaves no residual data in the database. All pricing data is owned and managed by the downstream modules.