Shipping Hub — Complete Guide

★ Introduction to Shipping Hub

The Shipping Hub is your central command for managing fulfillment across multiple shipping carriers. Connect your carrier accounts, automate label generation, and track shipments in real-time.

Multi-carrier support — Connect providers from Egypt, Saudi Arabia, UAE, and international carriers like DHL and FedEx.
Automated labeling — Generate shipping labels (AWB) automatically when orders are created.
COD management — Handle Cash on Delivery amounts with currency rules per provider.
Real-time tracking — Track shipments and sync status changes (Pending, In Transit, Delivered, Cancelled).
Secure credentials — API keys and credentials are encrypted and stored securely per tenant.

Tip: Use the Shipping Hub from the sidebar to access all shipping-related configuration and operations.

1 Supported shipping providers

Keddily supports major shipping providers across MENA and international markets. Click the provider name to visit their official documentation.

Egypt (EG)

Bosta — Modern API-based courier for Egypt and MENA region
Aramex — Leading global courier and logistics company
Mylerz — Egyptian logistics and delivery services

Saudi Arabia (SA)

SMSA Express — Express delivery across Saudi Arabia
Ajex — Logistics and delivery solutions in KSA
Thabit — Saudi shipping and fulfillment services

UAE (AE)

Fetchr — Last-mile delivery and logistics
Empost — Emirates Post Corporation
QExpress — Express courier services in UAE

International (INT)

DHL — Global express shipping and logistics
FedEx — Worldwide delivery and freight services

2 Step-by-step configuration guide

Connect your shipping provider accounts by entering API credentials in the Shipping Hub configuration form.

Accessing Shipping Hub

Sidebar → Shipping Hub

Log in to your Keddily admin panel.
Click Shipping Hub from the left sidebar.
You'll see a list of available shipping providers grouped by region.
Click Configure on any provider to set up credentials.

…/user/shipping-hub

Shipping Providers

Egypt (EG)

BostaConfigure

AramexConfigure

Saudi Arabia (SA)

SMSAConfigure

Figure 2.1 — Shipping Hub provider list

Obtaining API credentials

Each provider has different steps to obtain API credentials. The configuration form displays provider-specific instructions.

Bosta

Log in to your Bosta dashboard.
Navigate to Settings > API.
Generate a new API key and secret.
Copy the credentials and paste them in the Keddily configuration form.

Aramex

Contact Aramex to obtain your shipping account credentials.
You'll receive: Account Number, Username, Password, and PIN code.
Enter these credentials in the Keddily configuration form.

Other providers

For SMSA, Ajex, Fetchr, DHL, FedEx, and others, visit their developer portals or contact their support team to obtain API credentials. The configuration form will show specific field requirements for each provider.

Entering credentials in Keddily

Shipping Hub → Configure (on provider card)

Click Configure on the provider you want to connect.
The configuration form shows dynamic fields based on the provider's schema.
Fill in required fields (marked with *).
For password fields, existing values are masked for security. Leave blank to keep existing credentials.
Set Commission Rate (%) — this is the platform fee for shipping transactions.
Toggle Active to enable this provider for your store.
Click Save Configuration.

…/user/shipping-hub/configure/1

Configure Bosta

Setup Instructions
To obtain your Bosta API credentials, log in to your Bosta dashboard and navigate to Settings > API.

API Key *

API Secret *

Webhook URL

Commission Rate (%)

Save Configuration

Figure 2.2 — Provider configuration form

Testing the connection

After saving credentials, the provider card shows a connection status.
Connected — green indicator means credentials are valid.
Not Connected — red indicator means credentials need verification.
Click Test Connection (if available) to verify API access.
If connection fails, double-check your credentials and try again.

Some providers may require additional verification steps like IP whitelisting. Check the provider's documentation for requirements.

3 Creating shipments

After you connect a provider, Keddily can create shipments and labels for you. Most store owners only need the steps below — no coding required.

What you do as a store owner

Connect a shipping provider in Shipping Hub and set it to Active.
Test the connection so credentials are valid.
When an order arrives, open the order and Generate Label (or let auto-label run if enabled).
Print / download the shipping label and attach it to the package.
Track status updates on the order (Pending → Processing → In Transit → Delivered).

Tip: Configure providers once. The Shipping Hub handles label creation and tracking. Use manual Generate Label from the order page if automatic generation fails.

Order-to-shipment workflow

How a customer order becomes a tracked shipment:

Order placement — Customer completes checkout on your storefront.
Order validation — System checks shipping address and payment method.
Provider selection — Your active shipping provider is selected for the destination.
Label generation — The provider creates a tracking number and printable label.
Order update — Tracking info is saved and the order moves to Processing.
Pickup & tracking — Courier pickup (if applicable) and live tracking for you and the customer.

