Bookings API

The Bookings API handles the complete booking lifecycle — from creation through completion or cancellation.

Booking Statuses

Status	Description
`pending`	Created but not yet confirmed/paid
`confirmed`	Payment received, booking confirmed
`active`	Customer has picked up the rental
`completed`	Rental returned, booking closed
`cancelled`	Booking cancelled

List Bookings

GET /v1/bookings

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status
`customer_id`	string	Filter by customer
`pickup_date_from`	string	Filter bookings with pickup date ≥ this value (ISO 8601)
`pickup_date_to`	string	Filter bookings with pickup date ≤ this value (ISO 8601)
`cursor`	string	Pagination cursor
`limit`	integer	Results per page (1–100, default 20)

// List confirmed bookings
const bookings = await renta.bookings.list({ status: 'confirmed' });

// Filter by date range
const julyBookings = await renta.bookings.list({
  pickup_date_from: '2026-07-01T00:00:00Z',
  pickup_date_to: '2026-07-31T23:59:59Z',
});

// Auto-paginate
for await (const booking of renta.bookings.list()) {
  console.log(`${booking.id}: ${booking.status}`);
}

curl "https://api.getrenta.io/v1/bookings?status=confirmed&limit=10" \
  -H "Authorization: Bearer renta_sk_live_..."

Response:

{
  "data": [
    {
      "id": "bk_def456",
      "status": "confirmed",
      "customer_id": "cust_abc",
      "customer": {
        "id": "cust_abc",
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "+1234567890"
      },
      "pickup_date": "2026-07-01T09:00:00Z",
      "return_date": "2026-07-03T17:00:00Z",
      "pickup_location_id": "loc_main",
      "half_day": false,
      "subtotal": 10000,
      "tax_amount": 800,
      "discount_amount": 0,
      "total": 10800,
      "amount_paid": 10800,
      "amount_owed": 0,
      "coupon_id": null,
      "notes": null,
      "line_items": [
        {
          "id": "li_001",
          "fleet_item_id": "fi_abc123",
          "fleet_item_name": "Trail Blazer 500",
          "quantity": 1,
          "unit_price": 5000,
          "override_price": null,
          "line_total": 10000
        }
      ],
      "addons": [
        {
          "id": "ba_001",
          "addon_id": "addon_helmet",
          "addon_name": "Helmet",
          "quantity": 1,
          "unit_price": 500,
          "line_total": 500
        }
      ],
      "created_at": "2026-03-31T12:00:00Z",
      "updated_at": "2026-03-31T12:05:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Get Booking

GET /v1/bookings/:id

const booking = await renta.bookings.get('bk_def456');
console.log(booking.status); // "confirmed"
console.log(booking.customer.name); // "John Doe"
console.log(booking.adjustments); // price adjustments

curl https://api.getrenta.io/v1/bookings/bk_def456 \
  -H "Authorization: Bearer renta_sk_live_..."

The single-booking response includes an adjustments array with any price adjustments applied:

{
  "id": "bk_def456",
  "status": "confirmed",
  "customer": {
    "id": "cust_abc",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  },
  "adjustments": [
    {
      "id": "adj_001",
      "type": "dollar",
      "amount": -500,
      "description": "Loyalty discount",
      "created_at": "2026-03-31T12:05:00Z"
    }
  ]
}

Create Booking

POST /v1/bookings

Body Parameters:

Parameter	Type	Required	Description
`customer_id`	string	✅	Customer ID
`pickup_date`	string	✅	Pickup date (ISO 8601)
`return_date`	string	✅	Return date (ISO 8601)
`line_items`	array	✅	Array of `{fleet_item_id, quantity?}`
`addons`	array	—	Array of `{addon_id, quantity}`
`pickup_location_id`	string	—	Pickup location ID
`half_day`	boolean	—	Half-day rental (default `false`)
`coupon_code`	string	—	Coupon code to apply
`notes`	string	—	Internal notes

The pricing engine automatically calculates subtotal, tax, discounts, and total based on item rates, duration, add-ons, seasonal pricing rules, and coupons.

const booking = await renta.bookings.create({
  customer_id: 'cust_abc',
  pickup_date: '2026-07-01T09:00:00Z',
  return_date: '2026-07-03T17:00:00Z',
  line_items: [
    { fleet_item_id: 'fi_abc123' },
    { fleet_item_id: 'fi_def456', quantity: 2 },
  ],
  addons: [
    { addon_id: 'addon_helmet', quantity: 3 },
  ],
  coupon_code: 'SUMMER20',
  notes: 'VIP customer — complimentary upgrade',
});

curl -X POST https://api.getrenta.io/v1/bookings \
  -H "Authorization: Bearer renta_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc",
    "pickup_date": "2026-07-01T09:00:00Z",
    "return_date": "2026-07-03T17:00:00Z",
    "line_items": [
      {"fleet_item_id": "fi_abc123"},
      {"fleet_item_id": "fi_def456", "quantity": 2}
    ],
    "addons": [
      {"addon_id": "addon_helmet", "quantity": 3}
    ],
    "coupon_code": "SUMMER20"
  }'

Update Booking

PATCH /v1/bookings/:id

Body Parameters:

Parameter	Type	Description
`notes`	string	Internal notes (max 2000 chars)
`status`	string	Status transition (validated)
`pickup_location_id`	string	Change pickup location

await renta.bookings.update('bk_def456', {
  notes: 'VIP customer',
  status: 'confirmed',
});

curl -X PATCH https://api.getrenta.io/v1/bookings/bk_def456 \
  -H "Authorization: Bearer renta_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"notes": "VIP customer", "status": "confirmed"}'

Cancel Booking

POST /v1/bookings/:id/cancel

Body Parameters:

Parameter	Type	Required	Description
`reason`	string	—	Cancellation reason

await renta.bookings.cancel('bk_def456', {
  reason: 'Customer requested cancellation due to weather',
});

curl -X POST https://api.getrenta.io/v1/bookings/bk_def456/cancel \
  -H "Authorization: Bearer renta_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "Weather cancellation"}'

Extend Booking

POST /v1/bookings/:id/extend

Extend a booking's return date. Recalculates pricing automatically.

Body Parameters:

Parameter	Type	Required	Description
`new_return_date`	string	✅	New return date (ISO 8601, must be after current return date)

await renta.bookings.extend('bk_def456', {
  new_return_date: '2026-07-05T17:00:00Z',
});

curl -X POST https://api.getrenta.io/v1/bookings/bk_def456/extend \
  -H "Authorization: Bearer renta_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"new_return_date": "2026-07-05T17:00:00Z"}'

Swap Line Item

POST /v1/bookings/:id/swap-item

Replace one fleet item in a booking with another. Useful when the original item becomes unavailable.

Body Parameters:

Parameter	Type	Required	Description
`line_item_id`	string	✅	Line item to replace
`new_fleet_item_id`	string	✅	Replacement fleet item

await renta.bookings.swapItem('bk_def456', {
  line_item_id: 'li_001',
  new_fleet_item_id: 'fi_upgrade',
});

curl -X POST https://api.getrenta.io/v1/bookings/bk_def456/swap-item \
  -H "Authorization: Bearer renta_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "line_item_id": "li_001",
    "new_fleet_item_id": "fi_upgrade"
  }'

Swapping items recalculates pricing based on the new item's rates. The change is logged in the booking's change_log.

On this page