Partner API v1.0 路 12 Operations Available

Build Reliable On-Demand Delivery Workflows.

Integrate Movve logistics directly into your checkout or ERP. Complete guides, curl snippets, and an interactive trial console for every partner endpoint.

API Key Auth

Test and Live secret keys authenticate your delivery requests via X-API-Key.

Delivery Lifecycle

Request quotes, dispatch orders, track real-time rider position, and verify OTPs.

Signed Webhooks

Receive HMAC SHA-256 signed event notifications whenever delivery states update.

Authentication

Authenticating with the Movve Partner API requires an active secret key sent in the X-API-Key request header.

Header Standard

Test secret keys start with mv_test_ and operate safely in sandbox mode. Live keys start with mv_live_ and route orders to active riders.

Interactive API Console

Select an environment and run requests directly against your active partner credentials.

API secret tokens are injected securely on server proxy endpoints and are never rendered into client JavaScript DOM.

Webhook Verification

Verify incoming webhooks using HMAC SHA-256 against the signature in x-movve-signature.

webhook-verifier.ts
const expected = crypto
  .createHmac('sha256', webhookSecret)
  .update(timestamp + '.' + rawRequestBody)
  .digest('hex');

const valid = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(request.headers['x-movve-signature'])
);

Error Envelopes

All error responses return standard HTTP status codes along with a structured JSON error body.

error-envelope.json
{
  "statusCode": 400,
  "message": "Missing required field",
  "error": "BadRequest",
  "timestamp": "2026-07-26T00:00:00.000Z",
  "path": "/api/v1/partner/deliveries"
}
API Specification Reference

Delivery API

POST/api/v1/partner/quotes

Create a delivery quote

Calculates delivery pricing from pickup, destination, and package details.

Request Example

cURL
curl -X POST https://api.movve.xyz//api/v1/partner/quotes \
  -H "X-API-Key: mv_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "pickup": {
    "lat": 6.5244,
    "lng": 3.3792,
    "address": "Victoria Island, Lagos"
  },
  "dropoff": {
    "lat": 6.6018,
    "lng": 3.3515,
    "address": "Ikeja, Lagos"
  },
  "packageDetails": {
    "size": "SMALL",
    "category": "GENERAL"
  }
}'

Response Payload 路 201

JSON
{
  "id": "quote_uuid",
  "baseCost": 2500,
  "commission": 500,
  "fee": 3000,
  "currency": "NGN",
  "durationMins": 35
}

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.
POST/api/v1/partner/deliveries

Create a delivery

Creates a delivery for a pharmacy, food, ecommerce, or general order after the merchant has confirmed it is ready for rider pickup.

馃挕 The `Idempotency-Key` header is required and must be unique per intended delivery.

馃挕 Create the delivery only after the merchant accepts and prepares the order.

馃挕 Do not send prescriptions, medical records, food recipes, or unnecessary customer data.

馃挕 Use orderType FOOD, ECOMMERCE, or GENERAL for other partner verticals.

Request Example

cURL
curl -X POST https://api.movve.xyz//api/v1/partner/deliveries \
  -H "X-API-Key: mv_test_your_key" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{
  "partnerReference": "rubimedik_order_uuid",
  "orderNumber": "RM-1001",
  "orderType": "PHARMACY",
  "branchReference": "pharmacy_branch_uuid",
  "branchName": "RubiMedik Pharmacy 路 Ikeja",
  "pickup": {
    "address": "10 Medical Road, Ikeja",
    "lat": 6.6018,
    "lng": 3.3515,
    "contactName": "Pharmacist Ada",
    "contactPhone": "+2348012345678"
  },
  "dropoff": {
    "address": "Victoria Island, Lagos",
    "lat": 6.5244,
    "lng": 3.3792,
    "contactName": "Patient",
    "contactPhone": "+2348098765432"
  },
  "packageDetails": {
    "size": "SMALL",
    "category": "PRESCRIPTION",
    "description": "Sealed medication package",
    "quantity": 2,
    "fragile": true,
    "specialHandling": "KEEP_UPRIGHT"
  },
  "pickupInstructions": "Collect from the pharmacy dispatch desk.",
  "deliveryInstructions": "Call the recipient on arrival.",
  "paymentStatus": "PAID",
  "requiresOtpAtPickup": true,
  "requiresOtpOnDelivery": true,
  "requiresProofOfDelivery": true,
  "pickupVerificationUrl": "https://api.rubimedik.example/movve/verify-pickup-otp",
  "deliveryVerificationUrl": "https://api.rubimedik.example/movve/verify-delivery-otp",
  "callbackUrl": "https://api.rubimedik.example/webhooks/movve"
}'

Response Payload 路 201

JSON
{
  "id": "delivery_uuid",
  "partnerReference": "rubimedik_order_uuid",
  "orderNumber": "RM-1001",
  "orderType": "PHARMACY",
  "status": "PENDING",
  "quotedFee": 3000,
  "currency": "NGN"
}

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.
GET/api/v1/partner/deliveries

List deliveries

Returns deliveries created by the authenticated partner.

Request Example

cURL
curl -X GET https://api.movve.xyz//api/v1/partner/deliveries \
  -H "X-API-Key: mv_test_your_key"

Response Payload 路 200

JSON
[
  {
    "id": "delivery_uuid",
    "externalReference": "ORDER-1001",
    "status": "IN_TRANSIT",
    "fee": 3000
  }
]

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

