API Documentation v2.0

Build with Book & Go

A powerful, secure REST API for integrating court booking data, payments, and live events into your automation systems.

Get Started View Authentication

Authentication

All API endpoints (except login) require JWT authentication. Tokens are designed for long-term automation, valid for 10 years.

Base URL: https://docsapi.bookandgo.app/api

Bearer Token

Include your JWT token in the Authorization header of every request.

HTTP Header 
Authorization: Bearer YOUR_JWT_TOKEN

Rate Limiting

To ensure system stability, API endpoints have rate limits based on their database load. Limits are applied per JWT token.

Endpoint Limit Period
/locations 60 requests per minute
/bookings 60 requests per minute
/payments/summary 30 requests per minute
/payments/transactions 10 requests per minute
/pos/transactions 10 requests per minute
/events/live 30 requests per minute
/events/history 10 requests per minute
/coaches 10 requests per minute
/wallet 10 requests per minute
Exceeding the limit returns a 429 Too Many Requests status code.

Login

POST /login

Authenticate with email and password to receive a long-lived JWT token.

Request Body

JSON 
{
  "email": "[email protected]",
  "password": "your-password"
}

Response

JSON 
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "club_id": 1,
  "club_name": "Your Club Name",
  "user_name": "Admin User",
  "expires_at": 2073037187
}

Locations

GET /locations

Retrieve all locations for your club. Use this to get location IDs required by other endpoints.

Tip: Call this endpoint first to get valid location IDs for filtering bookings, transactions, and events.

Example Request

BASH 
curl -X GET "https://docsapi.bookandgo.app/api/locations" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Fields

Field Type Description
id integer Unique location identifier (use this for location_id parameter)
location_name string Display name of the location
currency string Currency code (e.g., IDR, SGD)

Bookings

GET /bookings

Retrieve court bookings for your club within a date range.

Query Parameters

Parameter Type Required Description
start_date string No Start date (YYYY-MM-DD)
end_date string No End date (YYYY-MM-DD)
location_id integer No Filter by location

Example Request

BASH 
curl -X GET "https://docsapi.bookandgo.app/api/bookings?start_date=2024-03-01&end_date=2024-03-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

Payments Summary

GET /payments/summary

Get aggregated payment data including revenue, refunds, and breakdowns by payment method.

Maximum date range is 31 days to prevent database throttling.

Query Parameters

Parameter Type Required Description
start_date string No Start date in YYYY-MM-DD format (defaults to today)
end_date string No End date in YYYY-MM-DD format (defaults to today)
location_id integer No Filter by location ID
Note: All dates are interpreted in Asia/Singapore timezone. If both dates are omitted, defaults to today's data only.

Example Request

BASH 
curl -X GET "https://docsapi.bookandgo.app/api/payments/summary?start_date=2024-03-01&end_date=2024-03-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Structure

JSON 
{
  "date_range": {
    "start": "2024-03-01",
    "end": "2024-03-31"
  },
  "summary": {
    "total_revenue": 150000.00,
    "service_payments": 100000.00,
    "pos_payments": 40000.00,
    "refunds": 5000.00
  },
  "by_status": {
    "paid": 145000.00,
    "pending": 2000.00,
    "cancelled": 3000.00
  },
  "by_method": [
    {
      "method": "Credit Card",
      "amount": 50000.00,
      "count": 25
    }
  ]
}

Payment Transactions

GET /payments/transactions

Retrieve detailed payment transaction records with pagination support.

Rate Limited: 10 requests per minute due to heavy database load.

Query Parameters

Parameter Type Required Description
location_id integer Yes Location ID (required for indexing)
start_date string No Start date in YYYY-MM-DD format (defaults to today)
end_date string No End date in YYYY-MM-DD format (defaults to today, max 1 month range)
page integer No Page number (default: 1)
limit integer No Items per page (max 100)
Note: All dates are interpreted in Asia/Singapore timezone. Maximum date range is 31 days.

Example Request

BASH 
curl -X GET "https://docsapi.bookandgo.app/api/payments/transactions?location_id=1&start_date=2024-03-01&end_date=2024-03-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

POS Transactions

GET /pos/transactions

Retrieve detailed Point of Sale product transaction records with pagination support. Covers all POS product sales including rentals.

Rate Limited: 10 requests per minute due to heavy database load.

Query Parameters