Order → Shipment Flow

1

Customer Checkout

↓

2

Order Created

↓

3

Provider Selected

↓

4

Label Generated

↓

5

Tracking Active

Figure 3.1 — Order to shipment workflow

For Developers — API payloads, adapters & advanced patterns

Optional technical reference for teams integrating programmatically with the Shipping Hub. Store owners can skip this section.

Payload structure

To create a shipment programmatically, provide sender, recipient, package details, COD amount, and order reference:

Field	Type	Description
`sender`	Object	Sender information (name, phone, address, city, country)
`recipient`	Object	Recipient information (name, phone, address, city, country)
`package`	Object	Package details (weight, dimensions, description)
`cod_amount`	Decimal	Cash on Delivery amount (0 for prepaid orders)
`currency`	String	Currency code (e.g., EGP, SAR, AED, USD)
`reference`	String	Order reference number for tracking
`provider`	String	Shipping provider identifier (e.g., 'bosta', 'aramex')

{
  "sender": {
    "name": "Store Name",
    "phone": "+201234567890",
    "email": "[email protected]",
    "address": "123 Main Street",
    "city": "Cairo",
    "country": "EG",
    "postal_code": "11511"
  },
  "recipient": {
    "name": "Customer Name",
    "phone": "+201098765432",
    "email": "[email protected]",
    "address": "456 Customer Road",
    "city": "Alexandria",
    "country": "EG",
    "postal_code": "21500"
  },
  "package": {
    "weight": 1.5,
    "length": 20,
    "width": 15,
    "height": 10,
    "description": "Electronics - Smartphone"
  },
  "cod_amount": 2500.00,
  "currency": "EGP",
  "reference": "ORD-2024-001234",
  "provider": "bosta"
}

Code examples (PHP / Laravel)

use App\Services\Shipping\ShippingAdapterFactory;
use App\Services\Shipping\Adapters\BostaAdapter;

$user = auth()->user();
$adapterFactory = new ShippingAdapterFactory($user);
$adapter = $adapterFactory->getAdapter('bosta');

if (!$adapter) {
    throw new \Exception('Bosta provider not configured');
}

$shipmentData = [
    'sender' => [
        'name' => $user->shop_name,
        'phone' => $user->phone,
        'email' => $user->email,
        'address' => $user->address,
        'city' => $user->city,
        'country' => 'EG',
        'postal_code' => $user->postal_code ?? '11511'
    ],
    'recipient' => [
        'name' => $order->customer_name,
        'phone' => $order->customer_phone,
        'email' => $order->customer_email,
        'address' => $order->shipping_address,
        'city' => $order->shipping_city,
        'country' => $order->shipping_country,
        'postal_code' => $order->shipping_postal_code
    ],
    'package' => [
        'weight' => $order->total_weight,
        'length' => $order->package_length ?? 20,
        'width' => $order->package_width ?? 15,
        'height' => $order->package_height ?? 10,
        'description' => 'Order #' . $order->order_number
    ],
    'cod_amount' => $order->payment_method === 'cod' ? $order->total : 0,
    'currency' => $order->currency_code,
    'reference' => $order->order_number,
    'provider' => 'bosta'
];

try {
    $response = $adapter->createShipment($shipmentData);
    $order->tracking_number = $response['tracking_number'];
    $order->shipping_cost = $response['shipping_cost'];
    $order->estimated_delivery = $response['estimated_delivery'];
    $order->status = 'processing';
    $order->save();
} catch (\Exception $e) {
    // Log and handle failure
}

Response handling

{
  "success": true,
  "tracking_number": "BOS-1234567890",
  "shipping_cost": 45.50,
  "currency": "EGP",
  "estimated_delivery": "2024-01-25",
  "label_url": "https://provider.example.com/labels/BOS-1234567890.pdf",
  "provider_reference": "PROV-987654321"
}

Common error scenarios

Missing configuration — Provider credentials not configured
Invalid address — Recipient address format is incorrect
Unsupported destination — Provider does not ship to that country
COD limit exceeded — COD amount exceeds provider maximum
API rate limit — Too many requests to the provider API
Authentication failed — Invalid API credentials

Advanced patterns

Multiple providers by country

$provider = match ($shipmentData['recipient']['country']) {
    'EG' => 'bosta',
    'SA' => 'smsa',
    'AE' => 'fetchr',
    default => 'aramex'
};
$adapter = $adapterFactory->getAdapter($provider);

Batch shipments

