DEV Community: SendRelay

Build the e-hailing app. Let Relay connect the drivers.

SendRelay — Thu, 22 Oct 2026 16:17:07 +0000

You can build a good booking app and still have nobody to send when a customer requests a ride.

That is the awkward part of starting an e-hailing business as a solo developer. The map works. Payments work. You have spent weeks getting the pickup flow right. But before anyone can use it, you need drivers who will actually turn up.

You could recruit them yourself. Find car owners, speak to fleet operators, work out who covers which area and start taking bookings. You do not have to own the vehicles, but you do have to organise the supply behind your app. That can quickly become the bigger job.

Relay gives you a way to build around an existing driver network. It provides logistics as a service: your backend requests a task through the API, and Relay coordinates matching and task progress. You build the app your customers use. E-hailing is one use case for that infrastructure, rather than a passenger service operated by Relay itself.

What running your own fleet involves

Say you want to launch in one part of Lagos. Before you can promise customers a pickup, there is quite a bit to arrange:

Recruitment. Find drivers or fleet partners, agree on earnings and explain why they should join a new service with few customers.
Verification. Check identities, licences and vehicle documents; arrange appropriate background checks with consent. Keep track of documents that need renewing.
Vehicle checks. Assess condition, maintenance and suitability. You need to know which vehicles are ready for work, not just how many are registered.
Onboarding. Teach drivers how requests, pickups, cancellations and support work. Agree on the service customers should expect.
Daily coverage. Plan for busy hours, drivers going offline and vehicles breaking down. Someone has to deal with the gaps.
Local access. Build relationships around estates, campuses, terminals and pickup points. Work out the operating requirements for your service.
Support and payments. Handle missed pickups, disputes, incidents and settlements. Follow up on recurring complaints.

Then you want to expand. A launch in another state means finding reliable local partners and working through much of that list again. Meanwhile, customers are still asking for improvements to the app.

For a solo developer, this is a serious constraint on how much you can build and how far you can reach.

Connect the booking flow to Relay

With Relay, your backend sends the pickup, destination and task requirements through an API. Your app can use task events and location updates to show what is happening: waiting for a driver, assigned, on the way or completed.

That leaves more time for the details customers notice. Can they place the pickup pin outside the right gate? Can they book without calling for help? Is it clear what happens when no driver is available?

An example app screen with simulated driver locations.

You can test that experience before arranging a live launch. Relay's test mode gives you simulated drivers, so you can work through the booking and tracking flow without assembling a fleet just to try your idea.

You still run your customer-facing business. Support, pricing and the responsibilities of a passenger service remain yours to organise. Before launch, agree with Relay on driver supply, verification standards and the operating arrangements for your service. Relay currently describes its coverage as a Lagos and Abuja pilot; confirm your launch area and vehicle requirements with the team.

Cars, kekes or motorcycles

Your product does not have to look like every other booking app. You might want a car service for a particular community, a keke booking app for short local journeys, or a motorcycle service where passenger operations are permitted.

Relay lets your backend specify the vehicle category for a task:

Your app	API vehicle preference
Car bookings	`CAR`
Keke bookings	`TRICYCLE`
Motorcycle bookings	`MOTORCYCLE`

For an SUV service, discuss the required vehicles with Relay. There is no separate SUV category in the current API, so selecting CAR alone would not guarantee one. Each service also needs suitable supply in its launch area.

If you want to work with particular fleet partners, you can specify allowedOrganisations and set allowIndependentRiders: false. Your app can then match within that selected group. The matching documentation covers these controls.

This makes it easier to try different products through the same integration, without personally starting another recruitment operation for each one.

Try a booking from your backend

Here is a Node.js request for a simulated passenger task. Use a Relay test key; this example does not book a real driver.

import { RelayClient } from '@relay-sdk/sdk-node';

const apiKey = process.env.RELAY_API_KEY;
if (!apiKey?.startsWith('sk_test_')) {
  throw new Error('Use a Relay test key for this example');
}

