Pickleplus Developer API

Overview

The Pickleplus Tenant API enables businesses to integrate pickleball facility booking, e-commerce, and player management features into their own applications. The API uses a dual-authentication model: an API key identifies your business, and JWT tokens identify individual users.

1

Get Your API Key

Navigate to the Developers section in the admin panel to generate an API key for your business.

2

Set Up Authentication

Include your API key in the X-API-Key header of every request. For user-specific actions, also include a JWT Authorization: Bearer token.

3

Authenticate Users

Use the OTP endpoints to send and verify one-time passwords. A successful verification returns a JWT token for the user.

4

Start Building

Use the tenant endpoints to list facilities, create bookings, manage carts, process orders, and more.

Authentication

The API uses a dual-layer authentication system:

API Key Authentication Required for all requests

Every request must include your business API key in the X-API-Key header. This identifies your business and scopes all data to your facilities.

X-API-Key: pk_a1b2c3d4e5f6...

User JWT Authentication Required for user-specific endpoints

User-specific endpoints (bookings, cart, wallet, etc.) require a JWT token obtained through the OTP login flow. Include it in the Authorization header.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Response Format

All responses follow a consistent format:

{
  "code": 1,       // 1 = success, 0 = error
  "data": { ... }, // Response payload (on success)
  "msg": "..."     // Error message (on failure)
}

User Authentication

Authenticate users with OTP (one-time password) via email or phone.

POST /api/tenant/auth/send-otp API Key Send OTP to user

Request Body

Parameter	Type	Description
identifier	string	Email address or phone number required
identifierType	string	"email" or "phone" required

Response

{ "code": 1, "msg": "OTP sent" }

POST /api/tenant/auth/verify-otp API Key Verify OTP and get JWT token

Request Body

Parameter	Type	Description
identifier	string	Same identifier used to send OTP required
identifierType	string	"email" or "phone" required
code	string	6-digit OTP code required

Response

{
  "code": 1,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 123,
      "email": "player@example.com",
      "fullName": "Jane Doe"
    }
  }
}

User Profile

GET /api/tenant/user/profile API Key JWT Get current user profile

Response

{
  "code": 1,
  "data": {
    "id": 123,
    "email": "player@example.com",
    "fullName": "Jane Doe",
    "phone": "+65 9123 4567",
    "skillLevel": "intermediate",
    "preferredHand": "right"
  }
}

PUT /api/tenant/user/profile API Key JWT Update user profile

Request Body

Parameter	Type	Description
fullName	string	User's full name
phone	string	Phone number
skillLevel	string	beginner, intermediate, advanced, pro
preferredHand	string	left, right

Business & Branding

GET /api/tenant/branding API Key Get business branding configuration

Returns branding settings for your white-label app including colors, logos, and business info.

Response

{
  "code": 1,
  "data": {
    "businessName": "Ace Pickleball Club",
    "brandPrimaryColor": "#7C3AED",
    "brandSecondaryColor": "#A78BFA",
    "logoUrl": "https://...",
    "tagline": "Play. Compete. Connect."
  }
}

Facilities & Availability

GET /api/tenant/facilities API Key List business facilities

Returns all facilities belonging to your business, including courts and operating hours.

Response

{
  "code": 1,
  "data": [
    {
      "id": 1,
      "name": "Main Arena",
      "address": "123 Pickleball Lane",
      "courts": [
        { "id": 1, "name": "Court A", "type": "indoor" }
      ]
    }
  ]
}

GET /api/tenant/availability API Key Check court availability

Query Parameters

Parameter	Type	Description
facilityId	number	Facility ID required
date	string	Date in YYYY-MM-DD format required
courtId	number	Filter by specific court

Response

{
  "code": 1,
  "data": {
    "facility": { "id": 1, "name": "Main Arena" },
    "date": "2025-03-15",
    "slots": [
      {
        "courtId": 1, "courtName": "Court A",
        "time": "09:00", "endTime": "10:00",
        "available": true, "price": "25.00"
      }
    ]
  }
}

Bookings

GET /api/tenant/bookings API Key JWT List user's bookings

Query Parameters

Parameter	Type	Description
status	string	Filter: upcoming, completed, cancelled

GET /api/tenant/bookings/:id API Key JWT Get booking details

URL Parameters

Parameter	Type	Description
id	number	Booking ID required

