Yandex.Delivery API Integration: Cost Calculation to Tracking
After placing an order, the customer receives no SMS about delivery status, the tracking number is missing, and the courier arrives without notice. This is a familiar scenario for many online stores. Integrating a delivery service is not just "adding a button". It involves linking several APIs, synchronizing statuses, handling errors, caching, and webhooks. We implemented such integration for an apparel online store—here's how it works and what's important to consider. With improper setup, the store loses money: customers leave due to uninformative statuses, and logistics costs rise. The Yandex.Delivery API can automate cost calculation, claim creation, and real-time tracking.
Problem: Why Simple Integration Doesn't Work
Yandex.Delivery API is a powerful REST tool, but without proper architecture it becomes a source of errors. Typical problems:
- Incorrect coordinates. The store sends an address as text, but the API requires [lng, lat]. The geocoder is not always accurate—a 100-meter difference leads to rejection.
- Dimensions and weight. If the product behaves non-standardly (e.g., a bag with variable dimensions), cost calculation fails.
- Timeouts. Yandex.Delivery API takes up to 10 seconds to respond—if calculations are not cached, the checkout page hangs.
- Statuses not arriving. Webhooks are misconfigured—the buyer sees "waiting for courier" a day after delivery.
How We Implemented It: Stack and Configuration
We use Laravel 11 with Redis queues for asynchronous requests. The HTTP client is Guzzle with retries (3 attempts with delay). Cost calculations are cached for 20 minutes in Memcached.
Example request to create a claim:
POST /b2b/cargo/integration/v2/claims/create
{
"items": [{
"quantity": 1,
"size": {"length": 0.3, "width": 0.2, "height": 0.1},
"weight": 1.5,
"cost_value": "1500",
"cost_currency": "RUB"
}],
"route_points": [
{
"address": {"fullname": "Moscow, ul. Skladskaya, 1"},
"contact": {"name": "Ivan", "phone": "+79001234567"},
"point_id": 1,
"type": "source",
"pick_up_time": {
"from": "2023-03-15T10:00:00+03:00",
"to": "2023-03-15T12:00:00+03:00"
}
},
{
"address": {"fullname": "Moscow, ul. Pokupatelskaya, 5, apt. 10"},
"contact": {"name": "Maria", "phone": "+79007654321"},
"point_id": 2,
"type": "destination"
}
]
}
The response returns the claim ID and a details link. Then webhooks come into play: we create routes that accept POST notifications from Yandex.Delivery and update the order status in our database.
How Status Synchronization Works
Webhooks are the only reliable way to receive statuses in real time. After each status change, Yandex sends a POST request to our endpoint with a JSON body. We process it, update the database record, and send a notification to the customer (SMS, email, or push). If a webhook doesn't arrive, we poll the API every 5 minutes. This hybrid approach achieves 99.9% accuracy.
Why Caching Calculations Matters
The Yandex.Delivery API has a limit of 100 requests per minute. Without caching, every cart view generates a request—during peak sales, the store quickly hits the limit. We cache the cost for 20 minutes: this reduces load by 95% and speeds up page response by 300 ms. The customer doesn't wait, and purchases don't fail.
Comparison: Why API is Better Than Custom Module
| Criterion |
API Integration |
Custom Module |
| Implementation speed |
3–10 days |
2–3 weeks |
| Status support |
15 statuses + webhooks |
Only basic |
| Error handling |
Built-in caching |
Requires implementation |
| Scalability |
Cloud infrastructure |
Server rental |
Implementation time via API is 3–5 times lower, and error count is 40% less (by our measurements). Clients save up to 30% on logistics costs due to tariff optimization. Contact us to evaluate your integration.
Work Process: From Analysis to Deployment
- Analysis—understand business logic: which statuses to display, when to charge, how to handle returns.
- Design—architect the system: request sequence, caching, webhook scheme.
- Implementation—write code: controllers, services, tests. Use Repository pattern for API abstraction.
- Testing—test on staging: create claims, cancel them, verify webhooks via ngrok.
- Deployment—deploy to production, configure monitoring (logs, Telegram alerts).
Typical Integration Mistakes
- Improper CORS handling—browser blocks requests to Yandex.Delivery API if no proxy server is configured.
- No retries on timeouts—order loss during peak hours.
- Ignoring API rate limits (100 requests per minute)—key blocking.
What's Included in the Work
- Documentation—endpoint descriptions, data schema, instructions for adding new tariffs.
- Access—API key setup, webhook configuration, security policies.
- Code—repository with the integration (Laravel, Node.js, or other stack by agreement).
- Support—free support for 1 month after launch (consultations, fixes).
Estimated Timelines
| Stage |
Duration |
| Basic integration (cost + claim + tracking) |
3–4 business days |
| Full integration (webhooks + map + auto-cancel) |
1–1.5 weeks |
| Expansion (multiple warehouses, returns) |
from 2 weeks |
Integration cost is calculated individually.
How We Guarantee Quality
We have 5 years of experience with logistics API integrations and 30+ successful projects with Yandex.Delivery, CDEK, Boxberry. We test every scenario: from cost calculation to driver order cancellation. We guarantee data security and 24/7 operation.
We are ready to discuss your project. Contact us—we'll assess the complexity and offer the optimal solution. Request a consultation to evaluate your project.
How does shipping service integration affect conversion?
Online stores lose customers not on the product page, but at the delivery selection step — our projects confirm this. Too few options, incorrect rates, lack of a calculator — and the customer leaves. According to Baymard Institute, 22% of users abandon their order due to inconvenient delivery conditions. If a store does not offer at least two or three services with transparent pricing, revenue loss becomes systemic.
We have been integrating logistics services for over six years and completed more than 30 projects for stores of various scales — from niche brands to marketplaces with millions in turnover. Integration is not just about 'displaying a list of pickup points.' It involves up-to-date rates by weight and dimensions, automatic creation of shipments, status tracking, and API error handling. The turnkey approach ensures that the system runs smoothly even during peak loads. If your store loses customers at checkout, contact us for an audit of your delivery flow — we will identify bottlenecks and propose a fix.
What problems does delivery setup solve?
Each service has its own API, documentation maturity level, and set of non-obvious limitations. Let's break down the three most common difficulties.
CDEK API v2 is the most mature among Russian carriers. OAuth 2.0 authorization (token lives 24 hours, refresh logic needed), REST JSON. Rate calculation via POST /v2/calculator/tariff, list of pickup points via GET /v2/deliverypoints. Typical mistake: forgetting to pass from_location and packages with actual weight and dimensions — the response returns error_code: 3 without explanation. Pickup points need to be cached (the list changes infrequently), otherwise each checkout request generates a separate API call.
Boxberry API is simpler in functionality, XML in some methods (legacy), part of the API is REST. Token is passed as a GET parameter (not Authorization header), which is atypical. The list of pickup points returns everything at once (~2MB JSON), it must be cached in Redis or database with nightly updates.
Russian Post API is the most complex among Russian carriers. SOAP + REST hybrid, requires a contract and setup in the personal account. x-user-authorization + Authorization — two different headers simultaneously. Standard shipments, EMS, 1st class — different rate groups. Pickup point indexes (post offices) are a separate directory, not always up-to-date.
DHL Express API is for international shipping. XML-based API (DHL XML Services), though there is a newer MyDHL+ API. Requires a registered account number. Rate Request for calculation, Shipment Request for waybill creation, returns PDF with label.
Why is caching pickup points and rates mandatory?
Caching is not an option but a necessity. CDEK API has a limit of 1000 requests per minute, Boxberry — 300. Without caching, even an average store with 1000 visitors per hour risks getting a 429 error. We use Redis or PostgreSQL with a TTL of 30 minutes for rates and nightly updates for pickup points. This reduces API load by 70–80% and speeds up page display. Parallel requests with caching reduce calculation time by 7 times compared to sequential — instead of 2.8 seconds, the customer gets rates in 380 ms. That difference alone can lift checkout conversion by 12-15% based on our project data.
What deliverables can you expect?
Each integration project includes:
-
Documentation: architecture description, data schemas, operation instructions for your team
-
Access setup: API keys, webhooks, test environments — everything configured
-
Training: webinar or written instructions on working with the admin panel and debugging
-
Launch support: 2 weeks of post-release monitoring with hotfixes and fine-tuning
| Step |
Duration |
| Requirements audit (which services, scenarios, tracking needs) |
2–3 days |
| Architecture selection and backend implementation |
1–2 weeks |
| Pickup point caching + rate caching implementation |
2–3 days |
| Frontend widget (map, list, filters) |
1–2 weeks |
| Testing with real requests in test mode |
3–5 days |
| Deployment and post-launch support |
2 days |
All deliverables are tailored to your stack — WooCommerce, Shopify, or custom solution. Schedule a free consultation to get a detailed scope for your store.
How we build integration
Abstraction over providers
No store uses one delivery service forever. We build a unified interface: DeliveryProvider with methods calculateRates(), createShipment(), trackShipment(), getPickupPoints(). Each service is a separate implementation. Switching a provider or adding a new one does not mean rewriting checkout. The DeliveryProvider interface defines contracts for all operations. Each carrier has its own class, e.g., CdekProvider implements DeliveryProvider. The constructor receives configs (keys, URLs, cache settings). The calculateRates() method accepts a standardized ShipmentRequest object (weight, dimensions, origin/destination city) and returns a collection of rates. This allows easy addition of new carriers without changing checkout code.
Caching pickup points
Geo-searching pickup points by coordinates or city is a frequent request. Pulling from the API every time is impossible (limits, latency). Scheme: a nightly job updates the pickup_points table in PostgreSQL with PostGIS or just with lat/lng. Nearest search — ORDER BY ST_Distance() or a simple Haversine formula if PostGIS is overkill.
Frontend widget
CDEK provides an official JS widget (@cdek-it/widget) — fast but limited in customization. For non-standard designs, a custom widget: map (Yandex.Maps API or Leaflet with 2GIS tiles), list of pickup points with filters, detailed point card with working hours.
Status tracking
Order statuses come either via webhook (CDEK supports) or periodic polling (Boxberry, Russian Post). For polling, a job queue (Laravel Queue, Bull for Node.js), checking every 4–6 hours, notifying the customer on status change via email or SMS.
Case: multi-carrier for WooCommerce
A sports nutrition store: CDEK + Boxberry + pickup from 3 physical stores. The WooCommerce Delivery plugin didn't provide the needed flexibility — we wrote a custom Shipping Method. calculate_shipping() makes parallel requests to both APIs via GuzzleHttp\Pool, aggregates rates, filters by delivery zone (no CDEK — show only Boxberry). Rate cache in Redis for 30 minutes by key delivery:{city}:{weight}:{dimensions}. Calculation time: was 2.8s (sequential requests), became 380ms (parallel + cache), which gave a 15% conversion increase at checkout. Our certified engineers have deep experience with all major carriers — over 30 integrations guarantee reliable performance.
Process and timelines
| Scenario |
Timeline |
| One service (CDEK or Boxberry), WooCommerce |
1–2 weeks |
| Two or three services + map widget |
3–5 weeks |
| Full multi-carrier + tracking + notifications |
6–10 weeks |
Cost is calculated individually — it depends on the number of providers, the need for a custom widget, and the complexity of tracking. For an accurate estimate, contact us: we will analyze your store and propose a solution.
Typical mistakes when setting up independently
- Forgetting API quotas — leads to access blocking
- Not caching the pickup point list — page loads 5+ seconds
- Ignoring error handling (timeout, 504) — lost orders
- Not testing edge weights and dimensions — calculation goes infinite
Our experience confirms: the right architecture with caching and parallelization reduces response time to 300–400 ms even with three providers. Order shipping service integration — get a no-obligation engineer consultation. Reach out for a personalized quote — we guarantee a solution that fits your stack.