Parameter Type Required Description
location_id integer Yes Location ID (required for indexing)
start_date string No Start date in YYYY-MM-DD format (defaults to today)
end_date string No End date in YYYY-MM-DD format (defaults to today, max 1 month range)
page integer No Page number (default: 1)
limit integer No Items per page (max 100, default: 50)
Note: Filtered by created_at (when the sale was made), not by booking date. All dates are interpreted in Asia/Singapore timezone.

Example Request

BASH 
curl -X GET "https://docsapi.bookandgo.app/api/pos/transactions?location_id=87&start_date=2026-04-14&end_date=2026-04-15" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Structure

JSON 
{
  "date_range": { "start": "2026-04-14", "end": "2026-04-15" },
  "club_id": 43,
  "club_name": "Jungle Padel",
  "location_id": 87,
  "location_name": "pererenan",
  "total_count": 1,
  "page": 1,
  "limit": 50,
  "total_pages": 1,
  "transactions": [
    {
      "payment_id": 85740,
      "created_at": "2026-04-15T20:25:19+08:00",
      "updated_at": "2026-04-15T20:25:19+08:00",
      "location_id": 87,
      "location": "pererenan",
      "coupon_name": "",
      "service_booking_id": 799021,
      "user": {
        "name": "John Doe",
        "email": "[email protected]",
        "phone_number": "+628123456"
      },
      "product": {
        "id": 84,
        "name": "Racket Rental",
        "category_id": 65,
        "category_name": "rental racket",
        "quantity": 4
      },
      "rental": {
        "hours": 2,
        "start_time": "2026-04-15T10:00:00+08:00",
        "end_time": "2026-04-15T12:00:00+08:00"
      },
      "payment": {
        "method": "credit card",
        "price": 200000,
        "discount": 0,
        "refund_amount": 0,
        "refund_method": "",
        "total_price": 200000
      },
      "sold_by": "[email protected]"
    }
  ]
}

Response Fields

Field Type Description
product.name string Product name
product.category_name string Product category
product.quantity integer Quantity sold
product.variant_sku string Variant SKU (if applicable)
rental object Only present for rental products (hours, start/end time)
sold_by string Staff email who processed the sale
service_booking_id integer Linked booking ID (if POS sale is tied to a booking)

Live Events

GET /events/live

Retrieve upcoming and current events with participant counts, details, and images.

Response

JSON 
{
  "club_id": 1,
  "club_name": "Example Club",
  "total_count": 5,
  "events": [
    {
      "event_id": 835,
      "event_name": "Morning Americano Tournament",
      "current_participants": 8,
      "maximum_capacity": 12,
      "price": 250000,
      "date": "2025-10-20",
      "location": { "id": 145, "name": "Main Location" }
    }
  ]
}

Historical Events

GET /events/history

Past (and current) events within a date range together with their realised revenue, participants and courts. Complements /events/live (upcoming-only) for month-over-month event revenue reporting. Defaults to the current month; date range is capped at 1 month.

Query Parameters

ParameterTypeDescription
start_datestringYYYY-MM-DD (defaults to first day of current month)
end_datestringYYYY-MM-DD (defaults to today)
location_idintegerOptional filter by location ID

Example Request

BASH 
curl -X GET "https://docsapi.bookandgo.app/api/events/history?start_date=2025-06-01&end_date=2025-06-30" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

JSON 
{
  "club_id": 43,
  "club_name": "Jungle Padel",
  "date_range": { "start": "2025-06-01", "end": "2025-06-30" },
  "total_count": 120,
  "totals": [
    {
      "currency": "IDR",
      "event_count": 120,
      "participants": 960,
      "paid_revenue": 48000000,
      "pending_revenue": 1200000,
      "refunded_amount": 300000
    }
  ],
  "events": [
    {
      "event_id": 204,
      "event_name": "BRONZE AMERICANA",
      "participants": 8,
      "maximum_capacity": 12,
      "price": 240000,
      "date": "2025-06-07",
      "start_time": "08:00:00",
      "end_time": "10:00:00",
      "booking_id": 210909,
      "location": { "id": 91, "name": "kedungu" },
      "courts": "Court 1",
      "currency": "IDR",
      "paid_revenue": 1600000,
      "pending_revenue": 0,
      "refunded_amount": 0
    }
  ]
}

Coach Hours

GET /coaches

