Authentication & modes
Every request needs your key in the Authorization: Bearer … header. We issue keys after a short conversation – there is no self sign-up.
https://api.listnride.com/v1Real bikes and prices, simulated bookings: the link opens a test page, nobody pays and the lister is not notified.
Real bookings through the ListNRide checkout.
curl "https://api.listnride.com/v1/rides?lat=52.52&lng=13.40" \
-H "Authorization: Bearer lnr_test_…"How a booking works
You don’t need your own checkout: the customer books and pays with us and then returns to your website.
Find bikes
GET /v1/ridesby location, period and category.Create a checkout session
POST /v1/checkout/sessions– you get the price and a link.Redirect the customer
Booking and payment in the ListNRide checkout, then back to you.
Get the status
Via webhook or
GET /v1/bookings/{id}.
Test mode step by step
With a test key everything works like live – except that nobody pays and no lister is involved. Build and check the whole flow once before you go live.
Create a session
POST /v1/checkout/sessionswithlnr_test_…. Prices and availability are real.Open the link
The
urlopens a test page instead of the checkout. Choose “Complete test booking” there.Check the return
The customer lands on your
return_urlwithbooking=bkg_test_…andstatus=success.Check the webhook
If a webhook URL is set,
booking.confirmedwith"mode": "test"arrives within a minute.
Endpoints
Bikes near a location or from one lister. With a period, availability.units_available shows the free units.
| Parameter | Description |
|---|---|
| lat, lng | Centre of the search (or lister) |
| radius_km | 0.1–100, default 15 |
| bbox | Map viewport minLng,minLat,maxLng,maxLat instead of lat/lng |
| from, to | Period, ISO date or date-time |
| quantity | Number of identical bikes, default 1 |
| category | e.g. e-bike,cargo-bike |
| price_min price_max | Price per day in cents, incl. service fee and basic insurance |
| rider_height | Rider height in cm (150–210) – finds bikes of the right size and unisize bikes |
| frame_size brand | Exact frame size or brand, e.g. M or Gazelle |
| accessories | Included equipment, all must be present: helmet,lock,lights,basket,childseat,trailer,gps,repair_kit |
| instant_booking top_booked | true: only instant confirmation / only top booked bikes |
| min_rating lister_type type | Minimum rating, business or private, bike or accessory |
| sort | recommended · distance · price_asc · price_desc · rating · popular |
| limit, cursor | Pagination, at most 100 per page |
{
"object": "list",
"data": [{
"id": "ride_oEbNgLPApUJf52PkgHU49A",
"name": "KRZBERG – Single Speed",
"category": { "id": "single-speed" },
"price": { "currency": "EUR", "per_day": 2500 },
"lister": { "id": "lis_VTknvPc20LBQbXE9p7dt6A" },
"instant_booking": true,
"distance_km": 1.46
}],
"has_more": true, "next_cursor": "eyJvIjoyMH0"
}A single bike with description, all images, equipment, deposit and insurance.
Plus everything a product page needs: total prices for 1–28 days, rider height, booking rules, opening hours, cancellation policy and bookable extras with delivery zones.
{
"price": { "per_day": 2500, "tiers": [
{ "days": 1, "total": 2500 },
{ "days": 7, "total": 15599, "discount": 1400 } ] },
"size": { "rider_height": { "range": "175-185" } },
"booking_rules": { "min_days": 1, "time_slot_minutes": 30 },
"opening_hours": { "monday": ["09:00-18:00"], … },
"cancellation_policy": { "by_customer": [
{ "hours_before_pickup_min": 72, "refund_percent_of_rental": 100 }, … ] },
"extras": [{ "code": "insurance_plus" }, { "code": "delivery" }]
}Free units per day plus pickup and return windows in local time, up to 92 days per request. Closed days and opening hours are already taken into account – ideal for your own date picker. The binding check happens in POST /v1/quotes and in the checkout.
{
"object": "availability",
"units_total": 4,
"days": [{
"date": "2026-11-17",
"units_available": 3,
"closed": false,
"pickup_windows": ["09:00-18:00"],
"return_windows": ["09:00-18:00"]
}, …]
}Verified reviews of a bike, newest first, with the average and total count. Authors appear as first name plus initial. For all reviews of a lister: GET /v1/listers/{id}/reviews.
Public profile of a lister: name, location, rating, completed bookings, number of bikes, instant confirmation, booking rules, opening hours and delivery zones. Private listers appear with first name and without street.
The cancellation policy that applies to every booking: from 72 hours before pickup everything is refunded, below that a share of the rental by time window. If the lister cancels, the customer gets everything back.
All categories with German and English names. A parent category such as e-bike includes its subcategories in searches.
All places with bookable bikes, the ones with most bikes first. Use q to search in all languages (e.g. q=munich), country to filter by country and locale for the language of the names. Single place: GET /v1/places/{id}.
Instead of one specific bike your customer books a class – e.g. “E-bike, mid-range” in Berlin – and ListNRide finds a suitable lister. Query by place or lat/lng. Book it with a checkout session using class and size (rider height).
{
"id": "berlin.e-bike.mid",
"object": "class",
"category": { "id": "e-bike" },
"tier": { "id": "mid" },
"price": { "currency": "EUR", "per_day": 3900 },
"sizes": ["150-165", "165-175", "175-185", "185-205", "Unisize"],
"listers_nearby": 12
}Calculates the exact price like the ListNRide checkout: rental, discount, service fee, basic insurance, extras (insurance_plus) and delivery to an address – without reserving anything. A quote covers bikes of one lister or one class.
curl -X POST https://api.listnride.com/v1/quotes \
-H "Authorization: Bearer lnr_test_…" \
-H "Content-Type: application/json" \
-d '{
"from": "2026-11-17", "to": "2026-11-19",
"items": [{ "ride": "ride_jK6n…", "quantity": 2,
"extras": ["insurance_plus"] }],
"delivery_address": "Torstraße 1, 10119 Berlin"
}'
# → "amounts": { "rental": 6000, "service_fee": 1100,
# "insurance_plus": 900, "delivery": 1500, "total": 9600 }Creates a checkout session. The ListNRide checkout checks price and availability. The link is valid for 24 hours; quantity and times are preselected in the checkout.
| Field | Description |
|---|---|
| ride * | Bike ID ride_… |
| class, size | Instead of ride: a class from GET /v1/classes and the rider height (165-175 … or Unisize) |
| from, to * | Pick-up and return day, YYYY-MM-DD |
| pickup_time, return_time | HH:MM, default 10:00 / 17:00 |
| quantity | Quantity, 1–50, default 1 |
| return_url * | Where the customer returns after booking (https), with checkout_session, booking and status=success |
| cancel_url | Optional, used when the customer cancels (https) |
| locale | de · en · fr · es · it · nl |
| client_reference | Your own reference |
curl -X POST https://api.listnride.com/v1/checkout/sessions \
-H "Authorization: Bearer lnr_test_…" \
-H "Content-Type: application/json" \
-d '{
"ride": "ride_jK6nvpDczET3Adx8AKKn1w",
"from": "2026-11-17", "to": "2026-11-18",
"pickup_time": "09:00", "return_time": "17:00",
"return_url": "https://your-site.com/thanks",
"locale": "en"
}'
# → { "id": "cs_O8t1…", "amount_total": 7800,
# "url": "https://www.listnride.com/api/go/p/BHTm…" }Session status: open, booked (with booking ID) or expired.
| status | Description |
|---|---|
| awaiting_payment | Customer is in the checkout, not paid yet |
| requested | Paid or reserved, waiting for the lister to accept |
| accepted | Lister accepted, payment in progress |
| confirmed | Confirmed |
| completed | Rental completed |
| canceled_by_lister · canceled_by_customer · canceled | Cancelled |
| expired | Not paid or not accepted in time |
All bookings from your checkout sessions, newest first. Filter by status or your client_reference. A test key lists test bookings, a live key live bookings. Canceled bookings carry cancellation with the refund amount and its status.
Cancels a booking on behalf of your customer – under the same rules as on listnride.com: from 72 hours before pickup everything is refunded, below that a share of the rental. The lister is notified, you receive booking.canceled_by_customer, and the refund goes back to the customer’s payment method.
Check first with GET /v1/bookings/{id}/cancellation – it shows whether cancelling is possible and the exact refund, without changing anything. Cancelling needs the scope bookings:cancel, which we enable on request. Optional: reason (changed_mind, found_better, timing_issue, price_too_high, personal_reasons, other) and comment.
# 1. Preview: can it be canceled, and what does the customer get back?
curl https://api.listnride.com/v1/bookings/bkg_gr9z…/cancellation \
-H "Authorization: Bearer lnr_live_…"
# → "cancelable": true, "refund": { "amount": 7300 },
# "breakdown": { "rental_refunded_percent": 75 }
# 2. Cancel
curl -X POST https://api.listnride.com/v1/bookings/bkg_gr9z…/cancel \
-H "Authorization: Bearer lnr_live_…" \
-H "Content-Type: application/json" \
-d '{ "reason": "timing_issue" }'
# → "status": "canceled_by_customer"Add ?aff=YOURCODE to any ListNRide link – every page, every language. If the customer books within the agreed period, the booking counts for you; the last click wins. Bookings through your checkout sessions always count for you, even without a click.
Commission is agreed individually and is based on the fees ListNRide earns from the booking. It counts once the rental has ended; if the lister cancels, there is no commission. GET /v1/commissions shows clicks, bookings, tier and commission per month – without customer data. We settle monthly by credit note.
# Referral link – works on any page
https://www.listnride.de/berlin/e-bike?aff=NEEDABIKE
# Your commission for a month
curl "https://api.listnride.com/v1/commissions?month=2026-09" \
-H "Authorization: Bearer lnr_live_…"
# → "clicks": 4812, "bookings": 91, "tier": "Stufe 3 · 30 %",
# "commission_net": { "amount": 54120 }, "status": "approved"Webhooks
When a booking’s status changes, we send a POST to your webhook URL, e.g. booking.confirmed. Reply with 2xx – otherwise we retry after 1 min, 5 min, 30 min and up to 24 h. Use ping to test the connection; the event id stays the same across retries.
Verify every message using the LNR-Signature: t=…,v1=… header: HMAC-SHA256 over t + "." + body with your secret whsec_…. Use the raw, unmodified body and reject messages whose t is older than 5 minutes.
POST https://your-site.com/hooks/listnride
LNR-Event: booking.confirmed
LNR-Signature: t=1791210000,v1=5f2c…
{
"id": "evt_Qm3xT0bWl2kZ8yQe",
"object": "event",
"type": "booking.confirmed",
"created": "2026-11-02T09:14:03.000Z",
"data": { "object": {
"id": "bkg_gr9z-CSUh4I8UrC9WEwW2Q",
"object": "booking",
"mode": "live",
"status": "confirmed",
"reference": "LNR-w4kKb",
"checkout_session": "cs_O8t1fc2rdEG2GyYTqghvfA",
"ride": "ride_jK6nvpDczET3Adx8AKKn1w",
"from": "2026-11-17T08:00:00.000Z",
"to": "2026-11-18T16:00:00.000Z",
"quantity": 1,
"amount_total": 7800,
"currency": "EUR",
"client_reference": "NB-1042"
} }
}const crypto = require("crypto");
// rawBody: the raw body exactly as received
function verify(rawBody, header, secret) {
const p = Object.fromEntries(header.split(",").map(x => x.split("=")));
if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
const expected = crypto.createHmac("sha256", secret)
.update(`${p.t}.${rawBody}`).digest("hex");
return typeof p.v1 === "string" && p.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1));
}
function lnr_verify(string $rawBody, string $header, string $secret): bool {
$p = [];
foreach (explode(",", $header) as $part) {
[$k, $v] = array_pad(explode("=", $part, 2), 2, "");
$p[$k] = $v;
}
if (abs(time() - (int)($p["t"] ?? 0)) > 300) return false;
$expected = hash_hmac("sha256", $p["t"] . "." . $rawBody, $secret);
return hash_equals($expected, $p["v1"] ?? "");
}
// $raw = file_get_contents("php://input");
// lnr_verify($raw, $_SERVER["HTTP_LNR_SIGNATURE"] ?? "", "whsec_…");
import hashlib, hmac, time
# raw_body: the raw body exactly as received
def verify(raw_body: bytes, header: str, secret: str) -> bool:
p = dict(x.split("=", 1) for x in header.split(",") if "=" in x)
if abs(time.time() - int(p.get("t", 0))) > 300:
return False
expected = hmac.new(secret.encode(), p["t"].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, p.get("v1", ""))Errors & limits
Errors always have the same shape. With the request_id we can find your case quickly.
Limits per key: a per-minute limit and a daily quota (headers X-Quota-Limit, X-Quota-Remaining). A search can be paged through at most 500 results deep – narrow it by place, radius, category or period. Bulk harvesting and reselling the data are not permitted.
Safe retries: send an Idempotency-Key header with POST /v1/checkout/sessions and POST /v1/bookings/{id}/cancel. A retry with the same key and the same body returns the first response (header Idempotent-Replayed: true) instead of acting twice. Keys are kept for 24 hours.
| HTTP | code |
|---|---|
| 400 | parameter_missing, parameter_invalid, outside_opening_hours, duration_too_short, duration_too_long, multiple_listers, delivery_unavailable, pagination_limit |
| 401 | missing_api_key, invalid_api_key |
| 403 | missing_scope |
| 404 | resource_missing, route_not_found |
| 409 | ride_unavailable, already_canceled, processing, already_started |
| 429 | rate_limited, daily_quota_exceeded, too_many_failed_attempts – X-RateLimit-*, X-Quota-*, Retry-After |
{ "error": {
"type": "invalid_request_error",
"code": "ride_unavailable",
"message": "The ride is not available for this period and quantity.",
"param": "ride",
"request_id": "req_UqrIw8P5wzwT" } }SDKs & tools
Official clients as a single file without dependencies – copy them into your project. They handle authentication, paging, retries on 429/5xx, Idempotency-Keys and webhook verification.
const { ListNRide } = require("./listnride");
const lnr = new ListNRide({ apiKey: process.env.LNR_API_KEY });
for await (const ride of lnr.rides.all({ lat: 52.52, lng: 13.40, category: "e-bike" })) {
console.log(ride.name, ride.price.per_day);
}
const session = await lnr.checkoutSessions.create({ ride: "ride_…", from: "2026-11-17",
to: "2026-11-19", return_url: "https://your-site.com/thanks" }); // Idempotency-Key is added automaticallyVersioning
The version is part of the path. Within /v1 we only add fields – nothing is removed or renamed. Breaking changes will appear as /v2, and /v1 keeps running for at least 12 months. The machine-readable description (OpenAPI 3.1) is at /openapi.json and https://api.listnride.com/v1/openapi.json.
Changelog
Idempotency-Key for writing calls, Postman collection, official clients for Node.js, PHP and Python.
Affiliate: referral links with
?aff=CODEandGET /v1/commissions.GET /v1/bookings, cancellation preview andPOST /v1/bookings/{id}/cancel(scopebookings:cancel).Search filters (price, rider height, accessories, map viewport …), price tiers, opening hours, cancellation policy, availability calendar, reviews and lister profiles.
Places, vehicle classes,
POST /v1/quotes, class checkout and a daily quota per key.Launch of v1: bikes, categories, checkout sessions, bookings, webhooks and test mode.
Request access
Tell us about your website and what you have in mind. You get a test key first – going live follows after a short call.
partner@listnride.com