const relay = new RelayClient({ apiKey });
const { task } = await relay.tasks.create({
  taskType: 'PASSENGER_RIDE',
  preferences: { vehicleType: ['CAR'] },
  stages: [
    {
      type: 'PICKUP',
      instructions: 'Simulation only',
      location: {
        latitude: 6.4541, longitude: 3.4246,
        address: 'Demo pickup, Ikoyi, Lagos',
      },
      passengers: [{ name: 'Demo passenger', luggageCount: 0 }],
    },
    {
      type: 'DROPOFF',
      instructions: 'Simulation only',
      location: {
        latitude: 6.4474, longitude: 3.4495,
        address: 'Demo destination, Ikoyi, Lagos',
      },
    },
  ],
  autoAssign: true,
  paymentMethod: 'WALLET',
  simulationOutcome: 'SUCCESS',
}, { idempotencyKey: 'ride-demo:booking-001:attempt-1' });

console.log(task.id, task.status);

Keep the API key on your server and save the returned task ID against the booking. Reuse the same request and idempotency key when retrying that booking attempt; use a new key for a new booking.

Next, connect verified webhooks to your backend and a task-scoped WebSocket subscription to your UI. Try cancellations and the no-driver outcome as well as a successful booking. If you show a price before dispatch, request a quote first and create the task before it expires.

You now have something you can build a product around. Relay also has browser and Flutter tooling for the customer-facing part of the app.

What could you build beyond the first city?

Access to a shared network changes the expansion question. As Relay adds drivers and supported areas, you can explore those markets through the integration you already have, instead of beginning every launch by finding and onboarding another fleet yourself.

There are opportunities beyond passenger bookings, too. Within a state, a retailer could arrange pickups from several shops and deliveries to customers through one app. Across states, a business could let sellers request transport to customers or collection points along supported routes. Both depend on suitable vehicles and confirmed route coverage, but the developer can build the ordering, booking and tracking experience around the same task API.

That is the appeal of adopting Relay early: you can start with a focused local product and expand what it does as the network grows. E-hailing is the example here. We will cover other apps you can build with Relay in upcoming posts.

Get a test key and explore Relay · Read the API docs

Map: OpenFreeMap / OpenMapTiles, © OpenStreetMap contributors (ODbL).

No rider accepted your delivery task. What should your app do?

SendRelay — Mon, 19 Oct 2026 15:46:33 +0000

An order is ready at a pharmacy in Wuse 2, Abuja. The customer opens your app to check on delivery. Your backend has created a Relay task, but no rider accepts the offer. If your screen still says “finding a rider,” the customer has no idea what is happening, and your operations team has no clear next step.

What you'll build

You'll handle the no-rider branch: store the task ID, observe its terminal state, and show a customer message that your app can actually support. Start by rehearsing it with a test key:

import { RelayClient } from '@relay-sdk/sdk-node';

const relay = new RelayClient({ apiKey: process.env.RELAY_API_KEY! }); // sk_test_... only
const { task } = await relay.tasks.create({
  taskType: 'PACKAGE_DELIVERY',
  autoAssign: true,
  simulationOutcome: 'NO_RIDERS',
  stages: [
    {
      type: 'PICKUP',
      location: { latitude: 9.0579, longitude: 7.4951, address: 'Demo pickup, Wuse 2, Abuja' },
      instructions: 'Simulation only',
      items: [{ name: 'Demo parcel', estimatedValue: 100000,
        estimatedWeight: 'LIGHT', estimatedSize: 'BOX' }],
    },
    {
      type: 'DROPOFF',
      location: { latitude: 9.0765, longitude: 7.3986, address: 'Demo dropoff, Abuja' },
      instructions: 'Simulation only',
      items: [],
    },
  ],
});

// Persist task.id with your order. Later, reconcile from Relay:
const latest = await relay.tasks.get(task.id);
console.log(latest.task.status, latest.task.failureReason);

The addresses and coordinates are demonstration inputs. estimatedValue is the parcel's value in kobo, not the delivery fee. NO_RIDERS works with sk_test_... keys; test mode simulates the lifecycle and does not dispatch a real rider or move real money. Follow the Node SDK guide and simulation outcomes for setup.

What happens when nobody accepts?

In the live auto-assignment path, Relay looks for eligible nearby riders in configured offer tiers. A tier can find no eligible riders, receive no deliverable offers, or reach its decision deadline without an accepted assignment. The workflow checks for an assignment before ending the search. If none remains, it marks the task FAILED with reason NO_RIDERS_AVAILABLE and emits a task-failed event.

That distinction matters in your app. OFFERED is still in progress; FAILED is terminal. Don't promise a rider while an offer is pending, and don't keep showing a spinner after the failure. A webhook can synchronize your backend; GET /tasks/{taskId} lets you reconcile state when a webhook is delayed or your service restarts. Relay also supports WebSocket updates for a connected UI. See the task lifecycle and webhook guide.