$orders = Order::where('status', 'pending')->get();
foreach ($orders as $order) {
    try {
        $adapter = $adapterFactory->getAdapter($order->shipping_provider);
        $response = $adapter->createShipment(prepareShipmentData($order));
        $order->update([
            'tracking_number' => $response['tracking_number'],
            'status' => 'processing'
        ]);
    } catch (\Exception $e) {
        Log::error("Shipment failed for order {$order->id}: " . $e->getMessage());
    }
}

Always implement error handling and logging when calling shipping APIs.

4 Operations & order fulfillment

Once providers are configured, shipping operations integrate with your order workflow.

Automatic label generation

When a new order is created, the system can automatically generate shipping labels (AWB) if:

A shipping provider is configured and active.
The order has a valid shipping address.
The order payment is confirmed (for COD orders, the COD amount is included).

Orders in Pending status are eligible for label generation.
The system sends shipment data to the configured provider's API.
The provider returns a tracking number and printable label.
The tracking number is saved to the order and displayed in the order details.
Order status updates to Processing when label is generated.

Cash on Delivery (COD) handling

COD orders require special handling for amount collection and currency rules:

COD amount — The order total is sent to the provider as the COD amount to collect.
Currency rules — Some providers only accept COD in specific currencies (e.g., EGP for Egypt providers).
Currency conversion — If your store uses a different currency, the system converts the COD amount to the provider's accepted currency.
COD fees — Some providers charge additional fees for COD orders. These are typically deducted from the collected amount.

Tip: Configure your Multi-Currency settings to ensure proper COD amount conversion for international providers.

Real-time shipment tracking

Track shipments and sync status changes from the provider to your order system:

Status	Description
Pending	Order created, awaiting label generation
Processing	Label generated, shipment picked up by carrier
In Transit	Package is on the way to delivery address
Delivered	Package successfully delivered to customer
Cancelled	Shipment cancelled or returned
Exception	Delivery issue (wrong address, refused, etc.)

Providers send webhook updates when shipment status changes.
Keddily receives these updates and syncs them to your order.
Order status updates automatically based on provider status.
Customers can track their orders using the tracking number on your storefront.

…/all/item/orders/1043

Order #1043

Tracking: BOS-12345678

Label Generated

Picked Up

In Transit

Delivered

Figure 4.1 — Order tracking timeline

Manual label generation

If automatic label generation fails or you need to regenerate:

Open the order details from All Orders.
Click Generate Label in the shipping section.
Select the shipping provider if multiple are available.
The system requests a new label from the provider.
Download or print the label for package attachment.

5 Simulation & manual modes

Test your shipping workflow without live carrier accounts using simulation and manual adapters.

Simulation adapter

The built-in Simulation Adapter lets you test store checkout and label generation without connecting to real carriers:

Testing checkout — Simulate the complete order-to-shipping workflow.
Label generation — Generates mock tracking numbers and labels.
Status updates — Simulates shipment status changes over time.
No costs — No actual shipping fees or API calls.

In Shipping Hub, find the Simulation provider.
Click Configure — minimal setup required (portal username/password).
Set optional parameters like Bot Delay (ms) and Success Rate (%).
Save and activate the simulation adapter.
Test your checkout flow — orders will use simulation for shipping.

Simulation is ideal for development, testing, and training. Switch to real providers when going live.

Manual shipping adapter

For local couriers without API integration, use the Manual adapter:

Contact-based — Configure phone and email for courier communication.
Label templates — Choose from standard A4 or thermal printer formats.
Pickup address — Set default pickup location for courier collection.
Manual tracking — Update shipment status manually in the order system.

In Shipping Hub, find Local Courier Manual.
Configure contact details (phone, email) for the courier.
Select label template and set pickup address.
Save and activate the manual adapter.
When orders use this provider, you'll need to manually coordinate with the courier.

Switching between providers

You can configure multiple providers and switch between them:

Configure credentials for multiple providers in Shipping Hub.
Set each provider's Active toggle to enable/disable.
When creating orders, select which provider to use (if multiple are active).
Deactivate a provider to stop using it for new orders.
Existing orders continue to use their originally assigned provider.

Tip: Use different providers for different regions or order types (e.g., Simulation for testing, Bosta for Egypt orders, Aramex for international).

6 Troubleshooting

Common issues and solutions

Issue	Solution
Connection fails	Verify API credentials are correct. Check if provider requires IP whitelisting.
Label generation error	Ensure order has valid address. Check if provider supports the destination country.
COD amount incorrect	Check currency conversion settings. Verify provider's accepted currency.
Tracking not updating	Check if webhooks are configured. Verify provider sends status updates.
Provider not listed	Contact Keddily support to request additional provider integration.

Getting help

If you encounter issues not covered here:

Check the provider's official documentation for API requirements.
Review the setup instructions in the configuration form.
Contact Keddily support through the Support section.