Experiences Tools
These tools are only advertised to AI clients when the supplier has the Experiences module enabled. See Per-supplier tool filtering for details.
Manage tours, activities, and classes. Check schedules and availability, view rate categories, create new experiences, and manage guide assignments for slots.
Required scope: experiences:read for read tools, experiences:write for write tools. Guide assignment tools additionally require staff:read / staff:write.
Tools Overview
| Tool | Description | Read-only? |
|---|---|---|
list_experiences | List experiences with optional filters | Yes |
get_experience | Get detailed experience information | Yes |
check_experience_availability | Check available time slots for a date | Yes |
get_experience_schedule | Departures past or upcoming, with how full each one is, who leads each, and people booked per guide | Yes |
check_departure_fit | For one booking, request or departure: what booked holds its boat or vehicle, which unbooked departures it closes, and who can lead it | Yes |
list_experience_rate_categories | List rate categories (Adult, Child, etc.) | Yes |
create_experience | Create a new experience | No |
bulk_change_session_duration | Change how long selected timed sessions run | No |
list_experience_guides | List guides assigned to an availability slot | Yes |
get_available_guides_for_slot | Get grouped guide availability for a slot | Yes |
assign_guides_to_experience | Assign one or more guides to a slot | No |
remove_guide_from_experience | Remove a guide from a slot | No |
complete_session | Complete one session for everyone on it who checked in | No |
mark_participants_back | Mark people back from a session they were checked in on | No |
set_group_size_prices | Price an activity by the size of the group, one private way of booking per size | No |
list_experience_sessions | One experience's sessions with ids, capacity, booked and spots on sale | Yes |
get_series | One program with its sessions and, for a reusable program, each cohort's dates, enrolled count and seats left | Yes |
get_program_insights | A program's summary: upcoming sessions, enrollments, revenue, pricing and its cohorts | Yes |
set_group_size_prices
Price an activity by the size of the group: "$90 for 2, $120 for 3 to 4, $160 for 5 to 8". Each size becomes one private way of booking it with its own price, on the same activity. Sent again, it updates the same ones, so a change to one size sends every size. Asks the owner before it saves.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
experience_id | integer | Yes | The activity |
sizes | object[] | Yes | One entry per group size, smallest first: min_people, max_people, price |
word | string | No | The owner's word for the people in a group, plural, such as players. Defaults to people |
At least two sizes are needed. For one price for any group, use set_experience_price.
{
"experience_id": 1234567,
"sizes": [
{ "min_people": 2, "max_people": 2, "price": 90 },
{ "min_people": 3, "max_people": 4, "price": 120 },
{ "min_people": 5, "max_people": 8, "price": 160 }
],
"word": "players"
}
The result lists each way of booking with its name ("3 to 4 players"), party size, whether it is private and its price.
complete_session
Complete one session (departure) for everyone on it who checked in, in one go. Each booking with someone checked in has this session completed. A booking whose last day this was is completed in full and gets the business's after-the-day message. Bookings nobody checked in on are left alone. Needs the bookings:write scope, and the person must be able to fulfil bookings or check people in.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
schedule_id | integer | Yes | The session (departure) to complete |
Returns completed (how many bookings were completed) and booking_ids. Anyone checked in and not
marked back is recorded back by Complete.
mark_participants_back
Mark people back from a session they were checked in on: named people by participant_ids,
everyone on one booking (booking_id, people not named yet included), or everyone still out
(everyone: true). undo: true with participant_ids puts them back to still out. When the last
person out is marked back the session completes, as complete_session does. Needs the
bookings:write scope, and the person must be able to fulfil bookings or check people in.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
schedule_id | integer | Yes | The session (departure) they went out on |
participant_ids | integer[] | No | Named people to mark back (participants[].id from the manifest) |
booking_id | integer | No | Mark everyone on this booking back |
everyone | boolean | No | Mark everyone still out back |
undo | boolean | No | With participant_ids: they are still out after all |
Returns results, session_finished, checked_in_count, back_count and out_count.
list_experiences
List experiences/tours with optional filters. Returns details including pricing, duration, and capacity.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
search | string | No | Search by name |
category_id | integer | No | Filter by category |
limit | integer | No | Number of results (default 10) |
get_experience
Get detailed information about an experience.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
experience_id | integer | Yes | The experience ID |
check_departure_fit
Whether one departure fits before you say yes to it. Returns the shared item it runs on (a boat, a vehicle, a room) with the booked departures or rentals already holding it at that time and the unbooked departures it closes, and who can lead it: guides already leading it, guides free then with the certificates they hold (captain_license is true for a license to be in charge of a boat), guides busy and what they are leading, and guides on time off. For a request still waiting, the guides are the ones approval would choose from. Each part has an in_words line.
Needs the bookings:read scope.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
booking_id | integer | No | A booking or booking request |
schedule_id | integer | No | A departure, instead of a booking |
experience_id | integer | No | With date and time: the experience to check |
date | string | No | With experience_id: YYYY-MM-DD |
time | string | No | With experience_id: start time in the business's timezone, HH:MM |
Pass booking_id, or schedule_id, or experience_id with date and time.
check_experience_availability
Check available time slots for an experience on a specific date. Returns scheduled sessions with capacity, availability, and pricing.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
experience_id | integer | Yes | The experience ID |
date | string | Yes | Date to check availability for |
participants | integer | No | Number of participants needed |
get_experience_schedule
Scheduled experience departures, past or upcoming, with how many were booked against capacity and, for upcoming ones, the open spots. Answers how-full questions over a range: summary, by_experience and by_guide (each guide's departures and the people booked on them) cover every departure in the range, and sessions lists up to limit of them. Same numbers as GET /v1/reports/departure-fill.
An upcoming departure with open_spots 0 and a not_selling_because has empty places it cannot sell (no guide free, equipment or shared places in use, closed, held in carts); it is not full.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
experience_id | integer | No | Filter to a specific experience. If omitted, shows all. |
item | string | No | A shared item the experiences run on (a boat, a vehicle, a room), by name or id. Returns every departure of every experience that runs on it, in time order, each with ends, plus item.booked_on_its_own. When the name matches nothing and experience_id is given, the item that experience runs on is used and item.matched says so. |
at_time | string | No | With item: a time HH:MM (24-hour, business time) on date_from. Returns item.at_time with free, the booked departures running then, and the departures still on sale that run then. |
period | string | No | today, yesterday, this_week, last_week, next_week, this_month, last_month, next_month, in the business's timezone |
date_from | string | No | Start date YYYY-MM-DD (default: today). Ignored when period is set. |
date_to | string | No | End date YYYY-MM-DD (default: 7 days from date_from). At most 93 days. |
fill_below_percent | integer | No | Only departures booked under this percent of capacity, e.g. 50 |
sort | string | No | date (default), emptiest or fullest |
limit | integer | No | Departures to list by name (default 20, max 50). Totals always cover the whole range. |
Each session includes date, time, price (not with item), capacity, booked, fill_percent (0 to 100, in the unit the departure sells) and open_spots. Asked with experience_id for an experience that shares its item with others, the result adds same_item_other_trips: what the other experiences on that item are doing over the same range. Multi-day departures (one booking spanning several days) additionally include multi_day: true, an end_date, and a human-readable span (e.g. "3 days · Jul 13 9:00 AM – Jul 15 5:00 PM") — so a multi-day trek is never mistaken for a single morning slot.
list_experience_sessions
One experience's sessions with their session_id, date, time, capacity, booked, available (the spots still on sale) and guides. Takes experience_id (required), status (Upcoming, the default, or Past), date_from, date_to, guide_id, location_id and limit (default 50, max 200).
A short or empty list can carry how_to_read saying why: more_sessions: true when the list stopped at limit and later sessions exist, or a range the status leaves out (an Upcoming request for dates that already passed, a Past request for dates still to come). An empty list with how_to_read does not mean nothing is scheduled.
get_series
One program with its sessions, bookings and totals. Takes series_id.
For a reusable program, cohorts lists each cohort (archived ones left out) with first_date, last_date, sessions_count, enrolled, enrollment_cap and seats_left. enrolled is the count the program's Cohorts tab shows. seats_left is how many more can enroll: the tighter of the cohort's cap and the emptiest session still to run. null means nothing limits it, and 0 means full or every date has run. A program sold on its own carries its own seats_left.
{
"series": {
"id": 24,
"name": "Kids Surf Camp - 5 Mornings",
"is_reusable_template": true,
"cohorts": [
{
"id": 26,
"name": "February Break Camp",
"first_date": "February 8th 2027",
"last_date": "February 12th 2027",
"sessions_count": 5,
"enrolled": 1,
"enrollment_cap": 8,
"seats_left": 7
}
]
}
}
get_program_insights
A program's summary for its own page: upcoming_sessions_count, next_session_date, enrollments_count, enrolled_count, revenue_total and pricing_summary, plus the same cohorts rows as get_series. For a reusable program the counts cover its cohorts, the same numbers the program page shows. Takes series_id.
list_experience_rate_categories
List experience rate categories (e.g., Adult, Child, Senior) used for participant-based pricing. Call this before creating an experience with participant pricing to get the rate category IDs.
Parameters
None.
create_experience
Create a new experience/activity. Pricing can be "group" (single price per group) or "participant" (per-person with rate categories).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Experience name |
price_structure | string | Yes | group (single price) or participant (per-person pricing) |
price | number | No | Price for group pricing (required if price_structure is group) |
max_participants | integer | No | Maximum participants per group. For a private activity without unit_name or an explicit max_group_size, this also sets its party limit. |
participant_rates | array | No | Per-price amounts: [{rate_category_id or rate_category_label, price}] (required for participant pricing) |
equipment | array | No | Full gear list. Each row has product_id, units_basis and units_per; add rate_category_id or rate_category_label to reserve the item only for that price. |
duration_value | number | No | Duration number (e.g., 1.5 for 1.5 hours) |
duration_unit | string | No | Duration unit (default: Hours) |
recurring_schedule | object | No | Create the activity and its repeating calendar together. Accepts times (HH:mm), days_of_week, date_from, date_to, repeats_yearly, window_opens, window_closes, every_value, and every_unit. |
default_capacity | integer | No | Maximum groups per start for a private activity, or participant seats for a shared activity. A plain private group activity defaults to one group per start when omitted. Explicit larger counts are supported. The people limit for each private group is max_group_size. |
is_private | boolean | No | Default true. Each private booking reserves its own group; another customer can book a remaining group up to default_capacity. Set false for shared experiences where groups fill participant seats. |
category_id | integer | No | Primary experience category ID. Use category_ids for multiple. |
category_ids | integer[] | No | Put the experience in multiple categories (primary first). |
brief_description | string | No | Brief summary (max 250 characters) |
location | string | No | Location where the experience takes place |
required_certifications | string[] | No | What a guide should hold to run this experience. Flags, never blocks. See Guide requirements. |
required_languages | string[] | No | What a guide should speak to run this experience, as two-letter codes. Flags, never blocks. See Guide requirements. |
whats_included | array | No | [{label, description}] rows. See Content Blocks. |
does_not_include | array | No | [{label, description}] rows — what's not included. See Content Blocks. |
itinerary | array | No | [{time, title, description}] rows. |
highlights | array | No | Flat list of strings (pill chips). |
check_in_details | string | No | Rich-text HTML, sanitized to the allowlist at write time. |
what_to_bring | array | No | Flat list of strings (pill chips). |
restrictions | string | No | Rich-text HTML — age / weight / skill requirements. |
health_and_safety | string | No | Rich-text HTML — safety statement. |
cancellation_notes | string | No | Rich-text HTML — customer-facing cancellation notes. |
custom_sections | array | No | Ordered [{heading, body}] blocks beyond the eight fixed sections. heading is plain text; body is rich-text HTML. |
user_confirmed | boolean | Yes | Must be true to create |
Creating its calendar in the same call
Include recurring_schedule when the activity has repeating start times. The activity and calendar
save together; invalid dates or a calendar failure leave neither saved. repeats_yearly needs an
end date. Days use full lowercase names, such as monday; omit the list for every day.
{
"name": "Example class",
"price_structure": "group",
"price": 220,
"max_participants": 4,
"duration_value": 2,
"duration_unit": "Hours",
"is_private": true,
"default_capacity": 1,
"recurring_schedule": {
"times": ["09:00", "13:00"],
"date_from": "2026-12-01",
"date_to": "2027-04-30",
"repeats_yearly": true
},
"user_confirmed": true
}
Equipment chosen with a price
create_experience, update_experience and sync_experience_equipment accept the same
equipment rows. Use an owned product_id; units_basis is booking, participant,
session or unit, and units_per defaults to 1.
A row with rate_category_id or rate_category_label reserves that item only for the chosen
price. Use the exact participant price label when creating the activity and its prices in one
call. Repeat an item in separate rows if several prices use it. Omit both price fields for gear
used by everyone. Each item can appear once per price, and cannot be both common and price-specific.
Prices and products from other shops are refused. Send the full replacement gear list.
Guide requirements
Two lists say what a guide should bring to run the experience: required_certifications and
required_languages. They are the same lists the shop sets under Guide requirements on the
experience, and update_experience takes both as well.
Both are warn-only. Assigning a guide who is missing one flags it on the departure so the shop
can see it; it never stops the assignment, and it never stops a customer booking. Sending either
field replaces that list outright, so send the whole set. Send [] to clear one.
required_certifications takes any of:
first_aid (First Aid), cpr (CPR), wilderness_first_aid (Wilderness First Aid),
wilderness_first_responder (Wilderness First Responder), lifeguard (Lifeguard),
swiftwater_rescue (Swiftwater Rescue), avalanche_safety (Avalanche Safety),
dive_certification (Dive Certification), drivers_license (Driver's License),
boat_license (Boat License), food_handling (Food Handling), uscg_master (USCG Master),
uscg_oupv (USCG OUPV), uscg_ab (USCG AB), uscg_offshore (USCG Offshore Endorsement),
uscg_towing (USCG Towing Endorsement), specialty (Specialty Endorsement), other (Other).
required_languages takes any two-letter code from:
ar (Arabic), cs (Czech), da (Danish), nl (Dutch), en (English), tl (Filipino),
fi (Finnish), fr (French), de (German), el (Greek), he (Hebrew), hi (Hindi),
hu (Hungarian), id (Indonesian), it (Italian), ja (Japanese), ko (Korean), ms (Malay),
zh (Mandarin Chinese), no (Norwegian), pl (Polish), pt (Portuguese), ro (Romanian),
ru (Russian), es (Spanish), sv (Swedish), th (Thai), tr (Turkish), uk (Ukrainian),
vi (Vietnamese).
The name the shop reads on screen is accepted too, so "First Aid" and "Spanish" land the same
rows as first_aid and es. Anything outside those lists is refused, and the refusal names what
can be sent. get_experience returns both lists under guide_requirements, alongside
required_certification_names and required_language_names, which carry the same entries in the
words the shop reads.
{
"required_certifications": ["first_aid", "boat_license"],
"required_languages": ["es"]
}
Example: Group Pricing
{
"name": "Sunset Kayak Tour",
"price_structure": "group",
"price": 120,
"max_participants": 6,
"duration_value": 2,
"user_confirmed": true
}
Example: Participant Pricing
{
"name": "Guided Mountain Hike",
"price_structure": "participant",
"participant_rates": [
{"rate_category_id": 1, "price": 45},
{"rate_category_id": 2, "price": 25}
],
"duration_value": 3,
"user_confirmed": true
}
bulk_change_session_duration
Change the duration of selected timed sessions without moving their starts. The first call previews
the change. Send the same fields with user_confirmed: true to apply it. Date-only sessions are left
unchanged, and the experience default and repeating schedule do not change.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
session_ids | array of integers | Yes | Sessions to change |
duration_value | number | Yes | A number greater than zero |
duration_unit | string | Yes | Minutes, Hours, or Days |
user_confirmed | boolean | No | Set to true after checking the preview |
list_experience_guides
List guides currently assigned to an experience availability slot.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
experience_availability_id | integer | Yes | The experience availability slot ID |
Response Fields
Returns a guides array. Each entry includes id, staff_id, and name.
get_available_guides_for_slot
Return a grouped availability picker for an experience slot: which guides are available, partially available (have a shift but a scheduling warning), or blocked (time-off or double-booked).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
experience_availability_id | integer | Yes | The experience availability slot ID |
Response Fields
Returns three groups: available (free to assign), warned (have a shift covering the time but with a caveat), and blocked (time-off or already assigned elsewhere). Each entry includes staff_id, name, and where applicable a reason or warnings array.
assign_guides_to_experience
Assign one or more guides to an experience availability slot. Returns per-staff assignment outcomes including any warnings (e.g., no covering shift).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
experience_availability_id | integer | Yes | The experience availability slot ID |
staff_ids | array of integers | Yes | Staff IDs to assign as guides |
Response Fields
Returns success, assigned (array of successfully assigned staff IDs), blocked (array of {staff_id, reason} for rejected assignments), and warned (array of {staff_id, warnings} for assignments accepted with cautions).
remove_guide_from_experience
Remove a guide from an experience availability slot.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
experience_availability_id | integer | Yes | The experience availability slot ID |
staff_id | integer | Yes | The staff (guide) ID to remove |
Response Fields
Returns success: true on removal, or an error if the assignment was not found.
Related
- Experiences REST API - REST API endpoints for experiences
- Guides REST API - Guide assignment REST endpoints
- Schedule Tools - Understaffing warnings and booking demand
- Staff Tools - Staff member and shift management
- Categories Tools - Experience category management
- Bookings Tools - Create experience bookings