Give the customer and your team a useful next step

Back in Wuse 2, your customer should see a plain status such as: “We couldn't find a rider for this delivery. We're checking another option.” That wording is your product choice, not an automatic Relay message. Your operations view should show the failed task and its reason so a person can decide whether to adjust the order, contact the customer, or create a new task. Do not silently treat the failed task as delivered.

If you retry from your backend, use the documented task-creation idempotency behavior to avoid duplicate task creation from network retries. A new dispatch attempt is a product decision: review the current task state and your payment flow first. Relay's live failure path refunds a wallet-funded task and attempts to void a card preauthorization before publishing failure; your UI should still use the task and payment records as its source of truth rather than promising an instant bank refund.

Rehearse the failure branch

Get a test API key and create a task with simulationOutcome: 'NO_RIDERS'.
Save the returned task.id against your order.
Listen for the task-failed webhook and verify its signature; keep the handler idempotent.
Retrieve the task by ID to reconcile the final status. Check FAILED and the failure reason before updating your order and customer UI.
Repeat with TIER_3_TIMEOUT to exercise the full timeout path. The simulation matrix lists the expected outcomes.

When your test task fails, check the customer screen and operations view together. Both should reflect the same failed task before anyone decides what to do with the order. Create a Relay account and get API keys, then use the task creation guide to run the scenario.

Create a delivery once, even when your Node worker retries

SendRelay — Wed, 30 Sep 2026 18:42:07 +0000

You run an online pharmacy in Wuse 2, Abuja. A customer confirms an order, and your checkout worker starts a delivery. The request times out just as the worker loses its connection. Did the task get created? Retrying with a fresh request can leave your team looking at two dispatches for one order.

Relay lets your backend attach an idempotency key to task creation. Keep that key tied to the order's delivery intent, and a retry can recover the existing task. The customer sees one delivery; your ops team has one task to track. Here is how to wire that into a Node worker.

What you'll build

A Node function that creates a package delivery for an Abuja order and safely retries an uncertain result with the same key. You'll use the Node SDK and the task creation guide.

import { RelayClient } from '@relay-sdk/sdk-node';

const apiKey = process.env.RELAY_API_KEY;
if (!apiKey) throw new Error('RELAY_API_KEY is required');
const relay = new RelayClient({ apiKey });

type Order = { id: string };

export async function createOrderDelivery(order: Order) {
  // Persist the order ID before dispatching this job. Reuse it on every retry.
  const idempotencyKey = `order:${order.id}:delivery:v1`;
  const result = await relay.tasks.create({
    taskType: 'PACKAGE_DELIVERY',
    externalId: order.id,
    stages: [
      {
        type: 'PICKUP',
        location: { latitude: 9.0765, longitude: 7.3986, address: 'Wuse 2, Abuja' },
        instructions: 'Ask for the pharmacy desk',
        items: [{
          name: 'Packed order',
          estimatedValue: 500000,
          estimatedWeight: 'LIGHT',
          estimatedSize: 'BOX',
        }],
      },
      {
        type: 'DROPOFF',
        location: { latitude: 9.0579, longitude: 7.4951, address: 'Garki, Abuja' },
        instructions: 'Call the recipient on arrival',
      },
    ],
  }, { idempotencyKey });

  // Store this ID against your order so later events can update the right row.
  return { taskId: result.task.id, duplicate: result.idempotency.duplicate === true };
}

Install the package with npm install @relay-sdk/sdk-node. Keep RELAY_API_KEY on your server. The SDK sends the explicit key as an Idempotency-Key header. Its automatically generated POST keys help within a request, but a stable order-based key is what makes a later job retry refer to the same delivery.

Retry the same intent, not a new delivery

If the worker times out or its queue redelivers the job, call createOrderDelivery(order) again with the same persisted order ID and the same delivery details. Do not add a timestamp or random value to the key. Relay looks up a task by account and key; a replay returns the existing task with idempotency.duplicate: true. The key is for one delivery intent. If the customer requests a genuinely new delivery, use a new versioned key.

The API describes a 24-hour validity window for this retry flow. Keep your own order-to-task record as the longer-lived source of truth. A timeout does not prove creation failed: retry with the same key, then record the returned task ID. If the API keeps failing, let your queue retry later with that same key rather than issuing an unkeyed create.

Try it without dispatching a rider

