Sell rentals as a marketplace

How it works

• Independent owners lease their cars to the platform for the dates they choose. You do not need a single car of your own.
• Your customers (people who book) never need an account with us, only with you.
• For every completed rental you earn a commission (see rates in GET /me; typically 15% of the rental price). The owner’s share is fixed and never depends on who sold the booking, and you never see it.
• Our agent hands the car over at the airport and checks the customer’s licence. You own the customer relationship and the screens.

1. Browse the cars

Show your customer cars that are free for their dates. Send the pick-up and return as local times with the offset. Each result carries a quote, so you can show a price straight from the list. Filter by class, transmission, fuel, min_seats or a price range, and sort and page the results.

curl "https://engine-production-0004.up.railway.app/api/v1/rentals/vehicles?location=ABV&from=2026-11-20T10%3A00%3A00%2B01%3A00&to=2026-11-23T10%3A00%3A00%2B01%3A00&extras=gps%2Cchild_seat" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"

For a “choose a type” screen first, GET /rentals/classes gives each kind of car with a count and the cheapest price. For extras and insurance, GET /rentals/options lists everything a customer can add; pass the codes in extras.

2. Show availability

If you draw a calendar, ask for it instead of guessing: GET /rentals/vehicles/{id}/availability returns the periods the car is on offer, the periods already taken (never any customer details) and the free periods that remain once the turnaround time between rentals is kept.

curl "https://engine-production-0004.up.railway.app/api/v1/rentals/vehicles/12/availability" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"

3. Quote

Before you take a customer’s details, show them the exact price. The quote lists every line (the car, each extra, a one-way fee when they return at the other airport), the refundable deposit, and the total charged up front. The total is what they will pay: show it as it is.

curl -X POST "https://engine-production-0004.up.railway.app/api/v1/rentals/quotes" \
  -H "Authorization: Bearer wc_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "vehicleId": 12,
  "from": "2026-11-20T10:00:00+01:00",
  "to": "2026-11-23T10:00:00+01:00",
  "extras": [
    "gps"
  ],
  "dropoffLocation": "ABV"
}'

4. Book and pay

Create the booking with the customer’s details. We hold the car for about 20 minutes and return a checkoutUrl. Redirect the customer there (or open it in a new tab); after paying they are sent to your returnUrl with ?booking=WC-… added. The booking confirms by itself. You do not call a “confirm” endpoint.

curl -X POST "https://engine-production-0004.up.railway.app/api/v1/rentals/bookings" \
  -H "Authorization: Bearer wc_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6b2f7c3e-6f0a-4a3e-9d1c-1c2b6f1a9e55" \
  -d '{
  "vehicleId": 12,
  "from": "2026-11-20T10:00:00+01:00",
  "to": "2026-11-23T10:00:00+01:00",
  "pickupLocation": "ABV",
  "dropoffLocation": "ABV",
  "extras": [
    "gps"
  ],
  "customer": {
    "name": "Chidi Obi",
    "email": "chidi@example.com",
    "phone": "+2348031234567",
    "licenseNumber": "ABC12345",
    "licenseExpiry": "2029-05-01T00:00:00+01:00"
  },
  "flightNumber": "W3123",
  "metadata": {
    "order_id": "A-1001"
  },
  "returnUrl": "https://shop.example/booking"
}'

Pass your own order id

Put your order id in metadata: it comes back on the booking, on every event and in webhooks, so you can match them to your records without storing our references.

5. After the booking

• Listen for events. Webhooks tell you the moment a booking is confirmed, active, completed, cancelled or expired. Mark your order paid on booking.confirmed.
• Let customers check in. Once paid, POST /rentals/bookings/{ref}/checkin records their arrival flight, time and a note for our agent. You can also pass flightNumber when you create the booking.
• Keep contact details right. PATCH /rentals/bookings/{ref} changes the customer’s phone, email or flight, and your metadata. Dates, car and price cannot be changed: cancel and book again.
• Let a customer come back to pay. GET /rentals/bookings/{ref} carries the checkoutUrl while a booking is unpaid.

Cancellations

POST /rentals/bookings/{ref}/cancel releases an unpaid booking, or refunds a paid one by this policy (the deposit is always returned in full):

The answer includes refundPercent and the refund status, and a booking.cancelled event follows with price.refunded. What is not refunded is a cancellation fee that stays with the platform: you and the car’s owner earn nothing from a cancelled booking. Every booking carries a live cancellation object (what cancelling now would return, and when it drops), and a closing settlement once it is cancelled or the car is back. Show your customer the policy before they book.

A rental ends when the car is returned: our staff confirm it at the airport. If the customer brings it back early, the unused time is refunded in proportion (to the second) and your commission is for the time used only. The booking shows earlyReturn while the car is out and returnedAt afterwards.

Your earnings

Your commission on each booking is shown in the booking’s commission field. It is held until the customer has returned the car, then released, and our team pays it out to your bank account. An early return gives back the share for the unused time; a cancelled booking gives back all of it. Read it all from the API:

curl "https://engine-production-0004.up.railway.app/api/v1/commissions?page=1&limit=20" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"

GET /balance gives the totals (available, pending and paid out), and GET /payouts the transfers made.

Booking states