Custom Magento 2 Shipping Plugin Development

Custom Magento 2 Shipping Plugin Development

When integrating with a courier service like SDEK in Magento 2, a common issue arises: the API returns rates only for orders up to 20 kg, but the store needs to deliver oversized items. Standard modules can't flexibly handle such scenarios. A custom plugin allows implementing any rate logic, including zones, days of the week, and multiple warehouses.

What problems we solve

Rate calculation through a third-party API. The carrier's documentation may be incomplete or change. Typical example: the API returns cost only for orders up to 20 kg, but the client wants to deliver 50 kg equipment. We handle errors, timeouts, sudden field changes.

N+1 queries for group delivery. If the cart has 10 items and each is calculated separately – checkout slows down. Solution: aggregate items – group by single address, cache rates for 30 minutes, invalidate by tag mycourier_rates.

Configuration errors. Developers often forget to add config.xml with defaults – config fields return null, shipping method doesn't appear. Or skip system.xml – admin can't configure API key. We ensure all necessary fields are in admin with encryption via Encrypted backend.

Why order a custom Magento 2 shipping plugin?

A ready-made extension for $50–200 rarely covers business specifics. For example, Boxberry with cash on delivery and pickup point selection – that's already 3 modules in one that need to be stitched together. A custom plugin avoids these issues:

Our custom plugin processes a cart with 20 items 3 times faster than a ready-made extension with per-item API requests.

How we implement courier service integration

Let's take a real case: a cosmetics online store wanted to deliver orders via DPD with cost calculation by weight and dimensions. No standard solutions existed – DPD only provides an API.

Module architecture. Class Vendor\MyCourier\Model\Carrier\MyCourier extends \Magento\Shipping\Model\Carrier\AbstractCarrier (see Magento documentation). In method collectRates we form a request to DPD: pass weight, city, postal code. We use \Magento\Framework\HTTP\Client\Curl – built into Magento 2, no extra dependencies needed.

<?php namespace Vendor\MyCourier\Model\Carrier; use Magento\Quote\Model\Quote\Address\RateRequest; use Magento\Shipping\Model\Carrier\AbstractCarrier; use Magento\Shipping\Model\Carrier\CarrierInterface; use Magento\Shipping\Model\Rate\Result; class MyCourier extends AbstractCarrier implements CarrierInterface { protected $_code = 'mycourier'; public function collectRates(RateRequest $request): ?Result { if (!$this->getConfigFlag('active')) { return null; } /** @var Result $result */ $result = $this->_rateResultFactory->create(); $rates = $this->fetchRatesFromApi($request); foreach ($rates as $rateData) { $method = $this->_rateMethodFactory->create(); $method->setCarrier($this->_code); $method->setCarrierTitle($this->getConfigData('title')); $method->setMethod($rateData['code']); $method->setMethodTitle($rateData['name']); $method->setPrice($rateData['price']); $method->setCost($rateData['price']); $result->append($method); } return $result; } private function fetchRatesFromApi(RateRequest $request): array { $apiKey = $this->getConfigData('api_key'); $fromCity = $this->getConfigData('from_city'); $toCity = $request->getDestCity(); $postcode = $request->getDestPostcode(); $weight = 0; foreach ($request->getAllItems() as $item) { if ($item->getParentItem()) { continue; } $weight += $item->getWeight() * $item->getQty(); } $payload = json_encode([ 'from' => $fromCity, 'to_city' => $toCity, 'postcode' => $postcode, 'weight' => max(0.1, $weight), 'currency' => $request->getPackageCurrency()->getCurrencyCode(), ]); $this->_curl->addHeader('Authorization', 'Bearer ' . $apiKey); $this->_curl->addHeader('Content-Type', 'application/json'); $this->_curl->setTimeout(10); try { $this->_curl->post('https://api.mycourier.ru/v2/rates', $payload); $body = $this->_curl->getBody(); $status = $this->_curl->getStatus(); } catch (\Exception $e) { $this->_logger->error('MyCourier API error: ' . $e->getMessage()); return []; } if ($status !== 200) { return []; } $data = json_decode($body, true); return $data['services'] ?? []; } public function getAllowedMethods(): array { return [$this->_code => $this->getConfigData('title')]; } } 

Configuration. config.xml sets defaults, system.xml provides admin form. API key is encrypted via \Magento\Config\Model\Config\Backend\Encrypted.

Rate caching. We use CacheInterface with tag mycourier_rates. TTL is 30 minutes. This reduces load on the carrier API and speeds up checkout.

Shipment creation handling. After payment (sales_order_invoice_pay event), observer CreateShipment calls carrier API to create an order, gets tracking number, and automatically creates shipment in Magento. This eliminates manual input.

Pickup point UI component. We add a field via checkout_index_index.xml. Component Vendor_MyCourier/js/pvz-selector loads a list of pickup points and saves the selected one to the order address.

What's included in custom shipping plugin development

• Module source code in a private repository.
• Documentation: configuration description, architecture, update instructions.
• Repository access setup.
• Team training: how to change rates, add new shipping methods.
• 6 months warranty support (bug fixes, adaptation to API updates).
• Post-release assistance during production deployment.

Process

1. Analysis. Study carrier API, agree on tariff model, data schema (cities, weights, dimensions).
2. Design. Create UML class diagram, define events and plugins.
3. Implementation. Write carrier, observer, caching mechanism, configuration.
4. Testing. Unit tests for PHP (cover key methods), integration tests in Magento environment. Example: verify that API requests are cached and on failure previous rates are returned.
5. Deployment. Build module, publish to Composer, set up CI/CD with compatibility check against target Magento version.

Timeline

Total timeline: from 5 to 12 days depending on API complexity and number of features.