API Documentation

Reference for approved API partners integrating with the DBGL delivery API.

1. Getting Started

1. Sign up at apip/signup with your business and contact details.
2. Our team reviews and approves your application in CPN.
3. On approval, you're emailed an api_key and api_secret (the secret is shown only once, so store it securely).

2. Authentication

Every call to apip/api/ requires both headers:

X-Api-Key: your_api_key
X-Api-Secret: your_api_secret

There is no session/cookie auth and no CSRF token for the API — it's stateless, key-authenticated per request. A suspended or not-yet-approved client will get a 401.

3. Create Order

POST /apip/api/orders_create.php

Required fields:

• partner_order_ref — your own order number. Also used as an idempotency key: posting the same value again returns the existing order (HTTP 200) instead of creating a duplicate.
• vendor_name, vendor_phone, vendor_address, vendor_city, vendor_state — the pickup point (your vendor).
• customer_name, customer_phone, delivery_address, delivery_city, delivery_state — the dropoff (your customer).
• package_description

Optional fields:

• vendor_email, vendor_street, delivery_street
• weight_kg, declared_value, special_instructions
• service_type — defaults to standard (also accepts express)
• pickup_latitude / pickup_longitude, delivery_latitude / delivery_longitude — strongly recommended; without coordinates the distance can't be calculated and the order falls into manual review (see below).

Example request:

curl -X POST https://yourdomain/apip/api/orders_create.php \
  -H "X-Api-Key: your_api_key" \
  -H "X-Api-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_order_ref": "MKT-00123",
    "vendor_name": "Acme Vendor Store",
    "vendor_phone": "08011112222",
    "vendor_address": "12 Adeola Odeku St, Victoria Island",
    "vendor_city": "Victoria Island",
    "vendor_state": "Lagos",
    "pickup_latitude": 6.4281,
    "pickup_longitude": 3.4219,
    "customer_name": "Chidi Customer",
    "customer_phone": "08033334444",
    "delivery_address": "5 Bourdillon Rd, Ikoyi",
    "delivery_city": "Ikoyi",
    "delivery_state": "Lagos",
    "delivery_latitude": 6.4531,
    "delivery_longitude": 3.4342,
    "package_description": "Electronics package",
    "weight_kg": 2.5,
    "service_type": "standard"
  }'

Example response (201 Created):

{
  "order_id": "ORD293535848",
  "waybill_no": "WB459009877",
  "status": "confirmed",
  "total_amount": 3687,
  "currency": "NGN",
  "review_required": false,
  "delivery_pin": "384920"
}

If review_required is true and status is on_hold, we couldn't automatically resolve the pickup/delivery zone or pricing (usually an unrecognized city name, or missing coordinates). The order still exists with a waybill — our ops team resolves pricing manually, and the status will update once confirmed. Check back via the status endpoint below.

delivery_pin is the 6-digit code your recipient (or you) will need to give the rider to confirm delivery — the same code shown on our internal delivery-confirmation screens. It's null until the order is confirmed: immediately for a normal order, or once our ops team resolves an on_hold one. Poll the status endpoint below if it's not present yet.

4. Check Status

GET /apip/api/orders_status.php?order_id=ORD293535848

or by your own reference:

GET /apip/api/orders_status.php?partner_order_ref=MKT-00123

Example response (200 OK):

{
  "order_id": "ORD293535848",
  "partner_order_ref": "MKT-00123",
  "status": "confirmed",
  "waybill_no": "WB459009877",
  "shipment_status": "pending_assignment",
  "delivery_pin": "384920",
  "total_amount": 3687,
  "currency": "NGN",
  "created_at": "2026-07-28 09:01:46",
  "confirmed_at": null,
  "picked_up_at": null,
  "delivered_at": null,
  "cancelled_at": null
}

Lookups are scoped to your own API client — an order created by another partner, or an unknown order_id/partner_order_ref, always returns 404. This is polling only; there is currently no webhook/push notification for status changes.

5. Errors

Errors are returned as JSON in this shape:

{
  "error": {
    "code": "invalid_credentials",
    "message": "Invalid API key or secret."
  }
}

Status	When
401	Missing/invalid API key or secret, or the client is not approved/suspended
404	Order not found, or not owned by this API client
422	Missing required field or malformed request
500	Unexpected server error