{"openapi":"3.1.0","info":{"title":"ListNRide Partner API","version":"2026-10-05","description":"Search ListNRide bikes and send customers to the ListNRide checkout to book. Guides, examples and webhook verification: https://developers.listnride.com","contact":{"name":"ListNRide Partner","email":"partner@listnride.com","url":"https://developers.listnride.com"}},"servers":[{"url":"https://api.listnride.com/v1"}],"security":[{"bearer":[]}],"tags":[{"name":"Rides","description":"Read bikes and categories (rides:read)."},{"name":"Checkout","description":"Checkout sessions and bookings (bookings:write, bookings:read)."}],"paths":{"/categories":{"get":{"tags":["Rides"],"operationId":"listCategories","summary":"List categories","description":"Scope rides:read. A parent category includes its subcategories in searches.","responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryList"}}}},"401":{"description":"Missing or invalid API key (missing_api_key, invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (missing_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests (rate_limited, too_many_failed_attempts). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error on the ListNRide side (internal_error). Please retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rides":{"get":{"tags":["Rides"],"operationId":"listRides","summary":"Search bikes","description":"Scope rides:read. Give either lat+lng or lister.","parameters":[{"name":"lat","in":"query","schema":{"type":"number","minimum":-90,"maximum":90},"example":52.52},{"name":"lng","in":"query","schema":{"type":"number","minimum":-180,"maximum":180},"example":13.4},{"name":"lister","in":"query","description":"Only bikes of this lister (lis_...).","schema":{"type":"string"}},{"name":"radius_km","in":"query","schema":{"type":"number","minimum":0.1,"maximum":100,"default":15}},{"name":"from","in":"query","description":"Start, ISO 8601 date or date-time. Only together with to.","schema":{"type":"string"},"example":"2026-11-17"},{"name":"to","in":"query","description":"End, ISO 8601 date or date-time. At most 366 days after from.","schema":{"type":"string"},"example":"2026-11-18"},{"name":"quantity","in":"query","description":"Number of identical bikes needed.","schema":{"type":"integer","minimum":1,"maximum":50,"default":1}},{"name":"category","in":"query","description":"Category IDs, comma-separated (see /categories).","schema":{"type":"string"},"example":"e-bike,cargo-bike"},{"name":"sort","in":"query","schema":{"type":"string","enum":["recommended","distance","price_asc","price_desc","rating"],"default":"recommended"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","description":"next_cursor of the previous page, with otherwise identical parameters.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of bikes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RideList"}}}},"400":{"description":"Invalid input (parameter_missing, parameter_invalid).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (missing_api_key, invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (missing_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests (rate_limited, too_many_failed_attempts). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error on the ListNRide side (internal_error). Please retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rides/{id}":{"get":{"tags":["Rides"],"operationId":"getRide","summary":"Retrieve a bike","description":"Scope rides:read. With from/to, units_available is calculated.","parameters":[{"name":"id","in":"path","required":true,"description":"Bike ID","schema":{"type":"string"},"example":"ride_jK6nvpDczET3Adx8AKKn1w"},{"name":"from","in":"query","schema":{"type":"string"}},{"name":"to","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The bike","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RideDetail"}}}},"400":{"description":"Invalid period.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (missing_api_key, invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (missing_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Bike not found or no longer active (resource_missing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests (rate_limited, too_many_failed_attempts). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error on the ListNRide side (internal_error). Please retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkout/sessions":{"post":{"tags":["Checkout"],"operationId":"createCheckoutSession","summary":"Create a checkout session","description":"Scope bookings:write. The ListNRide checkout checks price and availability. Send the customer to url; the link is valid for 24 hours. In test mode, url shows a test page.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"400":{"description":"Invalid input (parameter_missing, parameter_invalid, outside_opening_hours, duration_too_short, duration_too_long).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key (missing_api_key, invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (missing_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Bike not found (resource_missing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not available for this period (ride_unavailable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests (rate_limited, too_many_failed_attempts). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error on the ListNRide side (internal_error). Please retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkout/sessions/{id}":{"get":{"tags":["Checkout"],"operationId":"getCheckoutSession","summary":"Retrieve a checkout session","description":"Scope bookings:read.","parameters":[{"name":"id","in":"path","required":true,"description":"Checkout session ID","schema":{"type":"string"},"example":"cs_O8t1fc2rdEG2GyYTqghvfA"}],"responses":{"200":{"description":"The session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"401":{"description":"Missing or invalid API key (missing_api_key, invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (missing_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (resource_missing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests (rate_limited, too_many_failed_attempts). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error on the ListNRide side (internal_error). Please retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bookings/{id}":{"get":{"tags":["Checkout"],"operationId":"getBooking","summary":"Retrieve a booking","description":"Scope bookings:read. Test bookings have IDs like bkg_test_...","parameters":[{"name":"id","in":"path","required":true,"description":"Booking ID","schema":{"type":"string"},"example":"bkg_gr9z-CSUh4I8UrC9WEwW2Q"}],"responses":{"200":{"description":"The booking","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Booking"}}}},"401":{"description":"Missing or invalid API key (missing_api_key, invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope (missing_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (resource_missing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests (rate_limited, too_many_failed_attempts). See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error on the ListNRide side (internal_error). Please retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"bookingStatus":{"post":{"operationId":"bookingStatusEvent","summary":"Booking status changed","description":"Types booking.<status> (e.g. booking.confirmed) and ping (connection test). Headers: LNR-Event, LNR-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<body>\")>. Non-2xx responses are retried after 1, 5, 30, 120, 360, 720 and 1440 minutes.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"lnr_test_... or lnr_live_..."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message"],"properties":{"type":{"type":"string","examples":["invalid_request_error","authentication_error","permission_error","not_found_error","rate_limit_error","api_error"]},"code":{"type":"string","examples":["ride_unavailable"]},"message":{"type":"string"},"param":{"type":["string","null"]},"request_id":{"type":"string"}}}}},"Category":{"type":"object","properties":{"object":{"const":"category"},"id":{"type":"string","examples":["e-bike"]},"parent":{"type":["string","null"]},"name":{"type":"object","properties":{"de":{"type":"string"},"en":{"type":"string"}}}}},"CategoryList":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"null"},"total":{"type":"integer"}}},"Ride":{"type":"object","properties":{"id":{"type":"string","examples":["ride_oEbNgLPApUJf52PkgHU49A"]},"object":{"const":"ride"},"name":{"type":["string","null"]},"brand":{"type":["string","null"]},"type":{"enum":["bike","accessory"]},"category":{"type":["object","null"]},"size":{"type":"object","properties":{"label":{"type":["string","null"]},"frame_size":{"type":["string","null"]},"variants":{"type":"array","items":{"type":"object","properties":{"size":{"type":"string"},"units":{"type":"integer"}}}}}},"location":{"type":"object","description":"For private listers without street and with rounded coordinates (precision=approximate).","properties":{"street":{"type":["string","null"]},"zip":{"type":["string","null"]},"city":{"type":["string","null"]},"district":{"type":["string","null"]},"country_code":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"precision":{"enum":["exact","approximate"]}}},"price":{"type":"object","properties":{"currency":{"const":"EUR"},"per_day":{"type":["integer","null"],"description":"Amount in cents."},"includes_basic_insurance":{"type":"boolean"}}},"rating":{"type":"object","properties":{"average":{"type":["number","null"]},"count":{"type":"integer"}}},"lister":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"is_business":{"type":"boolean"}}},"instant_booking":{"type":"boolean"},"is_top_booked":{"type":"boolean"},"availability":{"type":"object","properties":{"from":{"type":["string","null"],"format":"date-time"},"to":{"type":["string","null"],"format":"date-time"},"units_total":{"type":"integer"},"units_available":{"type":["integer","null"]}}},"image_url":{"type":["string","null"]},"web_url":{"type":"string"},"distance_km":{"type":["number","null"],"description":"Only in lists."}}},"RideList":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Ride"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"total":{"type":"integer"}}},"RideDetail":{"allOf":[{"$ref":"#/components/schemas/Ride"},{"type":"object","properties":{"description":{"type":["string","null"]},"images":{"type":"array","items":{"type":"object","properties":{"thumb":{"type":["string","null"]},"medium":{"type":["string","null"]},"original":{"type":["string","null"]}}}},"accessories":{"type":"array","items":{"type":"string"}},"deposit":{"type":["object","null"],"properties":{"amount":{"type":["integer","null"],"description":"Amount in cents."},"currency":{"const":"EUR"}}},"insurance":{"type":["object","null"],"properties":{"type":{"const":"basic"},"coverage":{"type":"object","properties":{"amount":{"type":["integer","null"],"description":"Amount in cents."},"currency":{"const":"EUR"}}}}}}}]},"CheckoutSessionCreate":{"type":"object","required":["ride","from","to","return_url"],"properties":{"ride":{"type":"string","examples":["ride_jK6nvpDczET3Adx8AKKn1w"]},"from":{"type":"string","format":"date","description":"Pick-up day YYYY-MM-DD"},"to":{"type":"string","format":"date","description":"Return day YYYY-MM-DD"},"pickup_time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","default":"10:00"},"return_time":{"type":"string","pattern":"^\\d{2}:\\d{2}$","default":"17:00"},"quantity":{"type":"integer","minimum":1,"maximum":50,"default":1},"return_url":{"type":"string","format":"uri","description":"https, max. 500 characters. checkout_session, booking and status=success are appended."},"cancel_url":{"type":"string","format":"uri","description":"https, optional."},"locale":{"enum":["de","en","fr","es","it","nl"]},"client_reference":{"type":"string","maxLength":100}}},"CheckoutSession":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"checkout_session"},"mode":{"enum":["test","live"]},"status":{"enum":["open","booked","expired"]},"url":{"type":"string"},"ride":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"pickup_time":{"type":["string","null"]},"return_time":{"type":["string","null"]},"quantity":{"type":"integer"},"locale":{"type":["string","null"]},"amount_total":{"type":["integer","null"],"description":"Amount in cents."},"currency":{"type":"string"},"return_url":{"type":"string"},"cancel_url":{"type":["string","null"]},"client_reference":{"type":["string","null"]},"booking":{"type":["string","null"],"description":"Booking ID once booked."},"created_at":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"}}},"Booking":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"booking"},"mode":{"enum":["test","live"]},"status":{"enum":["awaiting_payment","requested","accepted","confirmed","completed","canceled_by_lister","canceled_by_customer","expired","canceled"]},"reference":{"type":["string","null"],"examples":["LNR-w4kKb"]},"checkout_session":{"type":"string"},"ride":{"type":"string"},"from":{"type":["string","null"]},"to":{"type":["string","null"]},"quantity":{"type":"integer"},"amount_total":{"type":["integer","null"],"description":"Amount in cents."},"currency":{"type":"string"},"client_reference":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"}}},"Event":{"type":"object","properties":{"id":{"type":"string","examples":["evt_3kq..."]},"object":{"const":"event"},"type":{"type":"string","examples":["booking.confirmed","ping"]},"created":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/Booking"}}}}}}}}