Bookings API

Create and manage tee time bookings via API.

Endpoints

Method	Endpoint	Description
POST	/bookings	Create a booking
GET	/bookings/{id}	Get booking details
PUT	/bookings/{id}	Update a booking
DELETE	/bookings/{id}	Cancel a booking
GET	/players/me/bookings	List user's bookings

Create Booking

Request

POST /bookings
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "courseId": "championship-course",
  "teeTime": "2025-01-15T08:00:00Z",
  "players": 4,
  "playerDetails": [
    {
      "name": "John Smith",
      "email": "john@example.com",
      "phone": "+27821234567"
    }
  ],
  "options": {
    "cart": true,
    "caddy": false
  }
}

Response

{
  "data": {
    "id": "bk_abc123",
    "status": "CONFIRMED",
    "courseId": "championship-course",
    "teeTime": "2025-01-15T08:00:00Z",
    "players": 4,
    "totalAmount": 1800,
    "currency": "ZAR",
    "reference": "BK-2025-12345",
    "createdAt": "2025-01-10T14:30:00Z"
  }
}

Get Booking

Request

GET /bookings/bk_abc123
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": {
    "id": "bk_abc123",
    "status": "CONFIRMED",
    "courseId": "championship-course",
    "courseName": "Championship Course",
    "teeTime": "2025-01-15T08:00:00Z",
    "players": 4,
    "playerDetails": [
      {
        "name": "John Smith",
        "email": "john@example.com",
        "isOwner": true
      }
    ],
    "pricing": {
      "greenFee": 1600,
      "cartHire": 200,
      "total": 1800,
      "currency": "ZAR"
    },
    "reference": "BK-2025-12345",
    "checkInCode": "QR_DATA_HERE",
    "createdAt": "2025-01-10T14:30:00Z"
  }
}

Update Booking

Request

PUT /bookings/bk_abc123
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "players": 3,
  "playerDetails": [
    { "name": "John Smith", "email": "john@example.com" },
    { "name": "Jane Doe", "email": "jane@example.com" },
    { "name": "Bob Wilson", "email": "bob@example.com" }
  ]
}

Response

{
  "data": {
    "id": "bk_abc123",
    "status": "CONFIRMED",
    "players": 3,
    "priceDifference": -450,
    "refundAmount": 450,
    "updatedAt": "2025-01-11T10:00:00Z"
  }
}

Cancel Booking

Request

DELETE /bookings/bk_abc123
Authorization: Bearer YOUR_TOKEN

Response

{
  "data": {
    "id": "bk_abc123",
    "status": "CANCELLED",
    "refundAmount": 1800,
    "refundStatus": "PENDING",
    "cancelledAt": "2025-01-11T10:00:00Z"
  }
}

List User Bookings

Request

GET /players/me/bookings?status=CONFIRMED&from=2025-01-01
Authorization: Bearer YOUR_TOKEN

Query Parameters

Parameter	Type	Description
status	string	Filter by status
from	date	Start date
to	date	End date
limit	number	Results per page
offset	number	Pagination offset

Response

{
  "data": [
    {
      "id": "bk_abc123",
      "courseName": "Championship Course",
      "teeTime": "2025-01-15T08:00:00Z",
      "players": 4,
      "status": "CONFIRMED"
    }
  ],
  "meta": {
    "total": 5,
    "limit": 10,
    "offset": 0
  }
}

Booking Status

Status	Description
PENDING	Awaiting payment
CONFIRMED	Booking confirmed
CHECKED_IN	Player has arrived
COMPLETED	Round finished
CANCELLED	Booking cancelled
NO_SHOW	Player didn't arrive

Error Codes

Code	Description
SLOT_UNAVAILABLE	Tee time no longer available
INVALID_PLAYERS	Player count invalid
PAYMENT_FAILED	Payment not processed
PAST_CANCELLATION	Cannot cancel this close to tee time
BOOKING_NOT_FOUND	Booking ID not found

Webhooks

Subscribe to booking events:

{
  "event": "booking.confirmed",
  "data": {
    "bookingId": "bk_abc123",
    "courseId": "championship-course",
    "teeTime": "2025-01-15T08:00:00Z"
  },
  "timestamp": "2025-01-10T14:30:00Z"
}

Available events:

• booking.confirmed
• booking.modified
• booking.cancelled
• booking.checked_in