Playtomic API: Complete Guide

The Playtomic API lets clubs access their booking and payment data from external systems. This guide explains who can use it, how to get credentials, which data is available and what the limits are.

What is the Playtomic API?

The Playtomic API is a secure, read-only interface that lets clubs access their booking and payment data from other systems. Whether you run one club or several, you can use it to:

• Integrate with your existing systems, such as CRMs, marketing tools, loyalty platforms or facility management software
• Access booking data from the last 3 months and all future bookings
• Access detailed payment data, including periods older than 1 year
• Automate data synchronisation to streamline club operations
• Improve member communication through external tools and platforms

Who can access the API?

API access is available for:

• Single-location clubs with a Champion or Master subscription plan
• Multi-location clubs where each tenant has a Champion or Master subscription
• Chain owners, who get unified access to the data of all clubs in their organisation

What data can I get from the API?

The API is read-only. You can retrieve data, but you can't create, edit or delete it.

Bookings

• Booking ID and timestamps (UTC)
• Court information (ID, name)
• Player details (IDs, email, communication preferences)
• Payment information
• And more (view the complete data specification)

Payments

• Detailed data for each payment and refund at your club, including payment ID and refund ID
• See the Payments endpoint documentation for all fields

Which features are coming next?

We're working on:

• Player data endpoints (using the same authorisation)
• Detailed event, activity and clinic data

Contact your account manager to request specific features.

How do I get API credentials?

Individual clubs

You can create and manage your own API credentials in Playtomic Manager. Go to Settings > Developer Tools. From there, you can:

• Generate credentials
• Regenerate credentials
• Delete credentials
• View the documentation

📄 Complete API documentation (v1.1)

Note: Copy your Client ID and Client Secret and store them somewhere secure. Treat your Client Secret like a password: don't share it publicly or expose it in front-end code. If you lose it, generate new credentials. This invalidates the previous ones.

Chain owners

If you manage several clubs as part of a chain:

1. Contact your Playtomic account manager, or Customer Care via chat, to request unified API access for all your locations.
2. Open the secure link you receive with your credentials. The link is valid for 3 days and can be opened 3 times at most.
3. Store your credentials securely. The link expires and can't easily be regenerated.
4. Read the documentation and start your integration.

Note: Chain credentials give access to all clubs in your organisation. Keep them secure and share them only with authorised team members.

How does authentication work?

The API uses OAuth 2.0:

• Client ID and Client Secret: unique identifiers for your club or system
• Access token: a temporary credential (usually valid for 1 hour) that you use for API calls

Token request example:

POST <https://thirdparty.playtomic.io/api/v1/oauth/token>
Content-Type: application/json

{
  "client_id": "your_client_id",
  "secret": "your_client_secret"
}

API call example:

GET <https://thirdparty.playtomic.io/api/v1/bookings>
Authorization: Bearer your_access_token

🔒 Security best practices:

• Keep your Client Secret confidential.
• Never expose credentials in public repositories.
• Set up automatic token renewal in your systems.

How much data can I get, and what are the limits?

Bookings

• Past bookings: last 3 months only. Older bookings aren't returned.
• Future bookings: available as scheduled.
• Maximum range per request: 365 days (for example, the last 3 months plus the next 9 months).

Payments

• Maximum range per request: 13 months. This limits the length of each request, not how far back you can go.
• Longer periods: split them into several consecutive requests of up to 13 months each. For example, for 2024 to 2026:
  1. 1 January 2024 – 31 January 2025
  2. 1 February 2025 – 28 February 2026
  3. 1 March 2026 – today
• No date filter: if you provide no date filter, the API defaults to the last 13 months.
• Date type: each request filters by payment date or service date, not both.
• First request: the API may answer 202 Accepted while it prepares your club's payment history. This usually takes a few minutes. Wait and try again.

Timezone

• All timestamps are in UTC. Make sure your systems convert them to your local timezone.
• Check your club's timezone in Playtomic Manager > Settings > Club Info.

Rate limits

API calls are rate-limited (usually 1 call per minute) to keep the system stable. Check the documentation for current limits.

What can I use the API for?

• CRM synchronisation: import booking data for targeted marketing campaigns
• Analytics and reporting: analyse court use, player frequency and payments
• Member communication: send automated confirmations and reminders through external tools
• Facility management: integrate with smart door locks, lighting or other IoT systems
• Loyalty programmes: track member activity for rewards and retention

Where can I get help with the API?

• Account manager: feasibility checks, chain access requests and feature requests
• Technical support: API troubleshooting and integration help
• Documentation: complete examples, parameters and endpoint descriptions

There's no separate testing environment. You can safely test with your real data using limited queries during development.

FAQ

Authentication and access

How do I get API credentials? If you manage one club, go to Settings > Developer Tools in Playtomic Manager and generate them yourself. If you're a chain owner, contact your account manager or Customer Care via chat. You'll receive a secure link (valid for 3 days, 3 opens at most) with your Client ID and Client Secret.

What should I do if I get "Unauthorized" errors (401/403)? Check that:

• Your request includes the Authorization: Bearer token header.
• Your access token hasn't expired. Refresh it if needed.
• Your Client ID and Client Secret are correct.
• You haven't exceeded the rate limits.

Can someone else in my organisation create new credentials? Yes, but new credentials invalidate the previous ones. Share credentials within your organisation so you don't break existing integrations.

Data access

Can I create or edit bookings through the API? No. The API is read-only. You can retrieve and analyse data, but you can't create, edit or delete bookings.

How much booking history can I get? Bookings from the last 3 months, plus all future bookings. Each request can cover up to 365 days.

Can I get payments older than 13 months? Yes. 13 months is the maximum range of a single request, not a limit on how far back the data goes. To get a longer period, make several consecutive requests of up to 13 months each.

Can I get all my bookings and payments from previous years?

• Payments: yes, through the API. Split the period into several requests of up to 13 months each.
• Bookings: no. The API and the Bookings list in Playtomic Manager both only include the last 3 months.
• Reports in Playtomic Manager show totals for older periods, but not each booking or payment.

What timezone are the timestamps in? All timestamps are in UTC. Your integration needs to convert them to your local timezone.

Multi-location and chain management

As a chain owner, can I access all my clubs' data? Yes. Chain owners get unified access to data from all clubs in their organisation. You can filter by club or get data for all locations.

Do all locations need a Champion or Master subscription? Yes. For multi-location access, each tenant needs a Champion or Master subscription.

Technical implementation

How often can I call the API? Rate limits apply (usually 1 call per minute). Check the documentation for current limits.

Can I test the API before going live? There's no separate testing environment. You can safely test with your real data using limited queries.

Will more features be added to the API? Yes. We're working on player data endpoints and detailed event, activity and clinic data. Contact your account manager to request specific features.

Support

What information should I include when I contact support?

• The full error message
• The endpoint you were calling
• Your Club ID
• The steps you've already tried

Who should I contact for each type of issue?

• Access for chains: your account manager, or Customer Care via chat
• Technical integration: the technical support team
• Feature requests: your account manager
• Billing or subscription: your account manager

💬 Need Help?

If you have any questions or need further assistance, don’t worry! 😊 You can always contact us. We’re here to help!