Start with a sk_test_... key from your Relay dashboard. Test-key task creation runs a simulation: it does not assign a real rider or move real money. The server selects the internal TEST payment path, so do not send paymentMethod: 'TEST'. You can pass simulationOutcome: 'SUCCESS' in the create body while checking the flow. Create the same order twice and check that the second result reports duplicate: true and the same task ID.

For the response shape, lifecycle, and test outcomes, see Create Task and Simulation Outcomes. For your checkout, get your API keys and keep the key generation on your backend.

The first two minutes of a delivery (and everything after)

SendRelay — Wed, 30 Sep 2026 18:37:57 +0000

In our first post a cake got across Lagos without anyone making a phone call. In the second, we looked at the businesses that open up when delivery stops being the hard part.

People keep asking the same follow-up question: what actually happens in between? You press a button, a rider turns up. What goes on in the middle?

So let's slow one delivery right down and watch it.

10:02 a.m. The order is ready

A pharmacy in Wuse 2, Abuja. A customer in Maitama has ordered a repeat prescription, including insulin, which has to stay cold. The pharmacist has done her checks, packed the order, and taps "ready".

The price was settled earlier, when the customer checked out. Relay gave the pharmacy's app a quote, and that price held while the order was being prepared. Nobody haggles at the door, and nobody gets a surprise at the end.

The moment the order is marked ready, it becomes a delivery on Relay, waiting for a rider. The clock starts.

10:02 and one second. Who could take this?

Relay looks around the pharmacy for riders who could do this particular job well. Not just anyone nearby: riders who are online right now, who are rated highly enough, whose vehicle suits the trip, and, because of the insulin, who can keep things cold.

That last part matters. The pharmacy asked for refrigeration when it created the delivery, so a rider without it is never offered the job. It isn't a note someone might forget to read. The rider simply doesn't qualify.

The first two minutes: three waves

Here's the part most people never see. Relay doesn't shout the job to every rider in the city at once. It asks in waves.

The first wave goes to one rider, the best-placed one, who has thirty seconds to accept. One rider, one clear offer, no scramble.

If they don't take it, the second wave goes to up to three riders, for another thirty seconds. Whoever accepts first gets the job.

If it's still open, the third wave widens to up to twenty riders, for a final minute.

Those are the default timings. An urgent delivery moves faster, with shorter windows at every wave. Either way, within about two minutes you know where you stand.

And if nobody accepts? That can happen, especially late at night or in a heavy rainstorm. The delivery is marked as failed, the pharmacy is told straight away, and if the customer paid by card, the amount that was held on it is let go. Nobody's card is charged for a delivery that didn't happen, and the pharmacy isn't left waiting on a promise.

10:03 a.m. Someone says yes

A rider called Musa accepts from a few streets away. The delivery is now assigned to him.

On the customer's phone, the order page changes. It no longer says "preparing". It says a rider is on the way to the pharmacy, and shows him moving on the map.

This is the moment that used to be a string of phone calls. Now it happens without anyone picking up a phone.

10:09 a.m. The pickup

Musa arrives and collects the package. By now the delivery is "in progress", and the pickup is recorded as done, with the time.

If a delivery has several stops, each one is recorded the same way as it's completed. That's what lets the aso-ebi coordinator from our last post see exactly which of her forty guests have their outfits and which are still waiting.

10:10 to 10:24 a.m. The part everyone can see

Musa rides towards Maitama. His position updates live, so the customer can watch him come, and the pharmacy can see him from the counter without asking anyone.

If the customer steps out to buy bread, they can check their phone and know whether to hurry back. If traffic on the way is slow, everyone can see that too. Nobody has to guess, and nobody has to call.

10:25 a.m. Delivered

The insulin arrives cold. The delivery is marked complete.

A few quiet things happen at this moment, and they're the parts businesses end up valuing most.

A card payment is collected now, not before. If the customer paid by card, the amount was only held when the delivery was created. It's charged once the job is actually done.

Musa's earnings are recorded straight away, then held for a short while before they're released. That short wait leaves room to raise a problem if something went wrong, before the money has gone anywhere.

The pharmacy can rate the rider. Ratings are part of how riders are matched, so the next business that asks for well-rated riders benefits from this one's feedback.

And everything is written down. When the order was ready, when it was offered, who accepted, when the pickup happened, when it arrived, what it cost, and when everyone was paid. If a customer calls next week to ask about their order, the answer is a few seconds away.

