List Bookings

Overview

This endpoint retrieves a paginated list of bookings filtered by customer phone number. It allows you to search for all bookings associated with a specific customer and returns comprehensive booking details including customer information, branch details, services, and payment status.

Query Parameters

Parameter	Type	Required	Description
`search`	string	Yes	Customer phone number to search for bookings (e.g., `966512345678`). Use the full phone number with country code.
`per_page`	integer	No	Number of results to return per page. Default: `15`. Controls pagination size.
`page`	integer	No	Page number for pagination. Default: `1`. Use this to navigate through multiple pages of results.

Headers

Header	Required	Description
`Customer-Key`	Yes	Authentication key for the customer. Used to identify and authenticate the API consumer.
`Secret-Key`	Yes	Secret authentication key. Provides additional security layer for API access.
`Accept-Language`	No	Language preference for the response content (e.g., `ar` for Arabic, `en` for English). Affects localized fields like status labels and service names.

Response Structure

Success Response (200 OK)

{
  "success": true,
  "message": null,
  "data": [...],
  "meta": {...}
}

Response Fields

success (boolean): Indicates whether the request was successful

message (string|null): Additional message or error information

data (array): Array of booking objects, each containing:

uuid (string): Unique identifier for the booking

customer (object): Customer information

first_name, last_name, full_name: Customer name details

email: Customer email address

phone: Customer phone number with country code

branch (object): Branch/location details

uuid: Branch unique identifier

name: Branch name

address: Physical address

location: Geographic coordinates (lat/lng)

map_url: Google Maps URL for the location

booking_date (string): Date of the booking (YYYY-MM-DD)

booking_time (string): Time of the booking (HH:MM:SS)

booking_datetime (string): Combined date and time with timezone

currency (string): Currency code (e.g., "SAR")

total_amount (string): Total booking amount

paid_amount (number): Amount already paid

remaining_amount (number): Outstanding balance

coupon_code (string): Applied coupon code (if any)

services (array): List of booked services with details:

uuid: Service unique identifier

name: Service name

price: Service price

duration: Service duration in hours

image: Service image URL

icon: Service icon URL

booking_status (object): Current booking status

code: Status code (e.g., "pending", "confirmed", "in_progress")

label: Localized status label

payment_status (object): Payment status

code: Payment status code (e.g., "pending", "paid")

label: Localized payment status label

statuses (array): History of status changes

created_at (string): Booking creation timestamp

meta (object): Pagination metadata

current_page: Current page number

last_page: Total number of pages

per_page: Results per page

total: Total number of bookings found

Example Use Case

Scenario: A customer service representative needs to find all bookings for a customer who called with phone number +966512345678.

Request:

GET {{url}}/v1/bookings?search=966512345678&per_page=15&page=1

Result: The API returns all bookings associated with that phone number, showing booking details, service information, payment status, and branch locations. The representative can then assist the customer with their booking inquiries, modifications, or cancellations.

Notes

The search parameter matches against the customer's phone number stored in the system

Results are paginated; use the meta object to navigate through multiple pages

All monetary values are returned as strings to preserve precision

Timestamps include timezone information (+03:00 in the examples)

The Accept-Language header affects the localization of labels and service names

List Bookings

List Bookings#

Overview#

Query Parameters#

Headers#

Response Structure#

Success Response (200 OK)#

Response Fields#

Example Use Case#

Notes#

Request

Responses

List Bookings

Overview

Query Parameters

Headers

Response Structure

Success Response (200 OK)

Response Fields

Example Use Case

Notes