Bookings API

The Bookings API allows authenticated users to create, view, and manage their bookings.

Authentication Required: All endpoints require token authentication.

List Bookings

Retrieve all bookings for the authenticated user.

Request:

GET /api/v1/bookings/

Headers:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Response:

[
    {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "reference_code": "BK-250115-A7F3",
        "resource": 1,
        "resource_name": "Court 1",
        "venue_name": "Sports Center Munich",
        "venue_address": "Sportstrasse 1, 80000 Munich",
        "start_datetime": "2025-01-15T10:00:00+01:00",
        "end_datetime": "2025-01-15T11:00:00+01:00",
        "duration_minutes": 60,
        "participant_count": 2,
        "price_per_unit": "25.00",
        "pricing_unit": "hour",
        "total_price": "25.00",
        "currency": "EUR",
        "status": "pending",
        "can_cancel": true,
        "is_upcoming": true,
        "notes": "",
        "confirmed_at": null,
        "paid_at": null,
        "cancelled_at": null,
        "created_at": "2025-01-10T12:00:00Z",
        "updated_at": "2025-01-10T12:00:00Z"
    }
]

Get Booking Details

Retrieve detailed information about a specific booking.

Request:

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

Response:

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "reference_code": "BK-250115-A7F3",
    "resource": {
        "id": 1,
        "name": "Court 1",
        "venue_name": "Sports Center Munich",
        "venue_slug": "sports-center-munich"
    },
    "resource_name": "Court 1",
    "venue_name": "Sports Center Munich",
    "venue_address": "Sportstrasse 1, 80000 Munich",
    "start_datetime": "2025-01-15T10:00:00+01:00",
    "end_datetime": "2025-01-15T11:00:00+01:00",
    "duration_minutes": 60,
    "participant_count": 2,
    "price_per_unit": "25.00",
    "pricing_unit": "hour",
    "total_price": "25.00",
    "currency": "EUR",
    "status": "pending",
    "can_cancel": true,
    "is_upcoming": true,
    "notes": "",
    "confirmed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "created_at": "2025-01-10T12:00:00Z",
    "updated_at": "2025-01-10T12:00:00Z",
    "payment": null,
    "client": null
}

Get Upcoming Bookings

Retrieve only upcoming bookings for the authenticated user.

Request:

GET /api/v1/bookings/upcoming/

Response: Same format as List Bookings, filtered to future bookings only.

Create Booking

Create a new booking with status pending. The booking must be paid to be confirmed.

Request:

POST /api/v1/bookings/

Headers:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
Content-Type: application/json

Parameters:

Name	Type	Required	Description
resource	integer	Yes	Resource ID to book
start_datetime	string	Yes	Start time in ISO 8601 format
end_datetime	string	Yes	End time in ISO 8601 format
participant_count	integer	No	Number of participants (default: 1)
notes	string	No	Optional booking notes

Example:

curl -X POST http://127.0.0.1:8000/api/v1/bookings/ \
  -H "Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": 1,
    "start_datetime": "2025-01-15T10:00:00+01:00",
    "end_datetime": "2025-01-15T11:00:00+01:00",
    "participant_count": 2
  }'

Response 201 Created:

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "reference_code": "BK-250115-A7F3",
    "resource": 1,
    "resource_name": "Court 1",
    "venue_name": "Sports Center Munich",
    "venue_address": "Sportstrasse 1, 80000 Munich",
    "start_datetime": "2025-01-15T10:00:00+01:00",
    "end_datetime": "2025-01-15T11:00:00+01:00",
    "duration_minutes": 60,
    "participant_count": 2,
    "price_per_unit": "25.00",
    "pricing_unit": "hour",
    "total_price": "25.00",
    "currency": "EUR",
    "status": "pending",
    "can_cancel": true,
    "is_upcoming": true,
    "notes": "",
    "confirmed_at": null,
    "paid_at": null,
    "cancelled_at": null,
    "created_at": "2025-01-10T12:00:00Z",
    "updated_at": "2025-01-10T12:00:00Z"
}

Error Responses:

• 400 Bad Request - Validation error (slot not available, invalid times, etc.)
• 401 Unauthorized - Missing or invalid authentication token

Create Payment Intent

Create a Stripe PaymentIntent for a pending booking. Returns the client_secret needed for Stripe.js to complete the payment on the frontend.

Request:

POST /api/v1/bookings/{id}/create-payment-intent/

Headers:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Response:

{
    "client_secret": "pi_3ABC123_secret_XYZ789",
    "payment_intent_id": "pi_3ABC123",
    "amount": "25.00",
    "currency": "EUR"
}

Error Responses:

• 400 Bad Request - Booking already paid or invalid status
• 403 Forbidden - User does not own this booking
• 500 Internal Server Error - Stripe API error

Cancel Booking

Cancel an existing booking. Only bookings that are cancellable can be cancelled.

Request:

POST /api/v1/bookings/{id}/cancel/

Headers:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
Content-Type: application/json

Parameters:

Name	Type	Required	Description
reason	string	No	Cancellation reason: user_request, weather, other (default: user_request)
notes	string	No	Additional notes

Example:

curl -X POST http://127.0.0.1:8000/api/v1/bookings/550e8400-e29b-41d4-a716-446655440000/cancel/ \
  -H "Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "user_request",
    "notes": "Schedule conflict"
  }'

Response:

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "reference_code": "BK-250115-A7F3",
    "status": "cancelled",
    "cancelled_at": "2025-01-10T14:00:00Z"
}

Error Responses:

• 400 Bad Request - Booking cannot be cancelled
• 403 Forbidden - User does not own this booking

Booking Statuses

Status	Description
pending	Booking created, awaiting payment
confirmed	Booking confirmed (may be pre-paid by venue agreement)
paid	Payment received successfully
cancelled	Cancelled by user or system
completed	Booking time has passed
no_show	User did not show up
refunded	Payment was refunded