What didn't happen

It's worth noticing what nobody had to do.

Nobody rang round for a rider. Nobody negotiated a price at the door. Nobody answered "where is it?" three times. Nobody paid cash and tried to remember it at the end of the month. And the pharmacist never stopped being a pharmacist to become a dispatcher for half an hour.

That's the whole idea. The delivery still happens in the real world, on real roads, with a real person on a real bike. Relay just takes the uncertainty out of the middle.

For the developers reading

Everything above maps to a small, predictable set of states and events, so your app can follow along exactly.

A delivery moves through pending → offered → assigned → in progress → completed. It can also end as failed (no rider accepted) or cancelled.
Each change arrives as a webhook your server can listen for: task.status.created, task.status.offered, task.status.assigned, task.status.in_progress, task.status.completed, and task.status.failed or task.status.cancelled.
Every finished stop sends task.stage.completed, which is handy for multi-stop runs.
The money has its own events: payment.pending, payment.released, payment.disputed, and payment.dispute_resolved.
Live location for maps comes over a WebSocket, so your customer's screen updates without polling.

The part we like most is that you can rehearse all of it before going live. With a test key, you can tell Relay how a delivery should turn out, whether that's a smooth success, a first wave that times out, no riders at all, or a cancellation after the rider accepts, and check that your app handles each one gracefully. The simulation guide lists every outcome, and our Node walkthrough gets you to your first test delivery.

Two minutes, and then some

Most of what makes a delivery feel good to a customer happens in the first two minutes and the last one: someone reliable says yes quickly, and the thing arrives the way it left. Everything in between should be visible, fair, and written down.

That's the job we built Relay to do, so the pharmacist can stay a pharmacist.

If you'd like Relay behind your deliveries in Lagos or Abuja, start at sendrelay.com.ng or write to hello@sendrelay.com.ng.

Illustrations by Relay. The pharmacy, the customer and Musa are an illustrative example, not a real delivery.

What would you build if delivery were the easy part?

SendRelay — Mon, 28 Sep 2026 15:34:28 +0000

In our first post, we followed one cake from Yaba to Lekki. This time, let's zoom out.

Look closely at almost any business in Lagos or Abuja and you'll find a small delivery company hiding inside it. The pharmacy has a boy on a bike. The tailor has a cousin who "knows a rider". The caterer borrows her brother's car on Saturdays. None of them set out to run logistics, but every one of them does, a little badly, every day.

Relay exists so they don't have to. And once moving things across a city stops being the hard part, a lot of ideas that used to be too much trouble start to look like good businesses.

Here are some of them. A few are obvious. Most, we hope, are not.

Multi-stop tasks follow the stages in the order you provide. A return journey uses two tasks.

First, the ones you'd expect

Restaurants and cloud kitchens. The order is packed, a nearby rider is offered the job, and your customer watches the food come to them instead of calling to ask.

Pharmacies. You can request riders whose vehicle profile records refrigeration. Your business still needs to verify the equipment and handling required for the medicine.

Online shops. Show a quote at checkout, then create the same task with its quote ID before it expires. Relay uses that locked amount for the task.

Groceries and errands. Someone else does the market run. You follow it from your phone.

These are the reasons most people come to Relay. The interesting part is what else becomes possible.

Across town, right now

Some deliveries are small and urgent. They don't need a van; they need someone reliable, quickly.

The contract that must be signed today. A law firm in Ikoyi needs a signed agreement at a bank in Victoria Island before three o'clock. You can set an urgent priority and a minimum rider rating, or manually offer a pending task to selected available riders. Your app can show the envelope's progress with tracking events; the deadline is the firm's aim, not a delivery guarantee.

The part that gets the car moving again. A driver breaks down on the Lekki-Epe Expressway. The mechanic knows exactly which part he needs, and it's sitting in a shop at Ladipo. An app that connects roadside mechanics to parts dealers, and sends the part out the moment it's paid for, is a real business. It only ever needed a delivery network that nobody could afford to build alone.

The thing you forgot at home. Your laptop charger. Your ID card. The keys your sister needs. A simple "send anything across town" app, built for the everyday version of this problem, can use Relay for task creation and tracking while you build the rest of the app.

One pickup, many doors

A single Relay delivery can have several stops. The task follows the stages in the order you provide.

