Skip to main content

Rental

A rental gives a user access to a vehicle. Start and end a rental to begin and complete a ride; at the end, the price is returned so the partner can charge the user. A user can rent only one vehicle at a time, and pre-booking is not possible.

The rental model​

Every rental endpoint responds with the rental model below (wrapped in a data array).

{
  "data": [
    {
      "id": "82267e03-f5b1-4b76-86c6-9f07df279372",
      "type": "rental",
      "attributes": {
        "rentalDurationMin": 12,
        "rentalDistanceMeters": 142,
        "cost": {
          "startPrice": 150,
          "pricePerMinute": 30,
          "subtotal": 429,
          "total": { "amount": 510, "currency": "EUR", "vat": 81, "vatPercentage": 0.19 }
        },
        "state": "ENDED",
        "startedAt": "2020-01-13T16:02:05.44409597Z",
        "endedAt": "2020-01-13T16:13:20.44314233Z",
        "userStartLocation": { "longitude": 18.0757, "latitude": 59.3190 },
        "userEndLocation": { "longitude": 18.0757, "latitude": 59.3190 },
        "vehicle": { "vehicleId": "7983e884-1111-2222-3333-f50ce017fcc8", "vehicleCode": "xray" },
        "vehicleStartLocation": { "longitude": 18.0757, "latitude": 59.3190 },
        "vehicleEndLocation": { "longitude": 18.0757, "latitude": 59.3190 },
        "receipt": { "url": "https://example.com/receipt.pdf" }
      }
    }
  ]
}
FieldTypeDescription
idstringThe rental's unique id (UUID v4).
typestringAlways rental.
rentalDurationMinintegerDuration in full minutes, rounded up. Used to calculate the charge.
rentalDistanceMetersintegerDistance travelled in full meters, rounded up.
costobjectCost breakdown — see below.
statestringRUNNING (during) · ENDED (normal) · ENDED_WITH_NO_CHARGE (auto-ended, no charge) · ENDED_INTERNALLY (ended by Voi, e.g. user forgot to).
startedAt / endedAtstringStart / end time (RFC3339, UTC). endedAt is present once ended.
vehicleobjectvehicleId (UUID v4) and vehicleCode (4-letter code).
userStartLocation / userEndLocationobjectlongitude/latitude provided by the user (optional).
vehicleStartLocation / vehicleEndLocationobjectThe vehicle's own longitude/latitude.
receiptobject{ "url": ... } — link to a PDF receipt. Expires after 15 minutes.

Cost — startPrice (unlock fee), pricePerMinute, and subtotal (excl. VAT) are all in minor units; total holds amount (incl. VAT), currency (ISO 4217), vat and vatPercentage.

Notes

  • Amounts are always in minor units. Most currencies use 1/100, e.g. { "amount": 1213, "currency": "EUR" } = €12.13.
  • Receipt links expire after 15 minutes.
  • Location: if a start/end location is provided via the API, the phone's location defines the end-ride position; otherwise the vehicle's own location (updated every 15 seconds) is used.

See Payments for fines, short-ride rules, refunds and invoicing.