> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trutee.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trutee.app/_mcp/server.

# Group bookings

> Book multiple Tee Times as one atomic Reservation.

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:

```json title={"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" }
      ]
    }
  ]
}

```

```json title={"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.