API referencev1

Partner Delivery API

Use one endpoint to quote, book, track, cancel, or configure delivery notifications.

Sandbox base URL: https://sandbox.krate.ng

POSThttps://sandbox.krate.ng/api/v1/partner/delivery

AuthenticationBearer token

WebhooksHMAC-SHA256

₦CurrencyNGN

Authentication

Send your Krate secret API key as a bearer token. Keep this key on your server; never expose it in browser or mobile-app code.

HTTP

Authorization: Bearer sec_your_secret_key_X
Content-Type: application/json

Treat secret keys like passwords. Store them in encrypted environment variables and rotate any key that may have been exposed.

Select a host delivery partner

Send X-Business-Id when a specific Krate host business should price and fulfil the delivery.

HTTP

Authorization: Bearer sec_your_secret_key_X
Content-Type: application/json
X-Business-Id: 64f1234567890abcdef12345

The secret API key identifies the business placing the order. X-Business-Id identifies the host delivery partner. The host’s pricing, minimum fees, vehicle settings, weight rules, and interstate configuration are used.

Important

Send the same X-Business-Id on both quote and booking requests—even when booking with a quoteReference.

Get a quote

Set action to quote. If vehicleType is omitted, the response contains prices for every available vehicle.

JSON · Request

{
  "action": "quote",
  "pickup": "1 Marina Road, Lagos, Nigeria",
  "dropoff": "10 Admiralty Way, Lekki Phase 1, Lagos, Nigeria",
  "vehicleType": "bike",
  "weight": 3,
  "date": "2026-09-12T09:00:00.000Z"
}

Or run the same request against https://sandbox.krate.ng. Set SUPPLIO_SECRET_KEY and SUPPLIO_HOST_BUSINESS_ID first.

cURL

curl --request POST \
  "https://sandbox.krate.ng/api/v1/partner/delivery" \
  --header "Authorization: Bearer $SUPPLIO_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --header "X-Business-Id: $SUPPLIO_HOST_BUSINESS_ID" \
  --data '{
    "action": "quote",
    "pickup": "1 Marina Road, Lagos, Nigeria",
    "dropoff": "10 Admiralty Way, Lekki Phase 1, Lagos, Nigeria",
    "vehicleType": "bike",
    "weight": 3,
    "date": "2026-09-12T09:00:00.000Z"
  }'

The standard price is in data.quote.totals. If an eligible fixed-price pool is returned, charge data.quote.poolEnrollment.chargeNow instead. All amounts are in Nigerian naira. Quotes include a reference and expire after 15 minutes by default.

JSON · Response

{
  "success": true,
  "data": {
    "action": "quote",
    "quoteReference": "QT_7A10B15C9D21",
    "expiresAt": "2026-08-23T12:15:00.000Z",
    "quote": {
      "totals": { "bike": 2500 },
      "currency": "NGN",
      "poolEnrollment": {
        "matched": true,
        "applied": true,
        "poolId": "POOL-FIXED-1",
        "pricingMode": "fixed",
        "chargeNow": 1500,
        "maximumPrice": 2500,
        "paymentRequiredUpfront": true
      }
    }
  }
}

Book a delivery

Set action to book. Use the saved quote for route, price, and expiry protection. A booking fails safely if its price has changed.

An idempotency key is required. Give every booking a unique Idempotency-Key so a network retry cannot create the delivery twice.

HTTP · Headers

Idempotency-Key: order-1001-delivery
X-Business-Id: 64f1234567890abcdef12345

JSON · Request

{
  "action": "book",
  "quoteReference": "QT_7A10B15C9D21",
  "reference": "ORDER-1001",
  "vehicleType": "bike",
  "sender": {
    "name": "Ada Store",
    "phone": "08012345678",
    "notes": "Ask for Ada at reception"
  },
  "recipient": {
    "name": "Tolu Ade",
    "phone": "08087654321"
  },
  "pickupAccess": {
    "shopReference": "Shop B12",
    "floorOrSection": "First floor"
  },
  "paymentMethod": "online",
  "redirectUrl": "https://your-business.example/orders/1001"
}

cURL

curl --request POST \
  "https://sandbox.krate.ng/api/v1/partner/delivery" \
  --header "Authorization: Bearer $SUPPLIO_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --header "X-Business-Id: $SUPPLIO_HOST_BUSINESS_ID" \
  --header "Idempotency-Key: order-1001-delivery" \
  --data '{
    "action": "book",
    "quoteReference": "QT_7A10B15C9D21",
    "reference": "ORDER-1001",
    "vehicleType": "bike",
    "sender": {
      "name": "Ada Store",
      "phone": "08012345678",
      "notes": "Ask for Ada at reception"
    },
    "recipient": {
      "name": "Tolu Ade",
      "phone": "08087654321"
    },
    "pickupAccess": {
      "shopReference": "Shop B12",
      "floorOrSection": "First floor"
    },
    "paymentMethod": "online",
    "redirectUrl": "https://your-business.example/orders/1001"
  }'

When quoteReference is supplied, do not repeat pickup or dropoff. Direct booking without a quote remains supported by sending both addresses.

Fixed-price pools

Krate automatically checks the delivery route, date, vehicle and host against fixed-price pools. A match is returned as poolEnrollment on both quote and booking responses. Cashback pools are excluded and continue as ordinary non-pool deliveries. Partners cannot submit a pool ID or override the server-owned pool price.

