Bookings

Naming Convention Update

We are transitioning our naming conventions:

player instead of participant

New endpoints will use the updated terminology.

GET /api/v1/bookings

Retrieves a list of bookings based on filters.

Parameters

Parameter	Type	Required	Description
`tenant_id`	String	Yes	ID of the venue/club where the booking takes place.
`booking_id`	List[String]	No	List of specific booking IDs. Ignores other filters if used.
`start_booking_date`	Date (UTC)	Conditional	Required if `booking_id` is not used. Format: `YYYY-MM-DDTHH:MM:SS`.
`end_booking_date`	Date (UTC)	Conditional	Required if `booking_id` is not used. Format: `YYYY-MM-DDTHH:MM:SS`. Max range 365 days.
`participant_id`	String	No	ID of a player. By using this filter, you will find the bookings in which this person is one of the players.
`booking_type`	String	No	Possible values: `REGULAR_BOOKING` `RECURRING_BOOKING` `OPEN_MATCH` `LEAGUE_MATCH` `PRIVATE_CLASS` `COURSE_CLASS` `TOURNAMENT` `PUBLIC_CLASS`
`sport_id`	String	No	Possible values: `PADEL` `TENNIS` `PICKLEBALL` `FOOTBALL7` `FUTSAL` `FOOTBALL_OTHERS` `PADBOL` `SQUASH` `BADMINTON` `BEACH_TENNIS` `BEACH_VOLLEY` `BASKETBALL` `VOLLEYBALL` `CRICKET` `TABLE_TENNIS`
`status`	String	No	Possible values: `PENDING`: current time < `booking_start_date` `IN_PROGRESS`: current time between `booking_start_date` and `booking_end_date` `FINISHED`: current time > `booking_end_date` `CANCELED`
`page`	Int	No	Page number (default `0`)
`size`	Int	No	Results per page (max `200`)

Historical Data

We only keep bookings until three months in the past. Bookings older than that won't be returned.

Response (200)

A list of Booking objects. It is important to note that if you do not use the page, size and sort params, by default we will return a first page with 100 results ordered in descendent order by start_booking_date.

Field	Type	Required	Description
`booking_id`	String	Yes	ID of the booking.
`object_id`	String	Yes	Internal ID that we relate with our internal products that can be related with the Booking concept (matches, classes, leagues…).
`tenant_id`	String	Yes	ID of the venue/club where the booking takes place.
`resource_id`	String	Yes	ID of the court where the booking takes place.
`resource_name`	String	Yes	The name of the court where the booking takes place.
`sport_id`	String	Yes	Possible values: `PADEL` `TENNIS` `PICKLEBALL` `FOOTBALL7` `FUTSAL` `FOOTBALL_OTHERS` `PADBOL` `SQUASH` `BADMINTON` `BEACH_TENNIS` `BEACH_VOLLEY` `BASKETBALL` `VOLLEYBALL` `CRICKET` `TABLE_TENNIS`
`booking_start_date`	Date (UTC)	Yes	Date when the booking starts. Format: `YYYY-MM-DDTHH:MM:SS`.
`booking_end_date`	Date (UTC)	Yes	Date when the booking ends. Format: `YYYY-MM-DDTHH:MM:SS`.
`duration`	Long	Yes	Difference in microseconds between the `booking_start_date` and the `booking_end_date` of the booking.
`origin`	String	Yes	Possible values: `ANEMONE`: created internally by Playtomic `LEAGUES`: created automatically from a Playtomic league `PLAYTOMIC_MANAGER`: created from Playtomic Manager `RECURRING_MATCH_CONFIGURATION`: created from a recurring match configuration `MANAGER`: same as PLAYTOMIC_MANAGER `APP_ANDROID`: created from the app by a player using Android `APP_IOS`: created from the app by a player using iOS `WEB`: created from Playtomic Web without a known source `WEB_MOBILE`: created from Playtomic Web in its mobile version `WEB_DESKTOP`: created from Playtomic Web from desktop version `APP`: created from the app by an unknown source.
`price`	String [Money]	Yes	The price of the full booking (including every spot if it is a split payment) Format: `amount currency_code`, ie. `10 EUR` or `25 USD`.
`booking_type`	String	Yes	Possible values: `REGULAR_BOOKING` `RECURRING_BOOKING` `OPEN_MATCH` `LEAGUE_MATCH` `PRIVATE_CLASS` `COURSE_CLASS` `TOURNAMENT` `PUBLIC_CLASS`
`payment_status`	String	No	Possible values: `UNPAID`: applies in `_CLASS` when nobody has paid `PARTIAL_PAID`: applies when the booking is not paid by everyone `PAID`: applies when the booking has been paid by everyone `PENDING`: applies when the `_BOOKING` or `*_MATCH` are not paid by everyone `REFUNDED`: applies when the booking has been refunded `NOT_APPLICABLE`: default value. `TOURNAMENT` booking type will always have this value.
`participant_info`	Object	No	See ParticipantInfo Model below.
~~`coach_id`~~	String	No	Deprecated, use `coach_ids`. ID of the coach linked to the booking, if any (applyable for private, public and course classes).
`coach_ids`	List [String]	No	ID of the coaches linked to the booking, if any (applyable for private, public and course classes). A public class can have multiple coaches.
`course_id`	String	No	ID of the course, if the booking is linked to a particular course (only valid for course classes).
`course_name`	String	No	Name of the course, if the booking is linked to a particular course (only valid for course classes).
~~`tournament_id`~~	String	No	Deprecated, use `activity_id`. ID of the tournament, if the booking is linked to a particular tournament (only valid for tournament locks).
`activity_id`	String	No	ID of the activity, if the booking is linked to a particular one (only valid for tournament and public class locks). This allow to distinguish which bookings are associated with the same activity when it has multiple resources.
`activity_name`	String	No	Name of the activity, if the booking is linked to a particular one (only valid for tournament and courses).
`is_canceled`	Boolean	No	Flag to determine if the booking was canceled.

