The GOVIGO API uses API key authentication. Include the X-API-Key header in every request.

GET /api/golf-clubs/plans.php?golf_club_id=1 HTTP/1.1
Host: govigolf.com
X-API-Key: YOUR_API_KEY

Available scopes:

All API responses are returned in the following common format.

{
  "success": true,
  "data": { ... },
  "message": "",
  "http_code": 200
}

A reservation can be referenced by two keys.

Checks the API key validity, owner, granted scopes and rate limit. Use it for initial connectivity testing (no scope required).

{
  "success": true,
  "data": {
    "authenticated": true,
    "owner": { "type": "partner", "id": 3, "name": "Partner A" },
    "key_prefix": "a1b2c3d4",
    "scopes": ["golf_clubs:read", "tee_times:read", "reservations:read", "reservations:write"],
    "rate_limit": 120,
    "expires_at": null,
    "server_time": "2026-06-01T10:00:00+07:00"
  },
  "message": "pong",
  "http_code": 200
}

Retrieves golf club details. Omit id to get a list.

{
  "success": true,
  "data": {
    "lang": "en",
    "count": 1,
    "golf_clubs": [
      {
        "id": 1,
        "name": "Sample Golf Club",
        "area": "Central (Da Nang / Hue)",
        "area_code": 3,
        "country": 0,
        "address": "Xa Loc Vinh, Phu Loc, Hue, Viet Nam",
        "google_map": "https://maps.google.com/...",
        "latitude": 16.3312358,
        "longitude": 107.9558334,
        "phone": "+842343695880",
        "opening_hours": "05:30-18:00",
        "description": "Located about an hour's drive from Da Nang ...",
        "access": null,
        "courses": [
          { "name": "Lagoon Course", "holes": 18, "par": 71, "length_yards": 7101, "designer": "Sir Nick Faldo" }
        ],
        "course_info": "18 holes, Par 71 / 7,101 yards",
        "remark": "Located about an hour's drive from Da Nang ...",
        "opened_on": "2013-03-01",
        "dress_code": "Collared shirts required ...",
        "cancel_policy": "Free cancellation up to 9 days before tee time ...",
        "main_image": {
          "url": "https://govigolf.com/images/golf_club_top_picture/xxx.jpg",
          "thumbnail_url": "https://govigolf.com/images/golf_club_picture/thumb/xxx.jpg"
        },
        "images": [
          { "url": "https://govigolf.com/images/golf_club_picture/yyy.jpg",
            "thumbnail_url": "https://govigolf.com/api/golf-clubs/thumbnail.php?src=..." }
        ],
        "facilities": {
          "driving_range": { "available": true,  "note": null },
          "pro_shop":      { "available": true,  "note": null },
          "restaurant":    { "available": true,  "note": null },
          "lesson":        { "available": false, "note": null },
          "night_golf":    { "available": false },
          "note": null
        },
        "updated_at": "2026-08-18T09:30:40Z",
        "rental": {
          "club_available": true,
          "club_fee": 300000,
          "shoes_available": false,
          "shoes_fee": null
        },
        "options": {
          "rental_cart":      { "available": true,  "included": true,  "fee": null },
          "rental_umbrella":  { "available": false, "included": false, "fee": null },
          "caddy":            { "available": true,  "included": true,  "fee": null },
          "caddy_designate":  { "available": true,  "included": false, "fee": 200000 },
          "caddybag_storage": { "available": false, "included": false, "fee": null },
          "sent_caddybag":    { "available": false, "included": false, "fee": null },
          "accompany":        { "available": false, "included": false, "fee": null },
          "pickup":           { "available": false, "description": null }
        }
      }
    ]
  },
  "message": "Golf club information retrieved.",
  "http_code": 200
}

Gets the golf club plan list. The id obtained here is the golf_plan_id (required) used when booking.

{
  "success": true,
  "data": {
    "golf_club_id": 1,
    "lang": "ja",
    "count": 1,
    "plans": [
      {
        "id": 10,
        "source": "golf_plan",
        "name": "Weekday Plan",
        "day_type": "weekday",
        "price_local": 1500000,
        "price_inbound": 2000000,
        "partner_price_local": 1450000,
        "partner_price_inbound": 1850000,
        "apply_period": { "from": "2026-01-01", "to": "2026-12-31" },
        "time_ranges": [{ "from": "06:00", "to": "10:00" }],
        "minimum_players": 1,
        "summary": "Great value weekday-only plan",
        "cancel_policy": "Free cancellation up to 3 days before",
        "rental_club_fee": 300000,
        "rental_shoes_fee": 100000
      }
    ]
  },
  "message": "",
  "http_code": 200
}

