Skip to navigation

Group bookings

View as Markdown

A group Reservation contains 1–12 allocations, totals at most 50 golfers, and belongs to exactly one Inventory Course and one course-local date. Each allocation quantity is 1–5, never more than the tee time’s max_players (its capacity, set from the course’s max_players_per_tee_time when the tee time was created: 4 by default, 5 when the course allows it), and must equal the party size embedded in its offer. The top-level guest occupies one spot in the earliest Tee Time allocation after canonical time ordering. Optional allocation players contain only known companions; do not repeat the primary guest, and omit unnamed golfers.

Collect guest details first. Then search availability for each intended party, assemble offers only when the guest is ready to confirm, and submit all allocations once. If any offer has less than 30 seconds remaining, refresh the complete selection so the group shares a safe confirmation window:

Two-allocation group request
{
"external_reference_id": "group-2026-0815",
"guest": {
"first_name": "Avery",
"last_name": "Jordan",
"email": "avery@example.com"
},
"allocations": [
{
"offer_id": "off_group_first",
"quantity": 4,
"players": [
{ "first_name": "Morgan", "last_name": "Lee" },
{ "first_name": "Sam", "last_name": "Patel" },
{ "first_name": "Riley", "last_name": "Chen" }
]
},
{
"offer_id": "off_group_second",
"quantity": 4,
"players": [
{ "first_name": "Taylor", "last_name": "Kim" },
{ "first_name": "Jamie", "last_name": "Diaz" },
{ "first_name": "Casey", "last_name": "Brown" },
{ "first_name": "Alex", "last_name": "Nguyen" }
]
}
]
}
One atomic group Reservation response
{
"data": {
"id": "res_group_example_encrypted",
"status": "confirmed",
"course_id": "crs_example_encrypted",
"external_reference_id": "group-2026-0815",
"guest": {
"first_name": "Avery",
"last_name": "Jordan",
"email": "avery@example.com",
"phone": null
},
"allocations": [
{
"tee_time_id": "ttm_group_first",
"quantity": 4,
"time": {
"starts_at": "2026-08-15T14:10:00.000Z",
"local_date": "2026-08-15",
"local_time": "08:10",
"timezone": "America/Denver"
},
"selections": { "holes": 18, "cart": "riding" },
"pricing": {
"green_fee": { "amount_minor": 8500, "currency": "USD" },
"cart_fee": { "amount_minor": 1800, "currency": "USD" },
"total_per_golfer": { "amount_minor": 10300, "currency": "USD" }
},
"known_companions": [
{ "first_name": "Morgan", "last_name": "Lee" },
{ "first_name": "Sam", "last_name": "Patel" },
{ "first_name": "Riley", "last_name": "Chen" }
]
},
{
"tee_time_id": "ttm_group_second",
"quantity": 4,
"time": {
"starts_at": "2026-08-15T14:20:00.000Z",
"local_date": "2026-08-15",
"local_time": "08:20",
"timezone": "America/Denver"
},
"selections": { "holes": 18, "cart": "riding" },
"pricing": {
"green_fee": { "amount_minor": 8500, "currency": "USD" },
"cart_fee": { "amount_minor": 1800, "currency": "USD" },
"total_per_golfer": { "amount_minor": 10300, "currency": "USD" }
},
"known_companions": [
{ "first_name": "Taylor", "last_name": "Kim" },
{ "first_name": "Jamie", "last_name": "Diaz" },
{ "first_name": "Casey", "last_name": "Brown" },
{ "first_name": "Alex", "last_name": "Nguyen" }
]
}
],
"golfer_count": 8,
"payment": {
"method": "pay_at_course",
"amount_due_now_minor": 0,
"currency": "USD"
},
"cancellation_policy": {
"window_hours": 24,
"fee": { "amount_minor": 2500, "currency": "USD" },
"policy_fingerprint": "policy_2026_07"
},
"cancellation_eligibility": {
"allowed": true,
"code": "allowed",
"message": "This Reservation may be cancelled through the API.",
"contact_course": false
},
"integration_attribution": {
"organization_name": "Example Travel",
"source": "public_api"
},
"created_at": "2026-07-29T14:01:00.000Z",
"updated_at": "2026-07-29T14:01:00.000Z",
"cancelled_at": null,
"messaging": {
"owner": "integration",
"trutee_confirmation_suppressed": true,
"trutee_cancellation_suppressed": true,
"course_name": "Pine Ridge Golf Club",
"guest_name": "Avery Jordan",
"allocations": [
{
"time": {
"starts_at": "2026-08-15T14:10:00.000Z",
"local_date": "2026-08-15",
"local_time": "08:10",
"timezone": "America/Denver"
},
"quantity": 4,
"selections": { "holes": 18, "cart": "riding" }
},
{
"time": {
"starts_at": "2026-08-15T14:20:00.000Z",
"local_date": "2026-08-15",
"local_time": "08:20",
"timezone": "America/Denver"
},
"quantity": 4,
"selections": { "holes": 18, "cart": "riding" }
}
]
}
},
"meta": {
"request_id": "req_group_example"
}
}

The server revalidates principal access, offer expiry, course identity, capacity, guest eligibility, pricing, and policy. Any failure aborts every write. Never loop over allocations with separate Reservation calls when the guest expects one group.

Offers cannot cross Inventory Courses or course-local dates. The response returns allocations in canonical start order, not request order. golfer_count is the sum of allocation quantities.

Optional players names become known_companions; the top-level guest remains the primary customer identity and is not repeated in known_companions. The earliest allocation may therefore contain at most quantity - 1 named companions; later allocations may contain up to quantity.

There are no Reservation Holds in v1. If one offer expires, search again and submit a new logical booking with a new idempotency key. Do not reuse a failed request’s key with changed offers.