TuMicha

Connect your website to TuMicha

Use this page to link your company website so customers can place delivery orders through TuMicha, and so your site can show live order progress.

← Back to portal

1. Get ready in the portal

  1. Ask TuMicha to enable Integrations for your business account.
  2. Sign in to the company portal and open Integrations.
  3. Create a connection key and keep it private (only on your web server).
  4. Save your order update link — the address on your site that should receive delivery progress.
  5. Give your website developer the copy-paste examples below.

2. What your website needs

Your developer should send the connection key from your server only — never from a customer’s browser.

3. How to prove it’s your business

Every request from your site to TuMicha must include the connection key like this:

Authorization: Bearer tm_live_YOUR_KEY
Content-Type: application/json

Your developer can also send the same key as X-Api-Key.

4. JSON data exchange (website ↔ TuMicha)

Your website and TuMicha talk over HTTPS with JSON. There are two directions: your site creates and checks orders on TuMicha, and TuMicha pushes live status updates back to your order update link.

Website → TuMicha

Create a delivery when checkout finishes (POST /v1/deliveries). 

{
  "externalOrderId": "ORDER-10042",
  "serviceType": "delivery",
  "pickup": {
    "address": "Shop 12, Independence Way, Lusaka",
    "lat": -15.3875,
    "lng": 28.3228,
    "contact": "+260900000001"
  },
  "dropoff": {
    "address": "Customer Home, Cairo Road, Lusaka",
    "lat": -15.4167,
    "lng": 28.2833,
    "contact": "+260900000002"
  },
  "notes": "Leave with security if no one answers"
}

TuMicha replies with the created delivery (HTTP 201). Save delivery.id against your order. 

{
  "delivery": {
    "id": "8f3c2a1b-4d5e-6f70-8192-a3b4c5d6e7f8",
    "companyId": "c0mpany-uuid",
    "externalOrderId": "ORDER-10042",
    "serviceType": "delivery",
    "status": "created",
    "pickup": {
      "address": "Shop 12, Independence Way, Lusaka",
      "lat": -15.3875,
      "lng": 28.3228,
      "contact": "+260900000001"
    },
    "dropoff": {
      "address": "Customer Home, Cairo Road, Lusaka",
      "lat": -15.4167,
      "lng": 28.2833,
      "contact": "+260900000002"
    },
    "notes": "Leave with security if no one answers",
    "driverId": null,
    "driverName": null,
    "assignedAt": null,
    "createdAt": "2026-07-14T11:55:00.000Z",
    "updatedAt": "2026-07-14T11:55:00.000Z"
  }
}
TuMicha → Website

When status changes, TuMicha POSTs this JSON to your order update link. 

{
  "event": "delivery.status_changed",
  "occurredAt": "2026-07-14T12:00:00.000Z",
  "delivery": {
    "id": "8f3c2a1b-4d5e-6f70-8192-a3b4c5d6e7f8",
    "companyId": "c0mpany-uuid",
    "externalOrderId": "ORDER-10042",
    "serviceType": "delivery",
    "status": "assigned",
    "previousStatus": "created",
    "pickup": {
      "address": "Shop 12, Independence Way, Lusaka",
      "lat": -15.3875,
      "lng": 28.3228,
      "contact": "+260900000001"
    },
    "dropoff": {
      "address": "Customer Home, Cairo Road, Lusaka",
      "lat": -15.4167,
      "lng": 28.2833,
      "contact": "+260900000002"
    },
    "notes": "Leave with security if no one answers",
    "driverId": "driver-uuid",
    "driverName": "Chanda Banda",
    "driverVehiclePlate": "ABC 1234",
    "driverVehicleName": null,
    "driverVehicleModel": null,
    "assignedAt": "2026-07-14T12:00:00.000Z",
    "createdAt": "2026-07-14T11:55:00.000Z",
    "updatedAt": "2026-07-14T12:00:00.000Z"
  }
}