Gets available tee-time slots for the given date. To use a tee-time slot, pass tee_time_slot_id when booking (optional).

{
  "success": true,
  "data": {
    "golf_club_id": 1,
    "date": "2026-03-15",
    "lang": "en",
    "is_closed": false,
    "count": 1,
    "slots": [
      {
        "slot_id": 101,
        "course_id": 3,
        "course_name": "Lake Course",
        "tee_date": "2026-03-15",
        "tee_time": "07:00",
        "total_slots": 4,
        "available_slots": 2,
        "allow_join": true,
        "plan": { "id": 10, "name": "Weekday Plan", "price": 1500000 }
      }
    ]
  },
  "message": "",
  "http_code": 200
}

Gets the daily minimum price for the given month (for calendar display).

{
  "success": true,
  "data": {
    "golf_club_id": 1,
    "year": 2026,
    "month": 3,
    "prices": {
      "2026-03-01": 1500000,
      "2026-03-02": 1800000
    }
  },
  "message": "",
  "http_code": 200
}

Gets the final amount before creating a reservation. The create API recalculates with the same logic, so it matches this quote. Amounts returned are partner prices (regular price minus the partner discount).

{
  "success": true,
  "data": {
    "plan_id": 10,
    "plan_name": "Weekday Plan",
    "time_ranges": [{ "from": "06:00", "to": "10:00" }],
    "players": {
      "local":   { "count": 2, "regular_unit_price": 1500000, "discount_per_player": 50000, "unit_price": 1450000, "amount": 2900000 },
      "inbound": { "count": 2, "regular_unit_price": 2000000, "discount_per_player": 150000, "unit_price": 1850000, "amount": 3700000 }
    },
    "player_count": 4,
    "minimum_players": 1,
    "base_amount": 6600000,
    "rental": {
      "club_count": 2, "club_fee": 600000,
      "shoes_count": 0, "shoes_fee": 0,
      "subtotal": 600000
    },
    "currency": "VND",
    "total_amount": 7200000,
    "golf_club_id": 1
  },
  "message": "Quote calculated.",
  "http_code": 200
}

Creates a new reservation. The request body is JSON. The amount (total_amount) is recalculated on the server from golf_plan_id, so it need not be specified in the request.

POST /api/reservations/create.php HTTP/1.1
Host: govigolf.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "golf_club_id": 1,
  "golf_plan_id": 10,
  "tee_date": "2026-03-15",
  "customer_name": "Taro Tanaka",
  "customer_email": "tanaka@example.com",
  "customer_phone": "090-1234-5678",
  "players": { "local": 2, "inbound": 2 },
  "options": { "rental_club": 2 },
  "external_ref": "EXT-2026-00500"
}

{
  "success": true,
  "data": {
    "reservation_id": 500,
    "status": 1,
    "golf_club_id": 1,
    "tee_date": "2026-03-15",
    "tee_time": "08:00",
    "player_count": 4,
    "players": { "local": 2, "inbound": 2 },
    "total_amount": 7200000,
    "source": "api_partner"
  },
  "message": "Reservation created successfully.",
  "http_code": 201
}

Gets the reservation list (only reservations you created). Supports pagination.

{
  "success": true,
  "data": {
    "reservations": [
      {
        "id": 500,
        "golf_club_id": 1,
        "golf_club_name": "Sample Golf Club",
        "customer_name": "Taro Tanaka",
        "tee_date": "2026-03-15",
        "tee_time": "08:00",
        "player_count": 4,
        "players": { "local": 2, "inbound": 2 },
        "total_amount": 7200000,
        "status": "1.requested",
        "status_code": 1,
        "source": "api_partner",
        "external_ref": "EXT-2026-00500",
        "created_at": "2026-03-01 10:00:00"
      }
    ],
    "pagination": {
      "page": 1, "per_page": 20, "total_count": 1,
      "total_pages": 1, "has_next": false, "has_prev": false
    }
  },
  "message": "",
  "http_code": 200
}

