Partner API · v1

Courier Partner API

Integrate Vplaza deliveries into your own systems. Pull the open deliveries your company is eligible for, claim them, assign your own riders, and drive each one from pickup to drop-off — all over a simple REST API.

Base URL

https://api.usevplaza.com/v1/partner

This API is available to companies onboarded on the API integration path. Prefer no code? Your riders can use the Vplaza rider app instead.

Authentication

Every request is authenticated with your company's secret API key, issued once your company is verified and active. Find it in your dashboard under Developers. Send it as a bearer token (or an X-API-Key header). Keep it server-side and secret.

Authorization header

Authorization: Bearer sk_live_•••

All responses are JSON with a success boolean. Requests without a valid key return 401.

Sandbox

Every API partner gets two keys: a sandbox key (sk_test_…) and a live key (sk_live_…). Both are in your dashboard under Developers.

Call the exact same endpoints with your sandbox key and they run against isolated test data — no real orders, no payouts, no notifications, no effect on your riders. It's the safe way to build and test your integration before switching to the live key.

Test deliveries are auto-seeded. GET /deliveries with a sandbox key returns a few ready-to-use test jobs.
Codes are handed to you. Sandbox deliveries include their pickupCode and deliveryCode in the response, so you can complete the flow (in production the seller and buyer provide them).
Reset any time. POST /sandbox/reset wipes your test deliveries and seeds a fresh set.
Everything else is identical. Same request bodies, same response shapes, same error codes — only the data is fake.

reset your sandbox

curl -X POST https://api.usevplaza.com/v1/partner/sandbox/reset \
  -H "Authorization: Bearer sk_test_•••"

Delivery flow

A delivery moves through a few states. Two 4-digit codes make each hand-off verifiable:

1
Poll available deliveries
GET /deliveries returns open jobs in the areas you cover.
2
Claim one
POST /deliveries/:id/accept — atomic, so it can't be double-claimed. Optionally assign a rider now.
3
Assign a rider
POST /deliveries/:id/assign if you didn't at claim time.
4
Confirm pickup
POST /deliveries/:id/pickup with the seller's pickup code → order goes in-transit.
5
Complete delivery
POST /deliveries/:id/deliver with the buyer's delivery code → seller is paid, trip done.

Errors

Standard HTTP status codes; the body carries a message.

400Bad request — a required field is missing or invalid.

401Missing or invalid API key.

403Your company isn't active, or doesn't cover this delivery's area.

404The delivery, rider or resource wasn't found.

409Conflict — this delivery has already been taken.

Account

Confirm your key works and see what your company covers.

GET/me

Get your company

Returns the company the API key belongs to. Use it to verify authentication.

Request

curl https://api.usevplaza.com/v1/partner/me \
  -H "Authorization: Bearer sk_live_•••"

Response

{
  "success": true,
  "data": {
    "id": "665f1c...",
    "name": "Swift Logistics Ltd",
    "status": "active",
    "country": "Nigeria",
    "coverageAreas": [{ "state": "Lagos", "city": null }],
    "vehicleTypes": ["bike", "van"]
  }
}

Riders

GET/riders

List riders

All riders belonging to your company.

Request

curl https://api.usevplaza.com/v1/partner/riders \
  -H "Authorization: Bearer sk_live_•••"

Response

{
  "success": true,
  "count": 1,
  "data": [
    {
      "_id": "6660a1...",
      "fullName": "Musa Bello",
      "email": "musa@swift.co",
      "phone": "08031234567",
      "vehicleType": "bike",
      "plateNumber": "LND-482-KJA",
      "status": "active",
      "isOnline": false,
      "rating": 0,
      "totalRides": 0
    }
  ]
}

POST/riders

Register a rider

Create a rider under your company. Photos are optional over the API.

Body parameters

fullNamestringrequired

Rider's full name.

emailstringrequired

phonestringrequired

Contact phone.

passwordstringrequired

At least 6 characters.

vehicleTypestringoptional

bicycle | bike | car | van | truck. Default bike.

plateNumberstringoptional

Required unless vehicleType is bicycle.

vehicleImagestring (url)optional

Optional photo URL.

passportImagestring (url)optional

Optional photo URL.

Request

curl -X POST https://api.usevplaza.com/v1/partner/riders \
  -H "Authorization: Bearer sk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Musa Bello",
    "email": "musa@swift.co",
    "phone": "08031234567",
    "password": "s3cret!",
    "vehicleType": "bike",
    "plateNumber": "LND-482-KJA"
  }'