Aso-ebi season. One tailor, forty guests, forty outfits, all due before the wedding on Saturday. Instead of forty phone calls and a very long week, it's one pickup and a list of drop-offs, and your app can use task location and stage events to show guests progress. Anyone who has ever coordinated aso-ebi for a family wedding is already smiling.

Subscriptions that go out on a round. Weekly zobo and smoothies. Meal prep for busy professionals. Fresh bread every Friday morning. A small subscription business lives or dies on getting the same thing to the same thirty doors, reliably, every week.

Giving, delivered. Churches, mosques, and community groups that send food packs to families can plan a run of drop-offs and know that every stop was reached, with a record to show for it.

Many pickups, one door

Flip it around. Several stops to collect, one place to deliver.

A personal shopper for Balogun. The fabric from one stall, the lace from another, the shoes from a third. A shopper walks the market, and one rider collects from every stall and brings it all to one customer. For a customer elsewhere in Lagos, or just someone who can't face the market, that's a service worth paying for.

The morning ingredient run. A restaurant buying fresh produce from Mile 12 every morning. Peppers from one seller, onions from another, everything to the kitchen before lunch service.

Event day. The cake from Yaba, the flowers from Obalende, the small chops from Surulere, all arriving at the venue before the guests do.

There and back

Some ideas only work if the thing comes back. Those used to be twice as hard. With Relay they're two deliveries: one out, one home. Your app creates the return task when the item is ready; each task has its own quote, tracking and payment.

Laundry and dry cleaning that collects on Monday and returns on Thursday, without the business ever buying a van.

Phone and laptop repairs. The cracked phone goes to the technician; the fixed phone comes back. The customer never has to sit in traffic to Computer Village.

Renting instead of buying. Cameras for a weekend shoot. A PlayStation for the holidays. A dress for one wedding. Baby gear that's only needed for a few months. Rental businesses are held back by one question: how does it get there, and how does it come back? Answer that, and a whole category of small businesses opens up.

Choose vehicle and equipment filters

When you create a task, you can filter by vehicle type and by box, air-conditioning or refrigeration flags recorded on rider vehicle profiles. These filters do not verify temperature, packaging quality or suitability for sensitive goods.

Refrigeration requirements. For goods that need refrigeration, request the refrigeration flag and verify the available equipment and handling with your delivery operation.

Fragile and beautiful things. For cakes, flowers or artwork, you can request a box or air-conditioning flag. Confirm packaging and handling separately.

Heavy things. For a proposed bulk-delivery integration, choose a bulk-delivery task and filter for a truck. Verify suitable vehicle capacity and handling with your operation; the API does not guarantee truck supply.

Passenger rides

Relay supports passenger-ride tasks.

The night shift. A hospital, restaurant or hotel can build a staff ride service. Your app can create passenger tasks and use tracking events to show progress. Driver suitability and vehicle availability still need to be checked.

Guests. A hotel can build a guest pickup flow using passenger tasks and tracking events. Suitable vehicles, driver checks and any airport permissions remain the operation's responsibility.

Bring your own riders

Maybe you already have riders.

For manual dispatch, create a live task with autoAssign set to false. Retrieve available riders and offer the pending task to selected rider IDs. A rider must be eligible and accept the offer. The repo also includes an MIT-licensed Flutter location engine for integrating tracking into a rider app.

Equipment flags describe vehicle profiles. Earnings stay pending through the dispute window.

The pattern behind all of these

Every idea above has the same bones. Something needs to get from one part of the city to another. Someone is waiting for it. Someone needs to trust that it went well.

Relay takes care of that part:

filters nearby rider candidates by your rating and vehicle preferences
locks a matching task quote when used before expiry
provides location and stage events for your app
debits a wallet or pre-authorizes a card, then records pending earnings after completion
records stage progress and settlement state

Earnings release follows the dispute window; bank withdrawals are separate.

That leaves you free to work on the part that's actually yours: the idea itself.

Your turn

If you want to find an idea of your own, try this:

Where do people around you wait for something to arrive?
What do you regularly drive across town to fetch, or ask someone else to fetch for you?
Which business near you still says "sorry, we don't deliver"?
What would people rent, share, or subscribe to if getting it to them were easy?

Somewhere in those answers is a business that would have been too much trouble last year.

A note on honesty: Relay is piloting in Lagos and Abuja. It supports delivery and passenger-ride tasks. Your business still does its own part, whether that's checking a prescription or deciding what your customers are allowed to send.

