Skip to main content

​
Overview

App Courier includes a sophisticated pricing calculator that automatically determines shipping costs based on multiple factors including distance, weight, delivery type, and customer-specific pricing plans.

​
Pricing Factors

Shipping cost is calculated using these components:

Distance

Distance between origin and destination districts

Weight

Package weight in kilograms

Delivery Type

Agency-to-agency, home delivery, or door-to-door

Customer Plan

Customer’s assigned pricing plan with custom rates

​
How Pricing Works

​
Base Price Calculation

The base price is determined by the customer’s pricing plan: 
class Plan {
  int? id;
  String? descripcion;      // Plan name
  String? tarifa_km_0_50;   // Rate for 0-50 km
  String? tarifa_km_50_100; // Rate for 50-100 km  
  String? tarifa_km_100;    // Rate for 100+ km
  String? tarifa_min_0_50;  // Minimum charge 0-50 km
  String? tarifa_min_50_100;// Minimum charge 50-100 km
  String? tarifa_min_100;   // Minimum charge 100+ km
}

​
Distance Tiers

  1. 0-50 km: Short distance
    • Uses tarifa_km_0_50 per kg
    • Minimum charge: tarifa_min_0_50
  2. 50-100 km: Medium distance
    • Uses tarifa_km_50_100 per kg
    • Minimum charge: tarifa_min_50_100
  3. 100+ km: Long distance
    • Uses tarifa_km_100 per kg
    • Minimum charge: tarifa_min_100

​
Additional Charges

Extra Domicilio → AgenciaAdditional fee when driver picks up from sender’s address:
customer.extraDomAge  // Additional charge

​
IGV (Tax)

For business customers, 18% IGV may be added: 
if (customer.igv == 1) {
  totalWithIGV = subtotal * 1.18;
}

​
Price Calculation API

Calculate shipping costs programmatically:

​
Endpoint

POST /encomienda/calcularPrecio

​
Request Parameters

​
id_distrito_origen
integer
required
Origin district ID
​
id_distrito_destino
integer
required
Destination district ID
​
kilos
number
required
Package weight in kilograms
​
id_plan
integer
required
Customer’s pricing plan ID
​
tipo_entrega
string
required
Delivery type:
  • “Sucursal - Sucursal”
  • “Domicilio - Sucursal”
  • “Sucursal - Domicilio”
  • “Domicilio - Domicilio”
​
igv
integer
required
Include IGV: 1 = yes, 0 = no
​
extra_dom_age
number
Extra charge for home pickup
​
extra_age_dom
number
Extra charge for home delivery
​
extra_dom_dom
number
Extra charge for door-to-door

​
Response

{
  "success": true,
  "data": {
    "precio_base": "25.00",
    "precio_extra": "5.00",
    "precio_movilidad": "30.00",
    "precio_minimo": "15.00",
    "precio_total": "30.00",
    "precio_total_igv": "35.40",
    "km": "45"
  }
}

​
Response Fields

​
precio_base
string
Base shipping price (distance × weight × rate)
​
precio_extra
string
Additional delivery charges (home pickup/delivery)
​
precio_movilidad
string
Total mobility/transport cost (base + extra)
​
precio_minimo
string
Minimum charge for this distance tier
​
precio_total
string
Final price (maximum of precio_movilidad or precio_minimo)
​
precio_total_igv
string
Final price including 18% IGV tax (if applicable)
​
km
string
Distance in kilometers between districts

​
Pricing Examples

​
Example 1: Simple Agency-to-Agency

Origin: Lima (District 1)
Destination: Callao (District 50)
Distance: 35 km
Weight: 2 kg
Delivery: Sucursal - Sucursal
Plan: Standard (tarifa_km_0_50 = S/ 5.00/kg, min = S/ 15.00)

Calculation:
Base: 2 kg × S/ 5.00 = S/ 10.00
Extras: S/ 0.00 (no home delivery)
Minimum: S/ 15.00
Final: S/ 15.00 (minimum applies)

​
Example 2: Door-to-Door with IGV

Origin: Arequipa (District 100)
Destination: Cusco (District 200)  
Distance: 320 km
Weight: 5 kg
Delivery: Domicilio - Domicilio
Plan: Premium (tarifa_km_100 = S/ 8.00/kg, min = S/ 50.00)
Extras: extraDomDom = S/ 15.00
IGV: Yes

Calculation:
Base: 5 kg × S/ 8.00 = S/ 40.00
Extras: S/ 15.00
Subtotal: S/ 55.00
Minimum: S/ 50.00
Before IGV: S/ 55.00 (subtotal > minimum)
With IGV: S/ 55.00 × 1.18 = S/ 64.90

​
Price Display in UI

When creating packages, price is calculated automatically:
1

Select Origin & Destination

Choose districts for origin and destination
2

Enter Weight

Input package weight in kg
3

Choose Delivery Type

Select delivery type (affects extra charges)
4

Auto-Calculate

System calls pricing API and displays total cost
5

Review Breakdown

See price components:
  • Base shipping cost
  • Extra delivery charges
  • IGV (if applicable)
  • Total cost

​
Custom Pricing Plans

Business customers can have custom pricing plans:

​
Creating Custom Plans

Custom plans are typically created by system administrators and assigned to high-volume business customers.
  1. Define plan name and description
  2. Set rates for each distance tier
  3. Set minimum charges per tier
  4. Assign plan to customer
  5. Customer automatically uses new plan for all shipments

​
Plan Management

Administrators can:
  • Create new pricing plans
  • Modify existing plans
  • Assign plans to customers
  • View plan usage and revenue

​
Minimum Charges

Every distance tier has a minimum charge:
If calculated price is below minimum, the minimum charge is applied automatically.
Example: 
Calculated: S/ 8.00
Minimum: S/ 15.00
Actual Charge: S/ 15.00  // Minimum applies
This ensures:
  • Coverage of operational costs
  • Fair pricing for short distances
  • Consistent minimum revenue per package

​
Volume Discounts

While not explicitly in the pricing model, volume customers can receive:
  • Custom pricing plans with reduced rates
  • Lower extra delivery charges
  • Reduced minimum charges
  • Special negotiated rates
Contact administrators to set up volume discount pricing for high-volume business customers.

​
Integration

Pricing calculator integrates with:
  • Package Creation: Auto-calculate during package creation
  • Customer Management: Uses customer’s assigned plan
  • Branch Management: Calculates distance between districts
  • Invoicing: Generates correct invoice amounts
  • Reporting: Revenue projections and analysis

​
API Reference

Calculate Price

POST /encomienda/calcularPrecio

Get Plans

GET /configuraciones/getPlanes

​
Best Practices

Verify weight accuracy: Accurate weight is crucial for correct pricing. Use calibrated scales.
Explain pricing to customers: Be transparent about price breakdown including base cost, extras, and IGV.
Update plans carefully: Changes to pricing plans affect all future shipments for customers using that plan.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us