Models

ParticipantInfo Model

Field	Type	Required	Description
`owner_id`	String	No	ID of the player that is considered the owner of this booking. This means he's the person responsible for this match, he cannot leave the match, he will be paying if it's a single payment… (For regular bookings and recurring bookings).
`participants`	List [Participant]	Yes	A list (can be empty) that will contain all the players in this booking. See Participant Model below.

Participant Model

Field	Type	Required	Description
`participant_id`	String	Yes	ID of the player.
`family_member_id`	String	No	ID of the family member, if he was included in the booking.
`name`	String	No	Name of the player.
`email`	String	No	Email of the player if they are Playtomic users.
`accepts_commercial_communications`	Boolean	Yes	`true` if the player has explicitly accepted to receive marketing communications from the venue. Otherwise, `false`.
`participant_type`	String	Yes	Possible values: `GUEST`: included from manager and are not real Playtomic players (meaning, registered users in the app) `CUSTOMER`: real Playtomic player `CONTACT`: people that is not a real Playtomic player, that was invited through Playtomic app by a real Playtomic player.

Errors

Status Code	Error	Description
400	`DATES_IN_WRONG_ORDER`	The date filter you have requested has a end date that is previous to the start date in the date range.
400	`MISSING_DATE_PARAMS`	You have not included any date range filter in the request.
401 or 403	-	Either you have not set the authorization header or the token has expired.

Example

CURL RequestJSON Response

curl --request GET \
  --url "https://thirdparty.playtomic.io/api/v1/bookings?tenant_id=tenant-id&start_booking_date=2025-08-01T00:16&end_booking_date=2025-08-15T00:16&page=0&size=20" \
  --header "content-type: application/json" \
  --header "Authorization: Bearer <your-secret-token>"

[
    {
        "booking_id": "booking-id",
        "object_id": "object-id",
        "tenant_id": "tenant-id",
        "resource_id": "resource-id",
        "resource_name": "Padel Single Court 1",
        "sport_id": "PADEL",
        "booking_start_date": "2025-08-02T11:30:00",
        "booking_end_date": "2025-08-02T11:45:00",
        "duration": 900000,
        "origin": "MANAGER",
        "price": "0 EUR",
        "booking_type": "RECURRING_BOOKING",
        "payment_status": "PENDING",
        "participant_info": {
            "owner_id": "234",
            "participants": [
                {
                    "participant_id": "234",
                    "name": "Test owner",
                    "email": "testOwner@email.com",
                    "accepts_commercial_communications": true,
                    "participant_type": "CUSTOMER"
                }
            ]
        },
        "coach_ids": null,
        "is_canceled": false,
        "status": "FINISHED"
    }
]

Updates

Tournament Data

The bookings list will be expanded to include tournament information similar to what is contained in the Playtomic Manager Schedule. It is important to note that tournaments are not bookings in the same way that matches or classes are, but for consistency with the Schedule, we have decided to include them in the bookings list. The different booking entries for the same tournament represent the occupation of resources (courts) on different days.

To support tournament data, the new TOURNAMENT value will be added as booking_type and also the field activity_id will be included.

Public Class Data

The bookings list will be expanded to include public classes information once a new version is rollout. The new version locks resources and coaches availability, if they have them. For consistency with the Schedule, we have decided to include them in the booking list. The different booking entries for the same public class represent the occupation of resources (courts).

To support public class data, the new PUBLIC_CLASS value will be added as booking_type and also the field activity_id will be included.