POST /api/tenant/bookings API Key JWT Create a new booking

Request Body

Parameter	Type	Description
courtId	number	Court to book required
facilityId	number	Facility ID required
date	string	YYYY-MM-DD required
startTime	string	HH:MM format required
endTime	string	HH:MM format required

Note: Payment is deducted from the user's wallet. Gift credit is used first, then cash balance.

POST /api/tenant/bookings/:id/cancel API Key JWT Cancel a booking

Cancels a pending or confirmed booking and refunds the amount to the user's cash wallet balance.

Recurring Bookings

GET /api/tenant/recurring-bookings API Key JWT List recurring bookings

Returns all active recurring bookings for the authenticated user.

POST /api/tenant/recurring-bookings API Key JWT Create recurring booking

Request Body

Parameter	Type	Description
courtId	number	Court ID required
facilityId	number	Facility ID required
dayOfWeek	number	0 (Sun) - 6 (Sat) required
startTime	string	HH:MM required
endTime	string	HH:MM required
startDate	string	Recurrence start date required
endDate	string	Recurrence end date required

Cart & Orders

GET /api/tenant/cart API Key JWT Get cart items

Returns the authenticated user's current cart items with product details.

POST /api/tenant/cart API Key JWT Add item to cart

Request Body

Parameter	Type	Description
productId	number	Product ID required
quantity	number	Quantity (default: 1)

PUT /api/tenant/cart/:id API Key JWT Update cart item quantity

Request Body

Parameter	Type	Description
quantity	number	New quantity required

DELETE /api/tenant/cart/:id API Key JWT Remove cart item

Removes the specified item from the user's cart.

POST /api/tenant/orders/checkout API Key JWT Checkout cart

Request Body

Parameter	Type	Description
facilityId	number	Pickup facility required

Note: Payment is deducted from wallet (gift credit first). A pickup code is generated for order collection at the facility.

GET /api/tenant/orders API Key JWT List user's orders

Returns all orders for the authenticated user, sorted by most recent.

GET /api/tenant/orders/:id API Key JWT Get order details

Returns order details including items, pickup code, and status.

POST /api/tenant/orders/:id/cancel API Key JWT Cancel an order

Cancels a pending order and refunds the amount to the user's wallet.

Wallet

GET /api/tenant/wallet API Key JWT Get wallet balance

Response

{
  "code": 1,
  "data": {
    "cashBalance": "150.00",
    "giftBalance": "25.00"
  }
}

GET /api/tenant/wallet/transactions API Key JWT Get transaction history

Query Parameters

Parameter	Type	Description
limit	number	Results per page (default: 20)
offset	number	Pagination offset

Products & Shop

GET /api/tenant/products API Key List products

Query Parameters

Parameter	Type	Description
facilityId	number	Filter by facility
category	string	Filter by category
search	string	Search by name
sort	string	popular, newest, price_asc, price_desc

GET /api/tenant/products/:id API Key Get product details

Returns full product details including images, pricing, and stock levels.

GET /api/tenant/shop/banners API Key Get promotional banners

Returns active promotional banners for the business.

GET /api/tenant/shop/favorites API Key JWT Get favorited products

Returns the user's list of favorited products.

POST /api/tenant/shop/favorites/:productId API Key JWT Toggle product favorite

Adds or removes a product from the user's favorites (toggle behavior).

Coaches & Lessons

GET /api/tenant/coaches API Key List available coaches

Returns coaches affiliated with your business's facilities.

GET /api/tenant/coaches/:id API Key Get coach details

Returns detailed coach profile including specializations, ratings, and available slots.

POST /api/tenant/coaches/book API Key JWT Book a coaching lesson

Request Body

Parameter	Type	Description
coachId	number	Coach ID required
facilityId	number	Facility ID required
date	string	YYYY-MM-DD required
startTime	string	HH:MM required
endTime	string	HH:MM required
lessonType	string	private, semi_private, group

GET /api/tenant/user/coach-lessons API Key JWT List user's coaching lessons

Returns all coaching lessons for the authenticated user.

POST /api/tenant/coaches/lessons/:id/cancel API Key JWT Cancel a coaching lesson

Cancels a scheduled coaching lesson.

Programmes, Classes & Events

GET /api/tenant/programmes API Key List programmes

Returns programmes offered by your business's facilities.