Aggregated coaching hours per coach, split by lessons vs events vs bookings. Hours are computed from the actual dated bookings each coach was assigned to (cancelled bookings excluded). Defaults to the current month; date range is capped at 366 days.

Query Parameters

ParameterTypeDescription
start_datestringYYYY-MM-DD (defaults to first day of current month)
end_datestringYYYY-MM-DD (defaults to today)
location_idintegerOptional filter by location ID

Example Request

BASH 
curl -X GET "https://docsapi.bookandgo.app/api/coaches?start_date=2025-06-01&end_date=2025-06-30" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

JSON 
{
  "club_id": 43,
  "club_name": "Jungle Padel",
  "date_range": { "start": "2025-06-01", "end": "2025-06-30" },
  "coach_count": 33,
  "totals": {
    "total_hours": 1329,
    "total_sessions": 1300,
    "lesson_hours": 1299,
    "event_hours": 30,
    "booking_hours": 0
  },
  "coaches": [
    {
      "coach_id": 493,
      "coach_name": "FERRI",
      "email": null,
      "total_hours": 126,
      "total_sessions": 114,
      "lesson_hours": 126,
      "lesson_sessions": 114,
      "event_hours": 0,
      "event_sessions": 0,
      "booking_hours": 0,
      "booking_sessions": 0
    }
  ]
}

Wallet & Credit Liability

GET /wallet

Snapshot of the club's unspent wallet-credit / voucher liability. Returns the outstanding balance grouped by currency and by location, a manual-credit breakdown (vouchers granted vs wallet adjustments), and — when include_customers=true — the paginated per-customer ledger. Only non-expired balances count towards the liability.

Query Parameters

ParameterTypeDescription
include_customersbooleanInclude the per-customer balance ledger (paginated)
currencystringFilter by 3-letter currency code (e.g. IDR)
location_idintegerFilter customer ledger by wallet location ID
min_balancenumberOnly include customers with total balance ≥ this value (default 0.01)
limitintegerMax customers when include_customers=true (default 100, max 500)
offsetintegerOffset for customer ledger pagination (default 0)

Example Request

BASH 
curl -X GET "https://docsapi.bookandgo.app/api/wallet?include_customers=true&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

JSON 
{
  "club_id": 43,
  "club_name": "Jungle Padel",
  "generated_at": "2025-07-01T12:00:00Z",
  "liability": {
    "by_currency": [
      { "currency": "IDR", "total_balance": 1487582753.17, "wallet_count": 2033, "customer_count": 1890 }
    ],
    "by_location": [
      { "location_id": null, "location_name": "Club-wide", "currency": "IDR", "total_balance": 1471028253.17, "wallet_count": 1990 }
    ]
  },
  "manual_credits": [
    { "credit_type": "Vouchers", "currency": "IDR", "count": 841, "total_value": 1421937918 },
    { "credit_type": "Wallets", "currency": "IDR", "count": 854, "total_value": -76090139.41 }
  ],
  "customers": [
    {
      "customer_id": 80495,
      "first_name": "Lina",
      "last_name": "Indriana",
      "email": "[email protected]",
      "currency": "IDR",
      "balance": 14040000,
      "wallet_count": 1
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "count": 50, "has_more": true }
}

Quick Start

1. Get your Token

Authenticate using the Login endpoint to receive your JWT.

2. Find Locations

Call /locations to get the IDs needed for other requests.

3. Make Requests

Use the token in the Authorization header for all other calls.

Example: Get Token

BASH 
curl -X POST https://docsapi.bookandgo.app/api/login \
  -H "Content-Type: application/json" \
  -d '{"email": "your-email", "password": "your-password"}'

Pagination Pattern

Handle paginated responses in the transactions endpoint.

JAVASCRIPT 
async function fetchAllTransactions(locationId) {
  let allTransactions = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `.../payments/transactions?location_id=${locationId}&page=${page}`,
      { headers: { 'Authorization': 'Bearer TOKEN' } }
    );
    const data = await response.json();
    allTransactions = allTransactions.concat(data.transactions);
    hasMore = page < data.total_pages;
    page++;
    
    // Wait to respect rate limits
    await new Promise(r => setTimeout(r, 6000));
  }
  return allTransactions;
}

Error Handling

Code Description Action
200 Success Process the response
400 Bad Request Check your parameters
401 Unauthorized Check your JWT token
429 Too Many Requests Wait and retry