REST API reference: Departures

The departure endpoints of the Rentals & Bookings REST API v1. A departure is one run of a product sold by departures (a tour, a class, a boat trip: see Rental types): its seats, its status, its guest list and check-in. These endpoints do the same as the Departures page in the app. The rest of the core REST API is in REST API reference: bookings and availability and REST API reference: warehouse, stock and settings; the guides and equipment on a run are in REST API reference: Staff & resources. Keys, limits, pagination and the error format are in the API overview. The same operations are in GraphQL: GraphQL API reference: Departures.

Every endpoint on this page needs the Rentals & Bookings app. GET needs a read key; everything else needs a key with Allow changes (write). A read key gets 403 rentals_rest_forbidden on a change. The Free plan’s API can read only: a change answers 403 rentals_rest_plan_required with data.plan: "free" and data.required_plan: "regular". The examples use two shell variables:

API="https://YOUR-API-ADDRESS/api/v1"   # the REST address from Settings › API
KEY="sirb_your_secret_key"

Ids in the examples are made up: product 88001 (variant 44001, rental product 12), departure 31, booking 42, guest 77.

How departures work #

• {ref} is a departure’s id or its key. Runs made by a product’s repeating departure times exist before anything is stored for them: such a run has id: null and only its key, p<rental product id>-<YYYYMMDDHHMM> (p12-202612050900 is rental product 12 at 2026-12-05 09:00). Every row has key. Changing a run (capacity, cut-off, cancelling, moving) stores it and gives it an id.
• Times are Y-m-d H:i in the store’s time zone; days are Y-m-d; *_at timestamps are ISO 8601, except checked_in_at, which is store time.
• Request bodies are JSON with snake_case names.

The departure #

Field	Notes
id, key	The stored id (null until the run is stored) and the key.
rental_product_id, product_id, variant_id, title	The product the run belongs to.
start, end, length	When it runs; length like 3h or 2d.
status	open, closed (sales closed by staff), cancelled or done (the end has passed).
one_off	Added as a one-off run, or moved from its repeating time.
capacity	The run’s own seat limit; null = the stock decides.
stock	The units the product has.
seats_total, seats_taken, seats_left	Seats in all, booked, and still free (null = no limit).
booked, bookings, checked_in	Seats booked on stored bookings, the number of bookings, and bookings checked in.
cutoff_minutes, cutoff_at	The run’s own cut-off (null = the product’s) and when sales stop.
sales_stopped	True when the run isn’t open or the cut-off has passed.
location_id	The run’s Shopify location, when set.
notes, notes_public	Notes for staff, and notes shown to guests.
cancel_reason, cancelled_at	For a cancelled run: weather, not_enough, other (or moved for the old time of a moved run).
min_guests, decide_by	The minimum number of guests for the run to go ahead (null = no minimum) and when that is decided.
guaranteed, run_state	With a minimum: pending_minimum, guaranteed or run_anyway (staff decided to run it below the minimum). Null without a minimum.
limited_by	When staff and resources free for the run are what limits its seats (“Limit sales”): {by: "staff", seats, short: [{index, role, count, have}]}. Left out otherwise.
staff	GET /departures/{ref} only: the people and resources assigned, [{kind: staff|resource, id, name, role, status}] (staff also with email and phone).

Runs #

GET /api/v1/departures #

Every run of the store’s departure products between two days, soonest first. Paged with page and per_page; the totals are in the X-Total and X-Total-Pages headers.

Parameter	Notes
from, to	Days, Y-m-d. Default: 14 days from today. At most 92 days.
product_id	One product’s runs.
location_id	One location’s runs.
status	open, closed, cancelled, done or all. Cancelled runs are listed only with status=cancelled or status=all.

