API Reference

Returns a page of your bookings, newest first — the same records behind the operator portal’s Bookings list. Use this to poll for changes, reconcile your own records, or back a custom dashboard; if you just need to react to changes as they happen, a webhook subscription (see Webhooks) is cheaper than polling and lower-latency. Filter by status, or fetch a single booking directly via GET /bookings/{reference}.

const response = await fetch('https://your-rideloop-domain/api/v1/bookings?limit=…', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer rlk_...',
  },
})

const data = await response.json()

{
  "bookings": [
    {
      "id": "…",
      "reference": "RB-2026-000123",
      "status": "CONFIRMED",
      "itemName": "Mountain Bike",
      "startDate": "2026-08-01T00:00:00.000Z",
      "endDate": "2026-08-03T00:00:00.000Z",
      "guestName": "Jane Doe",
      "guestEmail": "jane@example.com",
      "estimatedTotalMinor": 10000,
      "amountPaidMinor": 5000,
      "outstandingMinor": 5000,
      "paymentOption": "DEPOSIT",
      "paymentStatus": "PARTIALLY_PAID",
      "depositMinor": 5000,
      "taxMinor": 0,
      "whatsappOptedIn": true,
      "createdVia": "STOREFRONT",
      "createdAt": "2026-07-01T00:00:00.000Z",
      "idVerificationStatus": "NOT_REQUIRED",
      "rescheduleOfferStatus": "NOT_APPLICABLE"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "totalCount": 1 }
}

Creates a booking — either a bike-category rental (categoryId + size) or a guided tour/holiday package booking (itemType + itemId). Runs the exact same pricing, availability, waiver/terms, and payment pipeline as the public storefront. When the operator has an active waiver or terms template, this request must supply acceptance the same way a guest would — there is no relaxed path for API callers. Every new booking starts life as PENDING and fires a booking.created webhook immediately; for paymentOption "DEPOSIT"/"FULL", it only moves to CONFIRMED (and fires booking.confirmed + payment.received) once the guest actually completes the returned checkoutUrl — see How payments work.

const response = await fetch('https://your-rideloop-domain/api/v1/bookings', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer rlk_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "categoryId": "…",
  "size": "M",
  "startDate": "2026-08-01",
  "endDate": "2026-08-03",
  "guestName": "Jane Doe",
  "guestEmail": "jane@example.com",
  "paymentOption": "DEPOSIT",
  "whatsappOptedIn": true
}),
})

const data = await response.json()

{
  "id": "…",
  "reference": "RB-2026-000124",
  "status": "PENDING",
  "itemName": "Mountain Bike",
  "startDate": "2026-08-01T00:00:00.000Z",
  "endDate": "2026-08-03T00:00:00.000Z",
  "guestName": "Jane Doe",
  "guestEmail": "jane@example.com",
  "estimatedTotalMinor": 10000,
  "amountPaidMinor": 0,
  "outstandingMinor": 10000,
  "paymentOption": "DEPOSIT",
  "paymentStatus": "AWAITING_PAYMENT",
  "depositMinor": 5000,
  "taxMinor": 0,
  "whatsappOptedIn": true,
  "createdVia": "API",
  "createdAt": "2026-07-01T00:00:00.000Z",
  "idVerificationStatus": "NOT_REQUIRED",
  "rescheduleOfferStatus": "NOT_APPLICABLE",
  "checkoutUrl": "https://checkout.stripe.com/…"
}

Fetches a single booking by its reference — the same shape returned by GET /bookings and pushed in every booking-related webhook payload, so you never need to reconcile two different representations. A booking moves through PENDING → CONFIRMED → INPROGRESS → COMPLETED as it’s paid, picked up, and returned; CANCELLED is reachable from any of the first three. Use PATCH on this same path to drive that transition yourself.

const response = await fetch('https://your-rideloop-domain/api/v1/bookings/{reference}', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer rlk_...',
  },
})

const data = await response.json()

{
  "id": "…",
  "reference": "RB-2026-000123",
  "status": "CONFIRMED",
  "itemName": "Mountain Bike",
  "startDate": "2026-08-01T00:00:00.000Z",
  "endDate": "2026-08-03T00:00:00.000Z",
  "guestName": "Jane Doe",
  "guestEmail": "jane@example.com",
  "estimatedTotalMinor": 10000,
  "amountPaidMinor": 5000,
  "outstandingMinor": 5000,
  "paymentOption": "DEPOSIT",
  "paymentStatus": "PARTIALLY_PAID",
  "depositMinor": 5000,
  "taxMinor": 0,
  "whatsappOptedIn": true,
  "createdVia": "API",
  "createdAt": "2026-07-01T00:00:00.000Z",
  "idVerificationStatus": "NOT_REQUIRED",
  "rescheduleOfferStatus": "NOT_APPLICABLE"
}

