Delivery Cost Calculation API Integration
Real-time delivery cost calculation is a critical conversion element. The customer must see the exact cost of each delivery option during selection, not after confirming the order. This reduces abandonment at the final checkout step.
Calculation Architecture
Cost calculation is performed with a single request to the backend, which simultaneously queries the APIs of all connected delivery services and returns a unified list of options.
class DeliveryCalculator
{
private array $providers;
public function calculate(Cart $cart, Address $destination): Collection
{
$requests = collect($this->providers)->map(function ($provider) use ($cart, $destination) {
return $provider->calculateAsync($cart, $destination); // returns Promise
});
return collect(async_all($requests)) // parallel execution
->flatten()
->sortBy('price')
->filter(fn($option) => $option->isAvailable());
}
}
Parallel requests via Guzzle Pool or ReactPHP HTTP. Timeout for each external request is no more than 2–3 seconds. If a provider doesn't respond, their option is simply excluded from the list.
Unified Delivery Option Format
class DeliveryOption
{
public string $providerId; // 'cdek', 'boxberry', 'pochta'
public string $serviceCode; // 'cdek_express', 'cdek_pvz'
public string $name; // 'CDEK: Express'
public string $type; // 'courier' | 'pvz' | 'postamat'
public int $price; // in kopecks
public ?int $priceWithDiscount;
public int $minDays;
public int $maxDays;
public ?string $pvzCode; // if pickup point selection is needed
public array $meta; // additional provider data
}
Result Caching
Calculation repeats whenever the address or cart contents change. Caching makes sense with the key {cart_hash}:{destination_hash} for 10–15 minutes.
$cacheKey = "delivery:{$cart->hash()}:{$destination->hash()}";
return Cache::remember($cacheKey, 900, fn() => $this->fetchFromProviders($cart, $destination));
Calculation Parameters
Each provider requires different parameters, but the basics are common:
- Package dimensions and weight (total across all items in the cart)
- Origin city/region (warehouse address)
- Destination city/region
- Declared value (affects insurance cost)
- Number of pieces
Dimensions are extracted from products: if the seller hasn't provided them, default values are applied.
Multiple Warehouses and Dispatch Points
E-commerce stores with multiple warehouses should calculate delivery from the closest warehouse to the customer's address. This requires preliminary routing logic: determine which warehouse will ship each item and calculate delivery from each warehouse separately.
Displaying Results
On the UI, results are grouped as follows:
- Courier delivery: multiple options by speed/cost
- Pickup from PVZ: click → opens pickup point selection map
- Russian Post: separately (usually slower, cheaper)
Delivery speed is displayed as "1–2 business days" or "by March 15" — this requires a production calendar (holidays, weekends).
Integration timeframe: 3–5 days to connect 2–3 providers with parallel requests and caching.