curl -s "$API/departures?from=2026-12-05&to=2026-12-06&product_id=88001" -H "Authorization: Bearer $KEY"
# 200, X-Total: 2
[{"id": null, "key": "p12-202612050900", "rental_product_id": 12, "product_id": 88001, "variant_id": 44001,
  "title": "Harbour kayak tour", "start": "2026-12-05 09:00", "end": "2026-12-05 12:00", "length": "3h",
  "status": "open", "one_off": false, "capacity": null, "stock": 12, "seats_total": 12, "seats_taken": 4, "seats_left": 8,
  "booked": 0, "bookings": 0, "checked_in": 0, "cutoff_minutes": null, "cutoff_at": "2026-12-05 08:00", "sales_stopped": false,
  "location_id": null, "notes": null, "notes_public": null, "cancel_reason": null, "cancelled_at": null,
  "min_guests": 4, "decide_by": "2026-12-04 09:00", "guaranteed": true, "run_state": "guaranteed"}]

POST /api/v1/departures #

Add a one-off run (not one of the product’s repeating times). Answers 201 with the run.

Field	Notes
product_id (+ variant_id) or rental_product_id	Required: a product sold by departures.
start	Required: Y-m-d H:i, not in the past.
end or length	When it ends, or a length like 3h, 90m or 2d. Default: the length of the product’s first departure time.
capacity, cutoff_minutes, notes, notes_public	Optional, as for a change.

curl -s -X POST "$API/departures" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"product_id": 88001, "start": "2026-12-12 14:00", "length": "3h", "capacity": 8, "notes_public": "Sunset run"}'

409 rentals_rest_duplicate when the product already has a run at that time; 400 rentals_rest_invalid_param for a start in the past, a product not sold by departures, or a missing length.

GET /api/v1/departures/{ref} #

One run, with staff. An unknown ref is 404 rentals_rest_not_found.

curl -s "$API/departures/p12-202612050900" -H "Authorization: Bearer $KEY"

PUT or PATCH /api/v1/departures/{ref} #

Change a run. Only the fields you send change; send at least one. Answers the run.

Field	Notes
capacity	A whole number of seats; null or "" = the stock decides.
cutoff_minutes	Stop sales this many minutes before the start; null = the product’s.
status	open or closed (close or reopen sales). Cancel a run with /cancel.
notes, notes_public	Up to 2000 characters each.
min_guests	The run’s own minimum number of guests; null = the product’s.
decide_by_minutes	Decide about the minimum this many minutes before the start; null = the product’s.

curl -s -X PATCH "$API/departures/p12-202612050900" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"capacity": 10, "notes": "Two guides needed"}'

400 rentals_rest_invalid_param with nothing to change or a value out of range; 409 rentals_rest_cancelled when opening or closing a cancelled run.

POST /api/v1/departures/{ref}/run-anyway #

Run a departure that is below its minimum anyway: no more alerts, run_state becomes run_anyway. Answers the run.

Guest list #

GET /api/v1/departures/{ref}/manifest #

The run’s guest list, one row per booking.

Field	Notes
departure, staff	The run and who is assigned.
pickups	The pickup points with their guests: [{id, name, address, at, map, guests, bookings}].
itinerary	For multi-day trips: [{day, title, text, overnight}].
rows	[{number, booking_id, name, guests, adults, children, seniors, students, other_guests, private, participants, pickup, order, order_id, phone, email, notes, balance_due, checked_in_at, no_show, ticket}]. ticket is the booking’s ticket code.
totals	{bookings, guests, checked_in}.

curl -s "$API/departures/31/manifest" -H "Authorization: Bearer $KEY"

GET /api/v1/departures/{ref}/manifest.csv #

The same guest list as a CSV file.

Cancelling and moving #

GET /api/v1/departures/{ref}/cancel-preview #

What cancelling would do. outcome is refund (default) or offer. Answers {departure, bookings, guests, refund_total, currency, manual}: refund_total is null for offer; manual counts the bookings that must be refunded by hand.

POST /api/v1/departures/{ref}/cancel #

Cancel a run. Guests are refunded (or offered another run) and told; staff on the run are told.

