Service Configuration

Single-page configuration module for managing all operational parameters of a shipping service — taxes, costs, pricing tariffs, volumetric factor, default zone rates, additional services, and additional charges.

Overview

The Service Configuration module provides a unified interface at /services/:id where operators configure every aspect of a shipping service's pricing and operational parameters. The page is organized into 7 scroll-navigable sections, each backed by dedicated API endpoints under the /services/{id}/ prefix.

The module bridges two backend layers: the PlansV2 system (costs, pricing, taxes, volumetric, default rates, additionals) and the Services system (pricing table management, fixed rules). All configuration endpoints live in plansV2.routes.js.

Key Concepts

Concept	Description
Service	A specific shipping offering from a carrier (e.g., "FedEx Express", "DHL Ground"), identified by service_id
Carrier	The logistics company providing the service (e.g., FedEx, DHL, Estafeta)
Locale	The country/region context that determines currency, tax rules, and weight units
Zone	A geographic delivery area, identified by a numeric identifier; costs and prices vary per zone
Weight Range	A weight interval (e.g., 0–1 kg, 1–5 kg) used as rows in cost/price matrices
Tariff Type	One of 4 pricing tiers: basic (1), pro (2), enterprise (3), corporate (4)
Operator (Pricing)	How prices are expressed: Flat (absolute price) or Margin (markup % over cost)
Graduated Cost	Base cost + tax amount + fuel amount — the effective cost used for margin calculations
Volumetric Factor	Divisor for dimensional weight: (L × W × H) / factor
Additional Service	An optional add-on (mandatory=false) with configurable pricing
Additional Charge	A mandatory surcharge (mandatory=true) with activation conditions

Architecture

Data Flow

Page Load

Simple Sections (covered in this file)

Taxes — Read-only display. Fetches tax_rules_2 for the service's locale from the database. No write operations.

Volumetric Factor — Select from catalog, PATCH to update. The catalog comes from GET /catalog/volumetric-factors, and the update sets factor_id on the service record.

Default Rates — Table of zones with a tariff type dropdown. Zones are derived from the cost matrix. The mapping (zone → type_id) is stored and retrieved via dedicated endpoints.

Backend Structure

Route & Controller

All 11 endpoints are defined in a single route file and handled by a single controller:

backend/routes/plansV2.routes.js       → All /services/{id}/* routes
backend/controllers/plansV2.controller.js → All handlers

Business Logic

backend/libraries/
├── plansCosts.util.js    → Cost and price matrix CRUD (zones, ranges, extra_weights)
├── plansv2.util.js       → Taxes, volumetric factor, additional services CRUD
└── plans.utils.js        → Default rates, tariff plans (legacy flows)

Catalog Endpoints

backend/routes/catalogs.routes.js
backend/controllers/catalogs.controller.js

Catalog Endpoint	Used By
GET /catalog/volumetric-factors	Volumetric Factor section
GET /catalog/zones?service={id}	Default Rates (zone list)
GET /catalog/additional-services	Additional Services offcanvas
GET /catalog/additional-services/operators	Additional Services offcanvas
GET /catalog/locales	Costs and Pricing forms

Database

Core Tables

Table	Purpose
services	Service metadata: carrier, locale, status, volumetric_factor_id
plan_cost_definitions	Cost matrix: zone × weight range → cost value
plan_definitions	Price matrix: zone × weight range × plan_type → price/markup value
plan_costs	Plan cost metadata: locale, fuel type, fuel percentage, weight unit
tax_rules_2	Tax rules per locale (country, concept, rate, application type)
catalog_zones	Zone definitions per service
catalog_volumetric_factors	Available volumetric factors (factor value + unit weight)
service_default_rates	Zone → tariff type mapping per service
additional_service_prices	Additional service/charge configurations per service
additional_service_conditions	Activation conditions for additional charges
additional_service_plan_definitions	Range-based pricing rows for operators 4, 15, 19

Entity Relationships

Key Decisions

Decision	Reasoning	Alternatives Considered
Single page with 7 scroll sections	All configuration is contextually related to one service; avoids navigation overhead	Separate pages per section (too fragmented), tabs (loses overview)
Dual pricing operators (Flat vs Margin)	Some carriers quote flat prices, others use margin-based pricing. Both models coexist.	Single operator (doesn't match real-world contracts)
4 tariff types (basic/pro/enterprise/corporate)	Matches the platform's customer tier system. Each tier gets different pricing.	Dynamic tariff types (over-engineering), single price (insufficient)
Zones from cost matrix, not standalone	Zones are meaningful only when they have cost data. Avoids orphan zones.	Independent zone management (creates sync issues)
Additional Services vs Charges via mandatory flag	Same data model, same UI, different behavior. Simpler than two separate systems.	Separate tables and APIs (duplication)
19 operator types for additionals	Covers all carrier billing models encountered in production	Fewer operators with formulas (too complex for operators to configure)

Permissions

Permission	Scope
plans-menu	Read access to all sections
manage-service-costs	Write access to operational costs
manage-service-pricing	Write access to pricing tariffs
manage-service-config	Write access to volumetric factor, default rates, additional services and charges

Dependencies

• Internal: Catalog module (volumetric factors, zones, additional service types, operators, locales), Plans module (legacy tariff plans)
• External: None (pure database CRUD, no external API integrations)

Related Documentation

• API Endpoints — Complete endpoint reference
• UI Screens & Flows — Frontend screens and component architecture
• Pricing & Costs — Deep dive into cost and price matrix subsystem
• Additional Services & Charges — Deep dive into add-on services subsystem
• User Guide — End-user instructions