Response

{
  "success": true,
  "data": { "_id": "6660a1...", "fullName": "Musa Bello", "status": "active" }
}

Deliveries

Pull open jobs, claim them for your company, and assign your riders.

GET/deliveries

Available deliveries

Open deliveries your company is eligible for — anything unclaimed in a state you cover.

Request

curl https://api.usevplaza.com/v1/partner/deliveries \
  -H "Authorization: Bearer sk_live_•••"

Response

{
  "success": true,
  "count": 1,
  "data": [
    {
      "_id": "6661de...",
      "orderId": "VPZ-2A9F",
      "deliveryFee": 2400,
      "deliveryAddress": "12 Admiralty Way, Lekki",
      "deliveryCoordinates": { "type": "Point", "coordinates": [3.47, 6.44] },
      "store": {
        "name": "Bloom Groceries",
        "address": "5 Adeola Odeku St",
        "state": "Lagos",
        "phoneNumber": "+2348012345678",
        "location": { "type": "Point", "coordinates": [3.42, 6.43] }
      },
      "product": { "name": "Fresh Produce Box", "image": "https://..." }
    }
  ]
}

GET/deliveries/mine

Your deliveries

Deliveries your company has claimed. Filter with ?status=assigned|picked_up|delivered.

Request

curl "https://api.usevplaza.com/v1/partner/deliveries/mine?status=assigned" \
  -H "Authorization: Bearer sk_live_•••"

Response

{
  "success": true,
  "count": 1,
  "data": [
    {
      "_id": "6662ff...",
      "status": "assigned",
      "fee": 2400,
      "pickupAddress": "Bloom Groceries",
      "dropoffAddress": "12 Admiralty Way, Lekki",
      "order": { "orderId": "VPZ-2A9F", "status": "Accepted" },
      "rider": { "fullName": "Musa Bello", "phone": "08031234567" }
    }
  ]
}

POST/deliveries/:orderId/accept

Claim a delivery

Atomically claim an open delivery for your company. Pass riderId to assign a rider at the same time. If another party already claimed it, you get 409.

Body parameters

riderIdstringoptional

Optional. One of your riders to assign immediately.

Request

curl -X POST https://api.usevplaza.com/v1/partner/deliveries/6661de.../accept \
  -H "Authorization: Bearer sk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "riderId": "6660a1..." }'

Response

{
  "success": true,
  "message": "Delivery claimed",
  "data": {
    "_id": "6662ff...",
    "status": "assigned",
    "order": "6661de...",
    "rider": "6660a1...",
    "fee": 2400
  }
}

POST/deliveries/:orderId/assign

Assign a rider

Assign or reassign one of your riders to a delivery you've already claimed.

Body parameters

riderIdstringrequired

The rider to assign.

Request

curl -X POST https://api.usevplaza.com/v1/partner/deliveries/6661de.../assign \
  -H "Authorization: Bearer sk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "riderId": "6660a1..." }'

Response

{ "success": true, "message": "Rider assigned", "data": { "_id": "6662ff...", "rider": "6660a1..." } }

POST/deliveries/:orderId/pickup

Confirm pickup

Confirm your rider collected the package, using the pickup code the seller provides. Moves the order to in-transit.

Body parameters

codestringrequired

4-digit pickup code from the seller.

Request

curl -X POST https://api.usevplaza.com/v1/partner/deliveries/6661de.../pickup \
  -H "Authorization: Bearer sk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "code": "4821" }'

Response

{ "success": true, "message": "Pickup confirmed", "data": { "status": "picked_up" } }

POST/deliveries/:orderId/deliver

Complete delivery

Complete the delivery using the delivery code the buyer provides on hand-off. Releases the seller's funds and finalises the trip.

Body parameters

codestringrequired

4-digit delivery code from the buyer.

Request

curl -X POST https://api.usevplaza.com/v1/partner/deliveries/6661de.../deliver \
  -H "Authorization: Bearer sk_live_•••" \
  -H "Content-Type: application/json" \
  -d '{ "code": "7390" }'

Response

{ "success": true, "message": "Delivery completed", "data": { "status": "delivered" } }

Vplaza Courier · Partner API v1 · Base URL https://api.usevplaza.com/v1/partner