POST /api/tenant/programmes/:id/enroll API Key JWT Enroll in a programme

Enrolls the user in the specified programme. Payment is deducted from wallet.

GET /api/tenant/classes API Key List group classes

Returns available group classes across your facilities.

POST /api/tenant/classes/:id/enroll API Key JWT Enroll in a class

Enrolls the user in the specified group class.

GET /api/tenant/events API Key List events

Returns upcoming events at your facilities.

POST /api/tenant/events/:id/register API Key JWT Register for an event

Registers the user for the specified event.

Subscriptions

GET /api/tenant/subscriptions/available API Key List available plans

Returns subscription tiers available for your business.

GET /api/tenant/subscriptions/my API Key JWT Get user's subscriptions

Returns the user's active and past subscriptions.

POST /api/tenant/subscriptions/subscribe API Key JWT Subscribe to a plan

Request Body

Parameter	Type	Description
planId	number	Subscription tier ID required

POST /api/tenant/subscriptions/:id/cancel API Key JWT Cancel subscription

Cancels the specified active subscription.

Waitlist

POST /api/tenant/waitlist/join API Key JWT Join a waitlist

Request Body

Parameter	Type	Description
courtId	number	Court ID required
date	string	YYYY-MM-DD required
startTime	string	HH:MM required
endTime	string	HH:MM required

GET /api/tenant/waitlist/my API Key JWT List user's waitlist entries

Returns all active waitlist entries for the user.

DELETE /api/tenant/waitlist/:id API Key JWT Leave waitlist

Removes the user from the specified waitlist.

Rewards & Loyalty

GET /api/tenant/rewards/status API Key JWT Get reward status

Response

{
  "code": 1,
  "data": {
    "points": 1250,
    "tier": "silver",
    "totalEarned": 3500,
    "totalSpent": 2250
  }
}

GET /api/tenant/rewards/tiers API Key List reward tiers

Returns available reward tiers and their benefits.

Notifications & Extras

GET /api/tenant/notifications API Key JWT Get notifications

Returns the user's unread and recent notifications.

PUT /api/tenant/notifications/:id/read API Key JWT Mark notification as read

Marks the specified notification as read.

GET /api/tenant/favorites API Key JWT Get user favorites

Returns the user's favorited facilities, courts, and coaches.

POST /api/tenant/favorites API Key JWT Toggle favorite

Request Body

Parameter	Type	Description
targetType	string	facility, court, coach required
targetId	number	ID of the target required

GET /api/tenant/user/badges API Key JWT Get user badges

Returns badges earned by the user based on their activity.

GET /api/tenant/user/referral-code API Key JWT Get referral code

Returns or generates the user's unique referral code for sharing.

Error Handling

The API uses standard HTTP status codes along with a consistent error response format:

Status	Meaning
200	Success
201	Created
400	Bad Request - Missing or invalid parameters
401	Unauthorized - Invalid or missing API key / JWT token
403	Forbidden - Feature not enabled for your business
404	Not Found - Resource doesn't exist or doesn't belong to your business
409	Conflict - Resource already exists (e.g., duplicate booking)
429	Rate Limited - Too many requests

Error Response

{
  "code": 0,
  "msg": "Insufficient wallet balance"
}

Rate Limits

API requests are rate-limited per API key. Current limits:

Tier	Limit
Standard	100 requests per minute
Premium	500 requests per minute

When rate limited, the API returns a 429 status code. Implement exponential backoff in your application.

Pickleplus API

Overview

Get Your API Key

Set Up Authentication

Authenticate Users

Start Building

Authentication

API Key Authentication Required for all requests

User JWT Authentication Required for user-specific endpoints

Response Format

User Authentication

Request Body

Response

Request Body

Response

User Profile

Response

Request Body

Business & Branding

Response

Facilities & Availability

Response

Query Parameters

Response

Bookings

Query Parameters

URL Parameters

Request Body

Recurring Bookings

Request Body

Cart & Orders

Request Body

Request Body

Request Body

Wallet

Response

Query Parameters

Products & Shop

Query Parameters

Coaches & Lessons

Request Body

Programmes, Classes & Events

Subscriptions

Request Body

Waitlist

Request Body

Rewards & Loyalty

Response

Notifications & Extras

Request Body

Error Handling

Error Response

Rate Limits