Quickstart

Follow these steps to call the Business API from your server.

1. Create a Business account

Sign up or log in to the Business Dashboard, then complete your business profile (pickup address and phone are used as defaults when placing orders).

Staging: Sign up ↗ · Log in ↗
Production: Sign up ↗ · Log in ↗

2. Generate an API key

Open Developers → Setup in the side menu. Generate an API key (and configure your webhook on the same page).

Run Business Developers Setup page showing Manage API Key and Manage Webhook — Business Dashboard → Developers → Setup — API key and webhook configuration

Staging:     run_test_fce859d98c4f0e2b1e644d5a46e2fb9fb45bde58b36a0wfj
Production:  run_live_fce859d98c4f0e2b1e644d5a46e2fb9fb45bde58b36a0wfj

Use staging (https://staging.rundeliverys.com/api/v2) with a run_test_… key while integrating, then production (https://api.rundeliverys.com/api/v2) with a run_live_… key. Store the key securely on your server — never in a mobile app or frontend.

3. Fund your wallet

Placing orders debits your Business wallet. Fund it from the dashboard before you call POST /business/order. See Wallet funding.

Run Business Wallet page showing balance and Fund Wallet — Business Dashboard → Wallet — fund balance before placing API orders

4. List rate-card options (optional)

If RUN admin has set custom rates for your business:

curl -X GET "$BASE/business/rate-cards" \
  -H "Authorization: Bearer $RUN_API_KEY"

This is read-only (you do not negotiate prices here). Use vehicle_type and options[].id when quoting. See Rate cards.

5. Get a quote

curl -X POST "$BASE/business/order/cost" \
  -H "Authorization: Bearer $RUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pickup_address": "15 Bode Thomas Street, Surulere, Lagos",
    "dropoff_address": "24 Allen Avenue, Ikeja, Lagos",
    "weight": 2,
    "vehicle_type": "bike"
  }'

A successful rate-card response looks like:

{
  "price": 5000,
  "distance_km": 12.4,
  "currency": "NGN",
  "pricing_model": "rate_card",
  "option_label": "0.5–2.5 kg",
  "delivery_mode": "MOTORBIKE"
}

$BASE is your base URL — for staging use https://staging.rundeliverys.com/api/v2.

6. Place an order

curl -X POST "$BASE/business/order" \
  -H "Authorization: Bearer $RUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "dropoff_address": "24 Allen Avenue, Ikeja, Lagos",
      "dropoff_state": "Lagos",
      "recipient_name": "Adewale Johnson",
      "recipient_phone": "+2348022222222",
      "item_name": "Shoes",
      "weight": 2,
      "quantity": 1,
      "vehicle_type": "bike"
    }
  ]'

7. Listen for webhooks (optional)

In Developers → Setup, register an HTTPS webhook URL and store the signing secret (shown once as something like whsec_••••••••••••••••). Run POSTs signed events when shipment status changes. Signatures are HMAC-SHA256 of orderId + status + timestamp (see Verify signatures). Track delivery attempts under Developers → Webhook deliveries. See Webhooks.

Run Business Webhook deliveries table with event types, HTTP status, and Retry — Business Dashboard → Developers → Webhook deliveries — inspect retries and dead-lettered events

Keys generated in the dashboard include both orders:read and orders:write by default.

Get started

Core concepts

Orders

Webhooks

Guides

1. Create a Business account

2. Generate an API key

3. Fund your wallet

4. List rate-card options (optional)

5. Get a quote

6. Place an order

7. Listen for webhooks (optional)

​1. Create a Business account

​2. Generate an API key

​3. Fund your wallet

​4. List rate-card options (optional)

​5. Get a quote

​6. Place an order

​7. Listen for webhooks (optional)

1. Create a Business account

2. Generate an API key

3. Fund your wallet

4. List rate-card options (optional)

5. Get a quote

6. Place an order

7. Listen for webhooks (optional)