Pricing & Costs
Matrix-based subsystem for configuring operational costs and selling prices per zone and weight range, with support for 4 tariff types, dual pricing operators, margin tracking, CSV import/export, and bulk operations.
Overview
Every shipping service has two interrelated data layers managed through this subsystem:
- Operational Costs: What the carrier charges Envia — a single matrix of zones × weight ranges with fuel configuration.
- Pricing: What Envia charges customers — 4 separate matrices (one per tariff type: basic, pro, enterprise, corporate), each with its own zone × weight range values.
The Pricing section depends on Costs: margin/markup indicators are calculated using the cost matrix, fuel percentage, and tax rules to derive the "graduated cost" against which prices are compared.
Key Concepts
| Concept | Description |
|---|---|
| Cost Matrix | A 2D grid of zones (columns) × weight ranges (rows) where each cell is the carrier cost in the service currency |
| Price Matrix | Same structure as cost matrix, but 4 instances (one per tariff type). Cell values are either absolute prices (Flat) or markup percentages (Margin) |
| Extra Weight | A single row per matrix showing the per-unit cost/price for weight exceeding the maximum defined range |
| Fuel Type | flat (fixed percentage) or dynamic (variable, externally updated). Affects graduated cost. |
| Fuel Percentage | Percentage applied to base cost for fuel surcharge calculation |
| Operator | Flat (1): cell value = selling price. Margin (2): cell value = markup % over graduated cost |
| Graduated Cost | base_cost + (base_cost × tax_rate/100) + (base_cost × fuel_rate/100) — the effective cost used for margin calculations |
| Markup | (price - graduated_cost) / graduated_cost × 100 — percentage increase over cost |
| Margin | (price - graduated_cost) / price × 100 — percentage of price that is profit |
| Secure Margins | Color-coded thresholds: Danger (<15%), Warning (15–25%), Safe (>25%) |
| Extended Zone | A flat surcharge (in currency) for extended delivery areas, applied across all tariff types |
| Upgrade Pricing | A cross-component feature that recalculates all pricing tariffs by applying a percentage over the cost matrix |
Data Flow
Cost Save Flow
Price Save Flow (per tab)
Upgrade Pricing Flow
Database
Tables
| Table | Purpose |
|---|---|
plan_costs | Metadata per service: locale_id, fuel_type, fuel_percentage, weight_unit_code, weight_extra_cost |
plan_cost_definitions | Cost cells: service_id, zone, weight_start, weight_end, cost, extra_cost |
plan_definitions | Price cells: service_id, zone, weight_start, weight_end, cost (the price value), plan_type, operator, extended_zone |
Key Fields (plan_cost_definitions / plan_definitions)
| Column | Type | Description |
|---|---|---|
service_id | INT (FK) | Reference to services |
zone | INT | Zone identifier |
weight_start | DECIMAL | Weight range start (e.g., 0) |
weight_end | DECIMAL | Weight range end (e.g., 5) |
cost | DECIMAL | Cost value (in plan_cost_definitions) or price/markup value (in plan_definitions) |
extra_cost | DECIMAL | Per-unit extra weight cost/price |
plan_type | VARCHAR | Only in plan_definitions: basic, pro, enterprise, corporate |
operator | INT | Only in plan_definitions: 1=Flat, 2=Margin |
Key Decisions
| Decision | Reasoning | Alternatives Considered |
|---|---|---|
| Separate cost and price tables | Costs change independently from prices; different update cadence and permissions | Single table with type column (coupling, permission complexity) |
| Delete + re-insert on save | Matrix saves are atomic — no partial updates. Simpler than diffing. | Upsert individual cells (complex, race conditions) |
| Upgrade Pricing via EventBus | Cross-component communication between Costs and Pricing without tight coupling | Shared composable state (more coupling), store actions (adds complexity to store) |
| Markup vs Margin as view toggle, not data | The stored data doesn't change — only the display formula. Avoids data conversion issues. | Store both values (redundancy, sync issues) |
| CSV supports partial tariff updates | Operators often update one tariff at a time. Forcing all 4 columns would be cumbersome. | Require all columns (inflexible) |
Related Documentation
- API Endpoints — Cost and price endpoint reference
- UI Screens & Flows — MatrixView usage, CSV flows, composable architecture
- User Guide — How to configure costs and pricing