This endpoint takes no route parameters or request body payload.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.
GET/api/v1/partner/deliveries/{id}

Get a delivery

Returns one delivery and its current lifecycle information.

Request Example

cURL
curl -X GET https://api.movve.xyz//api/v1/partner/deliveries/DELIVERY_ID \
  -H "X-API-Key: mv_test_your_key"

Response Payload 路 200

JSON
{
  "id": "delivery_uuid",
  "status": "IN_TRANSIT",
  "pickup": {
    "address": "Victoria Island, Lagos"
  },
  "dropoff": {
    "address": "Ikeja, Lagos"
  },
  "fee": 3000
}

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.
POST/api/v1/partner/deliveries/{id}/cancel

Cancel a delivery

Cancels an active delivery if it has not yet reached final delivery status.

Request Example

cURL
curl -X POST https://api.movve.xyz//api/v1/partner/deliveries/DELIVERY_ID/cancel \
  -H "X-API-Key: mv_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer cancelled order before pickup"
}'

Response Payload 路 201

JSON
{
  "id": "delivery_uuid",
  "status": "CANCELLED",
  "cancellationReason": "Customer cancelled order before pickup"
}

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.
GET/api/v1/partner/deliveries/{id}/track

Track a delivery

Returns real-time rider coordinates, ETA, and progress status for active orders.

Request Example

cURL
curl -X GET https://api.movve.xyz//api/v1/partner/deliveries/DELIVERY_ID/track \
  -H "X-API-Key: mv_test_your_key"

Response Payload 路 200

JSON
{
  "deliveryId": "delivery_uuid",
  "status": "IN_TRANSIT",
  "driver": {
    "name": "Chidi O.",
    "phone": "+2348000000000",
    "lat": 6.525,
    "lng": 3.378
  },
  "etaMinutes": 12
}

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.
POST/api/v1/partner/deliveries/{id}/pickup/verify-otp

Verify pickup OTP

Verifies the six-digit pickup verification OTP provided by the merchant.

Request Example

cURL
curl -X POST https://api.movve.xyz//api/v1/partner/deliveries/DELIVERY_ID/pickup/verify-otp \
  -H "X-API-Key: mv_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "otp": "123456"
}'

Response Payload 路 201

JSON
{
  "deliveryId": "delivery_uuid",
  "pickupVerified": true,
  "status": "PICKED_UP"
}

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.
POST/api/v1/partner/deliveries/{id}/proof-of-delivery/verify-otp

Verify delivery OTP

Verifies the six-digit delivery verification OTP provided by the recipient.

Request Example

cURL
curl -X POST https://api.movve.xyz//api/v1/partner/deliveries/DELIVERY_ID/proof-of-delivery/verify-otp \
  -H "X-API-Key: mv_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "otp": "654321"
}'

Response Payload 路 201

JSON
{
  "deliveryId": "delivery_uuid",
  "deliveryVerified": true,
  "status": "DELIVERED"
}

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.
POST/api/v1/partner/deliveries/{id}/proof-of-delivery

Record proof of delivery

Records recipient signature or photo proof of delivery.

Request Example

cURL
curl -X POST https://api.movve.xyz//api/v1/partner/deliveries/DELIVERY_ID/proof-of-delivery \
  -H "X-API-Key: mv_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "recipientName": "Patient Name",
  "signatureUrl": "https://cdn.movve.com/sig.png",
  "notes": "Handed directly to recipient"
}'

Response Payload 路 201

JSON
{
  "deliveryId": "delivery_uuid",
  "proofRecorded": true,
  "status": "DELIVERED"
}

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.
POST/api/v1/partner/deliveries/{id}/outcome

Record delivery outcome

Records successful or failed delivery resolution.

Request Example

cURL
curl -X POST https://api.movve.xyz//api/v1/partner/deliveries/DELIVERY_ID/outcome \
  -H "X-API-Key: mv_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "outcome": "SUCCESSFUL",
  "notes": "Delivery completed without issue"
}'

Response Payload 路 201

JSON
{
  "deliveryId": "delivery_uuid",
  "outcome": "SUCCESSFUL",
  "status": "COMPLETED"
}

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.
POST/api/v1/partner/webhooks/test

Send test webhook event

Triggers a simulated delivery update event to test partner endpoint handling.

Request Example

cURL
curl -X POST https://api.movve.xyz//api/v1/partner/webhooks/test \
  -H "X-API-Key: mv_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "event": "delivery.updated",
  "deliveryId": "delivery_uuid"
}'

Response Payload 路 201

JSON
{
  "eventSent": true,
  "targetUrl": "https://api.rubimedik.example/webhooks/movve",
  "statusCode": 200
}

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.
POST/api/v1/partner/sandbox/deliveries/{id}/advance-status

Advance delivery status (Test Mode)

Advances a test delivery through lifecycle states in sandbox mode.

Request Example

cURL
curl -X POST https://api.movve.xyz//api/v1/partner/sandbox/deliveries/DELIVERY_ID/advance-status \
  -H "X-API-Key: mv_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "targetStatus": "IN_TRANSIT"
}'

Response Payload 路 201

JSON
{
  "deliveryId": "delivery_uuid",
  "previousStatus": "DRIVER_ASSIGNED",
  "currentStatus": "IN_TRANSIT"
}

Interactive Execution 路 Test Mode

Execute API calls and inspect live HTTP headers, timings, and JSON responses.

Response Inspector
Click "Send Request" to view real status codes, execution latency, and JSON payload responses.