Developing a Custom Shipping Plugin for OpenCart
Standard OpenCart shipping methods — flat rate, free shipping, per item — cover basic cases. When you need rate calculation via carrier API, pickup point selection, or logic like "free from 3000 rubles, but only within the city" — you write a custom plugin.
Shipping Plugin Structure in OpenCart 3.x / 4.x
OpenCart 3.x follows the MVC+L pattern. A shipping plugin is a set of files by convention:
catalog/
controller/extension/shipping/my_courier.php
model/extension/shipping/my_courier.php
language/en-gb/extension/shipping/my_courier.php
language/ru-ru/extension/shipping/my_courier.php
admin/
controller/extension/shipping/my_courier.php
language/en-gb/extension/shipping/my_courier.php
language/ru-ru/extension/shipping/my_courier.php
view/template/extension/shipping/my_courier.twig
In OpenCart 4.x the path changed to extension/{extension_name}/shipping/, but the logic is the same.
Catalog Controller: Return Rates
The main method is getQuote(), which takes a shipping address and returns an array of methods with prices:
<?php
// catalog/controller/extension/shipping/my_courier.php
class ControllerExtensionShippingMyCourier extends Controller {
public function getQuote( array $address ): array {
$this->load->language( 'extension/shipping/my_courier' );
$this->load->model( 'extension/shipping/my_courier' );
$status = (bool) $this->config->get( 'shipping_my_courier_status' );
$geo_zone_id = (int) $this->config->get( 'shipping_my_courier_geo_zone_id' );
// Check geo-zone if set
if ( $geo_zone_id ) {
$this->load->model( 'localisation/geo_zone' );
$results = $this->model_localisation_geo_zone->getGeoZoneRules( $geo_zone_id );
$status = $this->isAddressInGeoZone( $address, $results );
}
if ( ! $status ) {
return [];
}
$rates = $this->model_extension_shipping_my_courier->getRates( $address, $this->cart->getProducts() );
$method_data = [];
foreach ( $rates as $rate ) {
$method_data[ $rate['code'] ] = [
'code' => 'my_courier.' . $rate['code'],
'title' => $rate['title'],
'cost' => $rate['cost'],
'tax_class_id' => 0,
'text' => $this->currency->format(
$this->tax->calculate( $rate['cost'], 0, $this->config->get( 'config_tax' ) ),
$this->session->data['currency']
),
];
}
if ( empty( $method_data ) ) {
return [];
}
return [
'code' => 'my_courier',
'title' => $this->language->get( 'text_title' ),
'quote' => $method_data,
'sort_order' => (int) $this->config->get( 'shipping_my_courier_sort_order' ),
'error' => false,
];
}
}
Model: Request to Carrier API
<?php
// catalog/model/extension/shipping/my_courier.php
class ModelExtensionShippingMyCourier extends Model {
public function getRates( array $address, array $products ): array {
$api_key = $this->config->get( 'shipping_my_courier_api_key' );
$from_city = $this->config->get( 'shipping_my_courier_from_city' );
$weight = 0;
$declared_value = 0;
foreach ( $products as $product ) {
$weight += (float) $product['weight'] * $product['quantity'];
$declared_value += (float) $product['price'] * $product['quantity'];
}
// Cache by address and cart composition
$cache_key = 'courier_' . md5( json_encode( $address ) . $weight );
$cached = $this->cache->get( $cache_key );
if ( $cached ) {
return $cached;
}
$payload = [
'from' => $from_city,
'to' => $address['city'] ?? $address['postcode'],
'weight' => max( 0.1, $weight ),
'value' => $declared_value,
];
$ch = curl_init( 'https://api.mycourier.ru/v1/tariff' );
curl_setopt_array( $ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode( $payload ),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 8,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $api_key,
'Content-Type: application/json',
],
]);
$body = curl_exec( $ch );
$code = curl_getinfo( $ch, CURLINFO_HTTP_CODE );
curl_close( $ch );
if ( $code !== 200 || ! $body ) {
return [];
}
$data = json_decode( $body, true );
$result = [];
foreach ( $data['services'] ?? [] as $service ) {
$result[] = [
'code' => $service['code'],
'title' => $service['name'] . ' (' . $service['days'] . ' days)',
'cost' => (float) $service['price'],
];
}
$this->cache->set( $cache_key, $result, 1800 );
return $result;
}
}
Admin: Settings Form
A form in Twig with fields for API key, shipping city, and geo-zone:
{# admin/view/template/extension/shipping/my_courier.twig #}
<div class="panel-body">
<div class="form-group required">
<label class="col-sm-2 control-label">API Key</label>
<div class="col-sm-6">
<input type="text" name="shipping_my_courier_api_key"
value="{{ shipping_my_courier_api_key }}" class="form-control"/>
</div>
</div>
<div class="form-group required">
<label class="col-sm-2 control-label">Shipping City</label>
<div class="col-sm-6">
<input type="text" name="shipping_my_courier_from_city"
value="{{ shipping_my_courier_from_city }}" class="form-control"/>
</div>
</div>
<div class="form-group">
<label class="col-sm-2 control-label">Geo-zone</label>
<div class="col-sm-6">
<select name="shipping_my_courier_geo_zone_id" class="form-control">
<option value="0">All zones</option>
{% for geo_zone in geo_zones %}
<option value="{{ geo_zone.geo_zone_id }}"
{% if geo_zone.geo_zone_id == shipping_my_courier_geo_zone_id %}selected{% endif %}>
{{ geo_zone.name }}
</option>
{% endfor %}
</select>
</div>
</div>
</div>
Saving Tracking Number to Order
After order placement, you need to create a shipment and save the tracking number:
// Hook on order creation event
// catalog/controller/extension/shipping/my_courier.php — confirmOrder() method
public function confirmOrder( int $order_id ): void {
$this->load->model( 'checkout/order' );
$order = $this->model_checkout_order->getOrder( $order_id );
if ( strpos( $order['shipping_code'], 'my_courier' ) === false ) {
return;
}
$api_key = $this->config->get( 'shipping_my_courier_api_key' );
$shipment = $this->createShipment( $order, $api_key );
if ( isset( $shipment['tracking'] ) ) {
// Save to custom table or order comment
$this->db->query(
"INSERT INTO " . DB_PREFIX . "order_tracking
SET order_id = '" . (int)$order_id . "',
tracking_number = '" . $this->db->escape( $shipment['tracking'] ) . "',
carrier = 'my_courier',
created_at = NOW()"
);
$this->model_checkout_order->addOrderHistory(
$order_id, $order['order_status_id'],
'Tracking: ' . $shipment['tracking'], true
);
}
}
Plugin Registration
In OpenCart 3.x the plugin is installed via admin > Extensions > Shipping. The installation code creates a table and registers an event:
// admin/controller/extension/shipping/my_courier.php — install() method
public function install(): void {
$this->db->query(
"CREATE TABLE IF NOT EXISTS `" . DB_PREFIX . "order_tracking` (
`id` INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
`order_id` INT UNSIGNED NOT NULL,
`tracking_number` VARCHAR(64) NOT NULL,
`carrier` VARCHAR(32) NOT NULL,
`created_at` DATETIME NOT NULL,
INDEX `order_id` (`order_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4"
);
$this->load->model( 'setting/event' );
$this->model_setting_event->addEvent(
'my_courier_confirm',
'catalog/model/checkout/order/addOrder/after',
'extension/shipping/my_courier/confirmOrder'
);
}
Implementation Timeline
Minimal plugin with rate calculation via API and display on checkout: 2–3 days. Full version with pickup point selection, tracking number saving, notifications, and tracking page in customer account: 5–7 days. Support for multiple carriers with unified management page in admin: 1.5–2 weeks.