If you build software, our step-by-step guide walks you through your first delivery in a few lines of code. If you run a business, write to hello@sendrelay.com.ng and tell us what you're trying to move. And if one of these ideas sparked a better one, tell us in the comments. We'd love to hear it.

Start at sendrelay.com.ng.
Next: The first two minutes of a delivery

Illustrations by Relay. Photos from Unsplash: Lagos market by Fahd Aminu, keke view by Joshua Oluwagbemiga.

Create your first delivery task with Relay (Node, test mode)

SendRelay — Mon, 28 Sep 2026 14:01:32 +0000

New to Relay? Start with the story behind it.

Imagine you run a pharmacy app in Lagos. An order is packed, but your checkout has no delivery ID to show the customer. Your team could call riders one by one and answer “where is my order?” from a chat thread. Instead, your backend can hand the delivery to Relay when the order is ready, save the task ID, and use that ID to follow its progress. In test mode, you can build that handoff without dispatching a real rider.

In this tutorial, you'll create a simulated package delivery with Relay's Node SDK. You'll install the SDK, use a test API key, send pickup and dropoff stages, and retrieve the task you created. The same pattern gives your order system a stable reference for later webhook handling.

What you'll build

This is the core call. It creates a test task with a deliberate idempotency key, so a retry for the same order does not create another intended delivery:

import { RelayClient } from '@relay-sdk/sdk-node';

const relay = new RelayClient({ apiKey: process.env.RELAY_API_KEY });

const created = await relay.tasks.create(
  {
    taskType: 'PACKAGE_DELIVERY',
    simulationOutcome: 'SUCCESS',
    autoAssign: true,
    stages: [
      {
        type: 'PICKUP',
        location: {
          latitude: 6.5244,
          longitude: 3.3792,
          address: 'Demo pickup, Lagos',
        },
        instructions: 'Simulation only',
        items: [
          {
            name: 'Demo parcel',
            estimatedValue: 100000,
            estimatedWeight: 'STANDARD',
            estimatedSize: 'BOX',
          },
        ],
      },
      {
        type: 'DROPOFF',
        location: {
          latitude: 6.4654,
          longitude: 3.4064,
          address: 'Demo dropoff, Lagos',
        },
        instructions: 'Simulation only',
      },
    ],
  },
  { idempotencyKey: 'order-demo-001-delivery' },
);

console.log(created.task.taskId, created.task.status);

The coordinates and addresses above are demonstration inputs. estimatedValue is the parcel's declared value in kobo; it is not a delivery quote. Relay's create-task guide covers the request fields in detail.

Get a test key

Create a Relay account and get an API key. Use a key that starts with sk_test_; the current SDK and API-key guide use that prefix for test mode. Keep the key on your server and out of source control. Never put it in browser code.

For a local Node project, install the SDK and put your key in your shell environment:

npm install @relay-sdk/sdk-node
export RELAY_API_KEY='sk_test_YOUR_TEST_KEY'

The placeholder is not a real credential. If you use another shell or hosting platform, set the environment variable through its secret settings. The SDK sends the key in the X-Relay-Key header; you do not need to build that header yourself.

Create the task

Save the first code block as create.mjs, then run:

node create.mjs

Use Node 18 or newer, as required by the Node SDK. A successful call prints the task ID and its initial status. Save created.task.taskId against your own order ID. Task creation means the delivery request was accepted; it does not mean delivery is complete.

Save the Relay task ID against your order so your backend can retrieve the delivery record.

The request has two stages. PICKUP tells Relay where the parcel begins; DROPOFF tells it where the parcel should end. simulationOutcome: 'SUCCESS' selects the success path for a test task. Test mode simulates the lifecycle without a real rider or real payment. You can use simulation outcomes to exercise other branches after the basic path works.

The second argument to relay.tasks.create() sets idempotencyKey. Derive this from a stable order ID in your app. If a network timeout makes you uncertain whether the create succeeded, retry the same intended delivery with the same key. For a different order, use a different key. The SDK can generate a key automatically, but an explicit order-based key gives your application control over retries.

Do not add paymentMethod: 'TEST' to this request. The test key selects the test flow. When you build your real order workflow, review the task creation guide and your payment setup before switching to a live key.

Read the task back

The task ID is the link between your order and Relay's delivery state. Add this after the create call to fetch the task:

const latest = await relay.tasks.get(created.task.taskId);
console.log('task' in latest ? latest.task.status : latest.status);

