Custom Ecommerce Integration

For businesses using bespoke platforms or headless architectures (like Next.js, Laravel, or Django), our APIs provide full control over the logistics and commerce experience.

Integration Architecture

A typical custom integration involves three main flows:

1. Checkout (Quote): Getting real-time delivery fees to show to the customer.
2. Fulfillment (Request): Initiating the delivery once payment is confirmed.
3. Tracking (Status): Providing live updates to the customer.

Workflow Diagram

graph TD
    A[Customer Checkout] --> B[Request Delivery Quote]
    B --> C[Show Fee & ETA]
    C --> D[Payment Confirmed]
    D --> E[Create Delivery Request]
    E --> F[Rider Assigned]
    F --> G[Webhook: Status Updates]
    G --> H[Customer Tracking UI]

1. Getting a Quote at Checkout

When a customer enters their address, use the Delivery Quote API to fetch real-time pricing.

{
  "pickup_address": "Your Store Location",
  "dropoff_address": "Customer's Address",
  "package_type": "standard"
}

2. Initiating Fulfillment

Once the order is paid, call the Create Delivery API. We recommend storing our delivery_id in your database alongside your internal order_id.

3. Real-time Status via Webhooks

Configure a Webhook to listen for status changes. When you receive a delivery.completed event, update the order status in your system to "Delivered".

Implementation Tips

• Pre-calculate Coordinates: For better accuracy, use a Geocoding service to convert addresses into lat/lng before calling our APIs.
• Handle Edge Cases: Always have a fallback shipping rate in case the API is unreachable or the customer is outside a delivery zone.
• Idempotency: Use our Idempotency-Key header when creating deliveries to prevent duplicate rider requests in case of network retries.

Sample Integration (Node.js)

// Example: Creating a delivery when an order is paid
app.post('/webhooks/payment-confirmed', async (req, res) => {
  const { orderId, customerAddress } = req.body;
  
  try {
    const delivery = await safaribid.deliveries.create({
      pickup: { address: 'Main Warehouse, Nairobi' },
      dropoff: { address: customerAddress },
      package: { type: 'standard' },
      payment_method: 'wallet'
    });
    
    await db.orders.update(orderId, { 
      status: 'dispatched',
      delivery_id: delivery.id 
    });
    
    res.sendStatus(200);
  } catch (err) {
    console.error('Logistics dispatch failed:', err);
    res.sendStatus(500);
  }
});