Market and mall addresses can include pickupAccess or dropoffAccess. Provide shopReference; optionally add floorOrSection, landmark, and instructions.

paymentMethodBehaviour

onlineDefault. Returns a payment link when payment is required.

walletPays from the API-key owner’s Krate wallet.

pay_on_deliveryThe recipient pays at delivery.

For compatibility, paymentType also accepts wallet or flutterwave. If both fields are sent, they must represent the same option.

201 · Response

{
  "success": true,
  "message": "Delivery booked successfully",
  "data": {
    "action": "book",
    "delivery": {
      "id": "internal_delivery_id",
      "reference": "SUP1234567",
      "status": "unpaid",
      "deliveryFee": 2400,
      "total": 2500,
      "currency": "NGN"
    },
    "payment": {
      "link": "https://payment-link.example"
    },
    "poolEnrollment": {
      "matched": true,
      "applied": true,
      "poolId": "POOL-FIXED-1",
      "pricingMode": "fixed",
      "chargeNow": 1500,
      "maximumPrice": 2500,
      "paymentRequiredUpfront": true
    }
  }
}

Track a delivery

Track using the Krate reference returned by booking or your own reference.

JSON · Request

{
  "action": "track",
  "deliveryReference": "SUP1234567"
}

cURL

curl --request POST \
  "https://sandbox.krate.ng/api/v1/partner/delivery" \
  --header "Authorization: Bearer $SUPPLIO_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "track",
    "deliveryReference": "SUP1234567"
  }'

The response contains delivery and payment statuses, payment method and amount, route, rider details when assigned, timeline, timestamps, and a tracking URL. Tracking is restricted to deliveries owned by the authenticated business.

Cancel a delivery

Cancel using the Krate reference or your own reference. An idempotency key is recommended.

JSON · Request

{
  "action": "cancel",
  "deliveryReference": "ORDER-1001",
  "reason": "Customer cancelled the order"
}

cURL

curl --request POST \
  "https://sandbox.krate.ng/api/v1/partner/delivery" \
  --header "Authorization: Bearer $SUPPLIO_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: cancel-order-1001" \
  --data '{
    "action": "cancel",
    "deliveryReference": "ORDER-1001",
    "reason": "Customer cancelled the order"
  }'

Deliveries that have started or completed cannot be cancelled. Eligible prepaid deliveries are refunded, and the response includes the refund amount.

Configure signed webhooks

JSON · Request

{
  "action": "configure_webhook",
  "webhook": {
    "url": "https://your-business.example/webhooks/supplio",
    "events": [
      "delivery.created",
      "delivery.assigned",
      "delivery.in_transit",
      "delivery.completed",
      "delivery.cancelled",
      "payment.succeeded",
      "payment.failed",
      "payment.refunded"
    ],
    "description": "Production delivery updates"
  }
}

cURL

curl --request POST \
  "https://sandbox.krate.ng/api/v1/partner/delivery" \
  --header "Authorization: Bearer $SUPPLIO_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "configure_webhook",
    "webhook": {
      "url": "https://your-business.example/webhooks/supplio",
      "events": [
        "delivery.created",
        "delivery.assigned",
        "delivery.in_transit",
        "delivery.completed",
        "delivery.cancelled",
        "payment.succeeded",
        "payment.failed",
        "payment.refunded"
      ],
      "description": "Production delivery updates"
    }
  }'

The 201 response contains a whsec_ secret. Save it immediately—it is returned only once.

Failed requests are retried automatically. Callback URLs must use HTTPS, resolve to a public IP address, and cannot redirect Krate.

Verify each callback

HTTP · Headers

X-Supplio-Event: delivery.completed
X-Supplio-Delivery-Id: webhook_attempt_id
X-Supplio-Timestamp: 1787486400
X-Supplio-Signature: t=1787486400,v1=hex_digest

Compute HMAC-SHA256 with the webhook secret over the following value and compare it to v1:

TEXT

<X-Supplio-Timestamp>.<raw JSON request body>

Reject invalid signatures and timestamps older than five minutes. The payload includes the delivery reference, partner reference, quote reference, status, route, rider, and timestamps.

Address formats

The simplest format is a full address string. Krate uses Google Maps to resolve its coordinates. You can also send known coordinates to avoid geocoding.

JSON

{
  "address": "1 Marina Road, Lagos, Nigeria",
  "latitude": 6.4511,
  "longitude": 3.3884,
  "state": "Lagos"
}

lat and lng are also accepted. Coordinate-only locations are reverse geocoded for interstate detection. Include city, state, country, and a landmark where possible to prevent ambiguous matches.

Optional delivery fields

FieldAccepted values

serviceTypeeconomy, standard, express

deliveryModedoor_delivery, hub_pickup

itemValueNumber

declaredValueNumber

includeInsuranceBoolean

dateISO 8601 delivery date and time

pickupAccessShop reference plus optional floor, landmark, and instructions

dropoffAccessShop reference plus optional floor, landmark, and instructions

metadataFree-form object (booking only)

Errors

Errors use a consistent shape and an appropriate HTTP status.

JSON · Error response

{
  "success": false,
  "message": "We could not locate the pickup address. Please make it more specific."
}

Next stepMake your first quote request