A test simulation can progress after the create response, so the status you read immediately may still be an early lifecycle state. Store the ID, then use task retrieval when you need the current snapshot. The Node SDK guide describes the task methods and response shape.

For an application that must update a customer or operations screen when the status changes, subscribe to Relay's webhook events. Verify each webhook's signature against the raw request body before using its data, and make event handling safe to repeat. Your order database should record the Relay task ID and the event IDs it has already processed. This is how the same Lagos order can move from “ready” to a delivery state your team can inspect without manual rider calls.

Build the next slice

Once the success simulation works, create a new test order using simulationOutcome: 'NO_RIDERS'. Decide what your checkout and support team should see when there is no available rider. Then connect the webhook to your order state and test duplicate delivery of an event before you use a live key.

You now have a small, repeatable delivery integration: an order triggers one Relay task, your app saves its ID, and you can inspect its status. Get your test API key and follow the first-request guide to try it in your backend.

Illustrations by Relay. Lagos photo by @ib_daye on Unsplash.

"Where is my cake?" A Saturday in Lagos, told twice

SendRelay — Mon, 28 Sep 2026 14:01:26 +0000

Say you bake cakes in Yaba.

It stopped being a hobby a while ago. The oven is on by six, your phone buzzes with orders all day, and on Saturdays there is barely room on the table for the boxes. People find you on Instagram, fall for a photo, and send a message: Can you do a two-tier for my mum's birthday? Lekki. Saturday, 3pm.

You say yes. Of course you say yes.

The cake is the easy part

By noon on Saturday the cake is done, and it is lovely. Now the real work starts.

You call the rider you used last week. He doesn't pick up. You call another one, who says he's close, then names a price well above what you told the customer delivery would cost. You agree anyway, because it's already 12:40. He says he's coming. Twenty minutes later, he is still coming.

When he finally arrives, you hand over the box, say a small prayer, and watch him ride off into Lagos.

Then the calls begin.

At 1:30 the customer asks if the cake has left. At 2:15 she asks where it is. You call the rider. "I dey Third Mainland, I dey come." At 2:50 she calls again. The guests are arriving, and you have no honest answer for her, because you don't know where your cake is. All you have is his word.

The cake arrives at 3:25. It's fine, thank God. Her afternoon wasn't, and neither was yours. You spent an hour and a half as a switchboard. You paid the rider in cash and have nothing written down to show for it. Tomorrow, you'll do it all again.

If any of that felt familiar, this is for you.

Now play it again

Same Saturday. Same cake. This time your orders come in through a website, and behind that website sits Relay.

At noon you mark the order as ready. Your backend requests a fresh quote with the pickup, destination, vehicle and minimum-rating preferences for this delivery. It then creates the task with the same inputs and that quote ID before the quote expires. Relay uses the locked quote amount for the task.

Relay filters nearby riders and offers an eligible rider the job. You haven't made a single call. Packaging and handling still need your attention.

The cake is ready. Your app hands the delivery request to Relay and keeps a record of its progress.

Your website uses Relay's location and stage events to show her the delivery's progress. When her friends ask whether the cake is coming, she can check the page instead of calling you for an update.

The task records the payment and delivery stages. Rider earnings stay pending through the dispute window; bank withdrawals are separate. At the end of the month you have a record to check against your orders.

The cake goes to the same address either way. What changes is the afternoon you both get to have.

So what is Relay?

Relay is the delivery API behind apps and websites that need to move orders across a city. Your backend creates the task, your app uses tracking events to show progress, and Relay records the delivery and settlement stages.

We're starting in Lagos and Abuja.

When to reach for Relay

You'll know it's time when:

someone on your team spends part of every day calling riders
customers ask "where is my order?" more often than they say thank you
you've paid for a delivery and been left with nothing but a phone number
you're building an app or website for food, medicine, groceries, errands, or anything else that has to reach a doorstep

If you run a business, mention Relay to whoever builds your website or app, or write to us at hello@sendrelay.com.ng and we'll talk it through with you. If you're the one who builds things, the next post on this page shows you how to send your first delivery with a few lines of code.

Either way, start at sendrelay.com.ng.

The cake deserves to arrive calmly. So do you.

Next: What would you build if delivery were the easy part?

Illustrations by Relay. Photos from Unsplash: Lagos by ib daye, Idumota by Opeyemi Adisa, Abuja by Muhammad-Taha Ibrahim.