Your website should answer quickly with a success body (any 2xx is fine): 

{
  "received": true
}
Match orders with externalOrderId (your store order number). Use delivery.id for TuMicha’s id. Status values follow the progress list below.

5. Create a delivery from your checkout

When a customer finishes an order on your site, your server should ask TuMicha to create a delivery. Full request including headers: 

POST /v1/deliveries
Authorization: Bearer tm_live_YOUR_KEY
Content-Type: application/json

{
  "externalOrderId": "ORDER-10042",
  "serviceType": "delivery",
  "pickup": {
    "address": "Shop 12, Independence Way, Lusaka",
    "lat": -15.3875,
    "lng": 28.3228,
    "contact": "+260900000001"
  },
  "dropoff": {
    "address": "Customer Home, Cairo Road, Lusaka",
    "lat": -15.4167,
    "lng": 28.2833,
    "contact": "+260900000002"
  },
  "notes": "Leave with security if no one answers"
}
You must send an order number (externalOrderId) plus pickup and dropoff addresses. Adding map coordinates (lat / lng) helps drivers find the places faster. Use delivery or ride for the service type. TuMicha returns { "delivery": { ... } } as shown in section 4.

6. Check or cancel an order

GET    /v1/deliveries
GET    /v1/deliveries/:deliveryId
POST   /v1/deliveries/:deliveryId/cancel

You can cancel only while the order is still waiting for a driver (status created).

Example reply when you fetch one order:

{
  "delivery": {
    "id": "8f3c2a1b-4d5e-6f70-8192-a3b4c5d6e7f8",
    "externalOrderId": "ORDER-10042",
    "status": "in_transit",
    "driverName": "Chanda Banda",
    "driverVehiclePlate": "ABC 1234",
    "updatedAt": "2026-07-14T12:18:00.000Z"
  }
}

7. Delivery progress to expect

Waiting Driver assigned Picked up On the way Delivered

Your site may also receive cancelled or failed orders.

created → assigned → picked_up → in_transit → delivered
   ↓          ↓           ↓            ↓
cancelled  cancelled   failed       failed

Those names are what your website should store and show to customers.

8. Receive live updates on your website

When an order changes, TuMicha sends a message to the order update link you saved in Integrations. Your website should reply quickly to say it received the update. Full JSON shapes are in section 4.

Message headers:

Content-Type: application/json
User-Agent: TuMicha-Webhooks/1.0
X-TuMicha-Event: delivery.status_changed
Find the matching order with externalOrderId, update your customer page, then answer with { "received": true } (or any 2xx). If a message is missed, your site can also ask TuMicha for the latest status using the check order links above.

9. Copy-paste: listen for updates (Node)

Your developer can paste this on your website server, then save that address in Integrations.

const express = require('express');
const app = express();
app.use(express.json());

app.post('/updates/tumicha', (req, res) => {
  const { delivery } = req.body || {};

  if (!delivery?.id || !delivery?.status) {
    return res.status(400).json({ error: 'invalid payload' });
  }

  // Match your store order with delivery.externalOrderId, then update the customer.
  console.log('TuMicha update', {
    orderId: delivery.externalOrderId,
    status: delivery.status,
    previousStatus: delivery.previousStatus,
    driverName: delivery.driverName,
  });

  res.status(200).json({ received: true });
});

app.listen(3000);

10. Copy-paste: create a delivery from checkout

async function createTuMichaDelivery(order) {
  const response = await fetch('https://YOUR-TUMICHA-HOST/v1/deliveries', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer tm_live_YOUR_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      externalOrderId: order.id,
      serviceType: 'delivery',
      pickup: order.pickup,
      dropoff: order.dropoff,
      notes: order.notes,
    }),
  });

  if (!response.ok) {
    throw new Error(`TuMicha create failed: ${response.status}`);
  }

  const data = await response.json();
  return data.delivery; // save delivery.id against your order
}

11. Keep it safe