Gets reservation details. Specify either id or external_ref.

{
  "success": true,
  "data": {
    "reservation": {
      "id": 500,
      "golf_club_id": 1,
      "golf_club_name": "Sample Golf Club",
      "plan_id": 10,
      "plan_name": "Weekday Plan",
      "customer_name": "Taro Tanaka",
      "customer_email": "tanaka@example.com",
      "customer_phone": "090-1234-5678",
      "tee_date": "2026-03-15",
      "tee_time": "08:00",
      "player_count": 4,
      "players": { "local": 2, "inbound": 2 },
      "total_amount": 7200000,
      "remark": null,
      "options": { "rental_club": 2, "rental_shoes": 0 },
      "status": "1.requested",
      "status_code": 1,
      "source": "api_partner",
      "external_ref": "EXT-2026-00500",
      "created_at": "2026-03-01 10:00:00",
      "updated_at": "2026-03-01 10:00:00",
      "attendees": [
        { "name": "Hanako Sato", "email": null, "phone": null }
      ]
    }
  },
  "message": "",
  "http_code": 200
}

Updates the reservation. Only the specified fields are updated. If players / options change, total_amount is recalculated on the server. players follows the same interpretation as reservation creation: omitted types are treated as 0 players (always specify counts for all types). For real-time bookings, changing the total number of players also adjusts the golf course inventory. Cancelled (status=6-8) / completed (status=9,10) reservations cannot be updated.

POST /api/reservations/update.php HTTP/1.1
Host: govigolf.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "external_ref": "EXT-2026-00500",
  "players": { "local": 2, "inbound": 1 },
  "remark": "1 person cancelled"
}

{
  "success": true,
  "data": {
    "reservation_id": 500,
    "golf_club_id": 1,
    "plan_id": 10,
    "player_count": 3,
    "players": { "local": 2, "inbound": 1 },
    "total_amount": 5350000,
    "status": "1.requested",
    "status_code": 1,
    "external_ref": "EXT-2026-00500",
    "updated_at": "2026-03-02 09:00:00"
  },
  "message": "Reservation updated.",
  "http_code": 200
}

Cancels the reservation. Specify reservation_id or external_ref. Like member bookings, it is accepted as a cancellation request (status=6) and finalized by staff. Real-time slot inventory is restored when the cancellation is finalized (not at request time). Reservations already cancelling (status=6-8) / completed (status=9,10) cannot be cancelled.

POST /api/reservations/cancel.php HTTP/1.1
Host: govigolf.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "external_ref": "EXT-2026-00500",
  "reason": "Due to schedule change"
}

{
  "success": true,
  "data": {
    "reservation_id": 500,
    "status": "cancel_requested",
    "status_code": 6,
    "cancelled_at": "2026-03-02T10:00:00+07:00"
  },
  "message": "Reservation cancelled successfully.",
  "http_code": 200
}

Registers a Webhook receiving URL. Delivery scope is automatically limited to reservations you created.

POST /api/webhooks/subscribe.php HTTP/1.1
Host: govigolf.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://your-system.com/webhook/govigo",
  "events": ["reservation.created", "reservation.status_changed", "reservation.cancelled"]
}

{
  "success": true,
  "data": {
    "subscription_id": 10,
    "url": "https://your-system.com/webhook/govigo",
    "events": ["reservation.created", "reservation.status_changed", "reservation.cancelled"],
    "secret": "a1b2c3d4e5f6..."
  },
  "message": "",
  "http_code": 201
}

Gets the list of registered Webhooks (no parameters).

{
  "success": true,
  "data": {
    "count": 1,
    "subscriptions": [
      {
        "id": 10,
        "url": "https://your-system.com/webhook/govigo",
        "events": ["reservation.created", "reservation.status_changed"],
        "is_active": true,
        "created_at": "2026-03-01 10:00:00",
        "updated_at": "2026-03-01 10:00:00"
      }
    ]
  },
  "message": "",
  "http_code": 200
}

Unsubscribes a registered Webhook.

POST /api/webhooks/unsubscribe.php HTTP/1.1
Host: govigolf.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "subscription_id": 10 }

Sends a test notification to a registered Webhook to verify URL connectivity and signature verification.

POST /api/webhooks/test.php HTTP/1.1
Host: govigolf.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{ "subscription_id": 10 }