ListNRideDevelopers
Getting started

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.

Base URL
https://api.listnride.com/v1
lnr_test_…

Real bikes and prices, simulated bookings: the link opens a test page, nobody pays and the lister is not notified.

lnr_live_…

Real bookings through the ListNRide checkout.

Keys belong on your server. Never ship them in a browser or app – anyone who has your key can book in your name.
curl
curl "https://api.listnride.com/v1/rides?lat=52.52&lng=13.40" \
  -H "Authorization: Bearer lnr_test_…"
Getting started

How a booking works

You don’t need your own checkout: the customer books and pays with us and then returns to your website.

  1. Find bikes

    GET /v1/rides by location, period and category.

  2. Create a checkout session

    POST /v1/checkout/sessions – you get the price and a link.

  3. Redirect the customer

    Booking and payment in the ListNRide checkout, then back to you.

  4. Get the status

    Via webhook or GET /v1/bookings/{id}.

Getting started

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.

  1. Create a session

    POST /v1/checkout/sessions with lnr_test_…. Prices and availability are real.

  2. Open the link

    The url opens a test page instead of the checkout. Choose “Complete test booking” there.

  3. Check the return

    The customer lands on your return_url with booking=bkg_test_… and status=success.

  4. Check the webhook

    If a webhook URL is set, booking.confirmed with "mode": "test" arrives within a minute.

Reference

Endpoints

GET/v1/ridesrides:read

Bikes near a location or from one lister. With a period, availability.units_available shows the free units.

ParameterDescription
lat, lngCentre of the search (or lister)
radius_km0.1–100, default 15
bboxMap viewport minLng,minLat,maxLng,maxLat instead of lat/lng
from, toPeriod, ISO date or date-time
quantityNumber of identical bikes, default 1
categorye.g. e-bike,cargo-bike
price_min
price_max
Price per day in cents, incl. service fee and basic insurance
rider_heightRider 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
accessoriesIncluded 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
sortrecommended · distance · price_asc · price_desc · rating · popular
limit, cursorPagination, at most 100 per page
Response (shortened)
{
  "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"
}
GET/v1/rides/{id}rides:read

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.

Response (shortened)
{
  "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" }]
}
GET/v1/rides/{id}/availabilityrides:read

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.

Response (shortened)
{
  "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"]
  }, …]
}
GET/v1/rides/{id}/reviewsrides:read

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.

GET/v1/listers/{id}rides:read

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.

GET/v1/cancellation-policyrides:read

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.

GET/v1/categoriesrides:read

All categories with German and English names. A parent category such as e-bike includes its subcategories in searches.

GET/v1/placesrides:read

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}.

GET/v1/classesrides:read

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).

Response (shortened)
{
  "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
}
POST/v1/quotesrides:read

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
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 }
POST/v1/checkout/sessionsbookings:write

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.

FieldDescription
ride *Bike ID ride_…
class, sizeInstead 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_timeHH:MM, default 10:00 / 17:00
quantityQuantity, 1–50, default 1
return_url *Where the customer returns after booking (https), with checkout_session, booking and status=success
cancel_urlOptional, used when the customer cancels (https)
localede · en · fr · es · it · nl
client_referenceYour own reference
curl
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…" }
GET/v1/checkout/sessions/{id}bookings:read

Session status: open, booked (with booking ID) or expired.

GET/v1/bookings/{id}bookings:read
statusDescription
awaiting_paymentCustomer is in the checkout, not paid yet
requestedPaid or reserved, waiting for the lister to accept
acceptedLister accepted, payment in progress
confirmedConfirmed
completedRental completed
canceled_by_lister · canceled_by_customer · canceledCancelled
expiredNot paid or not accepted in time
GET/v1/bookingsbookings:read

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.

POST/v1/bookings/{id}/cancelbookings:cancel

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.

curl
# 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"
GET/v1/commissionsbookings:read

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.

Link & report
# 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"
More

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.

Example: booking.confirmed
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"
  } }
}
Verify the signature
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));
}
More

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.

HTTPcode
400parameter_missing, parameter_invalid, outside_opening_hours, duration_too_short, duration_too_long, multiple_listers, delivery_unavailable, pagination_limit
401missing_api_key, invalid_api_key
403missing_scope
404resource_missing, route_not_found
409ride_unavailable, already_canceled, processing, already_started
429rate_limited, daily_quota_exceeded, too_many_failed_attempts – X-RateLimit-*, X-Quota-*, Retry-After
Error response
{ "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" } }
More

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.

Node.js
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 automatically
More

Versioning

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.

More

Changelog

  1. Idempotency-Key for writing calls, Postman collection, official clients for Node.js, PHP and Python.

  2. Affiliate: referral links with ?aff=CODE and GET /v1/commissions.

  3. GET /v1/bookings, cancellation preview and POST /v1/bookings/{id}/cancel (scope bookings:cancel).

  4. Search filters (price, rider height, accessories, map viewport …), price tiers, opening hours, cancellation policy, availability calendar, reviews and lister profiles.

  5. Places, vehicle classes, POST /v1/quotes, class checkout and a daily quota per key.

  6. 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

Request access

Tell us briefly who you are and what you’re planning. You get a test key first – going live follows after a short call.

Prefer email? partner@listnride.com