Transitions a booking’s status. Setting status to "CANCELLED" runs the same cancellation pipeline as the operator portal (computes and issues any refund due, voids an open security-deposit hold) and fires a booking.cancelled webhook, plus payment.refunded if money came back — every other target is a plain status change, firing the matching booking.confirmed/booking.completed event. Only the transitions already valid for the booking’s current status are accepted (e.g. a COMPLETED booking can’t be reopened) — see GET /bookings/{reference} for the full status lifecycle.

const response = await fetch('https://your-rideloop-domain/api/v1/bookings/{reference}', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer rlk_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ "status": "CANCELLED" }),
})

const data = await response.json()

{ "ok": true, "refundedMinor": 5000 }

Creates a Stripe Checkout link for whatever a booking still owes, and emails it to the guest. Defaults to the full outstanding balance. A more sensitive action than booking creation — money moves against an EXISTING booking — so it needs its own payments:write scope. Once the guest pays, a payment.received webhook fires and the booking's amountPaidMinor/outstandingMinor update — poll GET /bookings/{reference}/payments if you'd rather check than wait for the webhook.

const response = await fetch('https://your-rideloop-domain/api/v1/bookings/{reference}/payment-links', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer rlk_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ "amountMinor": 5000 }),
})

const data = await response.json()

{ "url": "https://checkout.stripe.com/…" }

Returns every payment recorded against a booking, newest first — deposits, balance charges, and refunds alike, each with its own status. Use it to reconcile what a guest has actually paid against the booking’s estimatedTotalMinor/amountPaidMinor/outstandingMinor, or to look up a specific charge after receiving a payment.received, payment.failed, or payment.refunded webhook.

const response = await fetch('https://your-rideloop-domain/api/v1/bookings/{reference}/payments', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer rlk_...',
  },
})

const data = await response.json()

{
  "payments": [
    {
      "id": "…",
      "amountMinor": 5000,
      "currency": "GBP",
      "type": "CHARGE",
      "status": "SUCCEEDED",
      "purpose": "DEPOSIT",
      "createdAt": "2026-07-01T00:00:00.000Z"
    }
  ]
}

Returns your published bike categories, guided tours, and holiday packages — the same catalog a guest sees on your storefront, minus anything still in draft. Each entry’s id is what you pass back as categoryId or itemId when creating a booking with POST /bookings, so this is typically the first call an integration makes: list the fleet, then book against one of the ids it returns.

const response = await fetch('https://your-rideloop-domain/api/v1/fleet', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer rlk_...',
  },
})

const data = await response.json()

{
  "categories": [{ "type": "category", "id": "…", "slug": "mountain-bike", "name": "Mountain Bike", "shortDescription": "…" }],
  "tours": [{ "type": "tour", "id": "…", "slug": "alps-loop", "name": "Alps Loop", "subtitle": "…", "pricePerPersonMinor": 5000 }],
  "packages": [{ "type": "package", "id": "…", "slug": "tuscany-week", "name": "Tuscany Week", "subtitle": "…", "priceFromMinor": 80000 }]
}

Checks whether a bike category, guided tour, or holiday package is available on real dates and returns its real price — never invented stock. When it isn’t available, you still get a 200 back with `available: false` and a real `alternatives` list of dates that ARE free, so your own UI can offer a next step instead of a dead end. Use GET /fleet first to get the real categoryId/tourId/packageId (and, for a package, this endpoint’s own variantOptions/accommodationOptions on a first call) — this endpoint always takes real ids, never a fuzzy name match. Also returns waiverRequired/termsRequired (collect these before calling POST /bookings whenever either is true) and the active add-ons catalog, each already priced for this exact stay (totalMinorForStay) — never recompute that yourself. When an automatic discount campaign applies, campaignName/discountMinor/discountedPriceMinor are included; otherwise they’re omitted entirely, so check for their presence rather than treating a missing discount as zero.

const response = await fetch('https://your-rideloop-domain/api/v1/availability?productType=…', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer rlk_...',
  },
})

const data = await response.json()

{
  "ok": true,
  "available": true,
  "productType": "bike",
  "productId": "…",
  "categoryName": "Mountain Bike",
  "requestedStartDate": "2026-08-01",
  "requestedEndDate": "2026-08-03",
  "priceMinor": 6000,
  "securityDepositMinor": 500,
  "rentalDays": 3,
  "addOns": [{ "name": "Helmet", "pricingType": "FLAT", "priceMinor": 500, "totalMinorForStay": 500 }],
  "waiverRequired": false,
  "termsRequired": true,
  "hasElectricAssist": false,
  "categoryType": "MOUNTAIN",
  "sizes": ["S", "M", "L"]
}