Field	Notes
reason	weather, not_enough or other (default).
outcome	refund (default): each booking is cancelled and refunded in full, to the way the guest paid. offer: guests get an email with the next runs that have seats; a booking that isn’t moved within 7 days is refunded.
notify_guests, notify_staff	Default true.
note	A note for the guests’ email, up to 1000 characters.

curl -s -X POST "$API/departures/31/cancel" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"reason": "weather", "outcome": "refund", "note": "High winds on the harbour."}'
# 200 (the run shortened here)
{"departure": {"id": 31, "key": "p12-202612050900", "status": "cancelled", "cancel_reason": "weather", "cancelled_at": "2026-12-04T18:02:11+00:00"},
 "results": [{"booking": 42, "order": "#1042", "refunded": true, "amount": 90, "refund_error": null, "emailed": true}]}

409 rentals_rest_cancelled when it is already cancelled.

POST /api/v1/departures/cancel-day #

Cancel every run that starts on a day (a storm). Runs already cancelled or done are left alone.

Field	Notes
date	Required: Y-m-d.
product_ids	Only these products’ runs.
reason, outcome, notify_guests, notify_staff, note	As for one run.

Answers {date, cancelled, departures, results}.

POST /api/v1/departures/{ref}/move #

Change a run’s time. Its bookings move with it; the end keeps the run’s length.

Field	Notes
start	Required: the new start, Y-m-d H:i.
notify_guests	Default true: guests get an email.

Answers {departure, moved, failed} (failed: [{booking, message}]). 409 rentals_rest_duplicate when the product has a run at the new time; 409 rentals_rest_cancelled for a cancelled run.

Check-in and guest names #

POST /api/v1/departures/check-in #

Check a booking in, undo it, or mark a no-show.

Field	Notes
booking_id or code	The booking, or the code on the guest’s ticket (like 42-3fa9c1d2e4b5, or the whole ticket address the QR code holds).
departure_id	The run being checked in: a ticket for another run answers a wrong_departure warning.
action	check_in (default), undo or no_show.

curl -s -X POST "$API/departures/check-in" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"code": "42-3fa9c1d2e4b5", "departure_id": 31}'
# 200
{"booking": {"id": 42, "departure_id": 31, "order": "#1042", "status": "reserved", "guests": 2,
             "checked_in_at": "2026-12-05 08:52", "no_show": false},
 "warnings": []}

warnings may hold already (checked in before), wrong_departure or cancelled (a cancelled booking is not checked in). 404 rentals_rest_not_found for a code that isn’t a ticket of the store; 409 rentals_rest_checked_in for a no-show on a booking that is checked in (undo first).

GET /api/v1/bookings/{id}/participants #

A booking’s named guests: {booking_id, ask, seats, participants}. ask is the product’s setting: off, optional or required. A guest: {id, position, name, email, phone, checked_in_at, no_show, waiver, waiver_url, details} (empty fields are left out; waiver and waiver_url with the E-Sign Contracts & Waivers app, when each guest signs).

PUT /api/v1/bookings/{id}/participants #

Replace a booking’s names. At most one name per seat; a position keeps its check-in.

curl -s -X PUT "$API/bookings/42/participants" -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"participants": [{"name": "Jordan Lee", "email": "[email protected]"}, {"name": "Sam Lee"}]}'

409 rentals_rest_cancelled for a cancelled booking.

POST /api/v1/participants/{id}/check-in #

Check one named guest in. action is check_in (default), undo or no_show. Answers {participant}. The first guest checked in checks the booking in too.

Errors #

Errors have the shape described in the API overview. The codes these endpoints add:

Status	Code	When
404	rentals_rest_not_found	No run, booking, guest or ticket with that ref, id or code.
409	rentals_rest_duplicate	The product already has a run at that time.
409	rentals_rest_cancelled	The run (or booking) is cancelled.
409	rentals_rest_checked_in	A no-show for a booking that is checked in.
400	rentals_rest_invalid_param	A value is wrong: data.field names it (days, times, reason, outcome, action, capacity…).