Authentication

First of all, you must request an API token to be able to query the Yoplanning API.
To do so, please request a token in your Yoplanning settings (section "Advanced")

Once you have your token in hands, you can start working with the API. All API methods require authentication.
We use standard token-based authentication system. To authenticate, just provide your API token on the header of each request like so:
Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada
Be careful : the space between "Token" and the token is important.

Here is a full example using curl
curl -H "Content-Type: application/json" https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients/8d23503e-041e-4180-98d1-641183bc5ead -H 'Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada'

If you don't provide a token or if the token is invalid, the API will respond with a 401 HTTP code (Unauthorized) and will give you a "details" field in the response JSON to help you understand the problem.
{"detail":"Invalid token."} or {"detail":"Authentication credentials were not provided."}

Permissions

When you have requested your API token, you have been granted specific permissions on a certain set of teams.
This means you probably cannot use all the API methods listed.
If you call the Yoplanning API without permissions (for instance, you don't have permission to create session-groups on the team), the API will respond with a 403 HTTP code (Forbidden) with the following details.
{"detail":"You do not have permission to perform this action."}

Throttling

For security reasons, the number of requests you can perform is limited, per user (identified by your token) and per clock hour: the counters start again from zero at the top of every hour. Reads (GET, HEAD, OPTIONS) and writes (POST, PUT, PATCH, DELETE) are counted separately, and each user is on one of these tiers:

• Tier 1 (default) : 1000 reads and 100 writes per hour
• Tier 2 : 8000 reads and 200 writes per hour
• Tier 3 : 20000 reads and 1000 writes per hour
• Tier 4 : 50000 reads and 2000 writes per hour

Whatever the tier, a user cannot perform more than 50000 requests per hour in total.

When the limit applies to your token, each response tells you where you stand in the current hour, for the kind of request you made:

• X-RateLimit-Limit : the number of requests of that kind allowed per hour
• X-RateLimit-Remaining : how many are left in the current hour
• X-RateLimit-Reset : when the counters start again from zero (Unix timestamp, in seconds)

Beyond the limit, the server will respond with a 429 HTTP code (Too Many Requests) with the following details :
{"detail":"Request was throttled. Expected available in 1260 seconds."}
If your use case needs a higher tier, please contact our support.

Concurrent requests

Independently of these rates, the number of requests you can have in progress at the same time (sent, but not answered yet) is limited:

• 100 concurrent requests per token
• 100 concurrent requests per IP address, whatever the tokens used

Sending requests one after the other never reaches this limit; firing many of them in parallel does. Beyond it, the server responds immediately with a 429 HTTP code (Too Many Requests), a Retry-After: 1 header and the following details :
{"detail": "Too many concurrent requests, retry later."}
Wait for some of your requests to complete before sending new ones: cap the parallelism of your client (a pool of a few workers is plenty) and retry a refused request after the Retry-After delay.

If you need higher limits for a specific purpose, please contact our support.

Concepts

Team

The team is the most fundamental concept in Yoplanning (which is a collaborative tool).
Almost all methods take a team_id parameter in the url. That means all the actions are relative to a team.

UUID

Lots of methods requires an "id" parameter in the url. This is the unique identifier for the resource you are trying to retrieve / create / update / delete.
Yoplanning uses UUID (version 4) as unique identifier for all resources.

Endpoints and HTTP verbs

For many resources, 2 endpoints are available :
- one to access a specific instance. The endpoint basically ends with {id}, for example :
/api/v3.1/teams/{teamId}/clients/{id}/

You can call these endpoints with the following http verbs :

• GET : Retrieve the resource
• PUT : Update the resource
• DELETE : Delete the resource

- one to access the instances manager : You call these endpoints with the following http verbs :
/api/v3.1/teams/{teamId}/clients

• GET : get a list of all resources (see Pagination)
• POST : create a new resource (The id will be generated by the server)

All these actions are not available for all endpoints. Please see each endpoint documentation to know which methods are allowed.

Using PUT properly

When you want to update a resource, you should always use the following workflow :

1. Retrieve the resource with a GET request
2. Modify the JSON data
3. Send a PUT request with the updated JSON

If you don't, the API may reject you because some nested resources require an ID that you don't give.
In addition, you may loose some data.

Online selling

For online selling purposes (retrieving products and availabilities), only 2 endpoints should be used:

• /api/v3.1/teams/{teamId}/online-products/
• /api/v3.1/teams/{teamId}/online-products/{productId}/availabilities/

Storing your ID

It might be useful to store your own id on each resource you manage, especially if you want to synchronize your system with Yoplanning.
For example, in case of synchronization problems on your side, these ids allow you to recover resources even if you lost the Yoplanning ID.
Therefore, you can store your ID in the external_reference fields in many resources (client, order, session_group, session, payment, ...)
This is not mandatory at all.

When you create an object or a sub-object (the main_client of a new order for exemple), you should not give the "id" property. Yoplanning will ignore that and create its own ID (that you will get in the response).
For instance, if the client already exist in the database, Yoplanning will try to reuse it instead of adding a duplicate.

Pagination

For all API methods that provide a large list of resources, pagination is used.
That means all the results will not be given in a single request. You will have to perform several requests to get the full list of resources.
You can see that as "pages in a book".

For each request, you can use query parameters (query string) in the url to navigate through the result.
Two query parameters can be provided : "offset" and "limit".
offset => the starting point where you want to retrieve data (you can see this as a cursor). Default : 0
limit => the number of results you want to retrieve per request. Default : 100 (which is also the maximum value)

For example : curl -H "Content-Type: application/json" -L "https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients?offset=20&limit=2" -H 'Authorization: Token 4804c2cb4d87a13146d4de029f407c82149f2ada'

Here is an example of response for methods using pagination:
{ "count":53, "next":"https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients?limit=2&offset=22", "previous":"https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients?limit=2&offset=18", "results":[ { "first_name" : "Jack", "last_name" : "Ichan", "email" : "jack.ichan@gmail.com", "phone_number" : "+32684952685", "birth_date" : "1975-05-22", "language" : "fr", "note" : "Pretty cool client :)", "street" : "rue du phare", "city" : "Brest", "postal_code" : "29200", "state" : null, "country" : "FR" "id":"7db70b5c-5175-4ba8-b471-78006940b79c" }, { "first_name":"Loic", "last_name":"Lepoivre", "email":null, "phone_number":null, "birth_date":null, "language":null, "note":null, "street":null, "city":null, "postal_code":null, "state":null, "country":null, "id":"669763dd-3bad-47a9-ac37-02d915a90bbe" } ] }

Explanation:
count => the total number of resources
next => the url to use to retrieve the next page. If there is no next page, the value will be null.
previous => the url to use to retrieve the previous page. If there is no previous page, the value will be null.
results => the list of resources

Filtering

For some endpoints, you can filter the results by adding query parameters to the request.
The following request will give you only the clients with first name "Norbert". https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients?offset=20&limit=2&first_name=Norbert

For date and numeric fields, you can filter using __lt (lower than), __gt (greater than), __lte (lower than or equal), __gte (greater than or equal).
The following request will give you only the clients with birth date greater than 1995-01-25. https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/clients?offset=20&limit=2&birth_date__gt=1995-01-25

Please see each endpoint documentation to know which fields can be used as filters (filters allowed).

Expand fields

For some endpoints, the resource object contains nested resources. For example, a session contains staff.
When you retrieve this resource (using a GET request), you will only retrieve the nested resources ids (here: staff ids).
To avoid sending more requests, you can use the expand mechanism of the API to retrieve the full nested object.

To do so, just append a query parameter in the url : "expand=" with the name of the nested resource you want to expand.
/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/payments/c21010f4-0e68-435b-b076-480087a49db1?expand=operator

You can use a dot notation to go deeper in the object.
/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/orders?expand=items.voucher.product

You can also expand several nested objects using a comma notation
/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/orders?expand=items.voucher.product,payments.operator

Please refer to each endpoint documentation to know which field is expandable.
Note : When you retrieve an instance using a GET request on an instance endpoint, some nested objects may be expanded by default. This forced expand is sometimes necessary in order to allow you to provide this JSON in a PUT request.

Important : If you want to retrieve a resource in order to update it with a PUT request, you MUST NOT USE the expand mechanism.

Webhooks

Webhooks are also called "web callback" or "HTTP push API". It is a notification system.
Rather than asking the API every few minutes whether something changed, you subscribe to an event (for example, each time an order is updated) and we send a POST request to your own url when it happens. You then read only what changed.
Webhooks are the way to keep your system in sync with orders and clients : the last_update field and filters are deprecated, they do not move on every change (a confirmation, a cancellation, a payment...).

Getting access

To receive webhooks on orders, please contact our support : we give you webhook access on orders and set up your subscription. A subscription is made of :

• the team you want to be notified for ;
• the resource : order, client, session_group, product, team_member or unavailability ;
• the event : created, updated or deleted, or all three ;
• your callback url ;
• the format (webhook_version) : 1 or 2, see below.

On request, we also add headers of your choice to every call (a secret key, for example), so that your endpoint can check that the call comes from us.

What you receive

When the event happens on the team, we send a POST request to your callback url, with a JSON body, a few seconds after the change.
With version 1, the body tells you which object changed and where to read it :

{
    "team": { "id": "5a90332e-568f-4980-9859-88a984844a4d" },
    "resource": {
        "id": "8d23503e-041e-4180-98d1-641183bc5ead",
        "type": "order"
    },
    "event": "updated",
    "link": "https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/orders/8d23503e-041e-4180-98d1-641183bc5ead"
}

team.id => the team on which the event occurred
resource.id => the object that has been created / updated / deleted
resource.type => the type of object (order / client / session_group, etc...)
event => the event fired
link => the url to use to retrieve the object

Send a GET request on link to read the object as it is now. Don't forget to add your authentication information when calling the API!

With version 2, the body has no link : it carries the object itself in resource.data, as a GET on the API returns it (an order comes with items.session_group.sessions and payments.operator expanded), so you have nothing to read back. On a deleted event, rely on resource.id only.

Events on orders

• created : an order was created (in the office, online, through the API...). It can come again for the same order, when an order on hold is confirmed for example : handle it by the order's id ;
• updated : the order changed, for example cancelled, paid online, finalised, or its participants changed ;
• deleted : the order was deleted, or merged into another order (which receives an updated).

Whatever the event, read the order's current state (its booking_status, its payments...) rather than deducing it from the event name : a cancelled order, for example, is updated, not deleted.

Answering a webhook

• Answer with a 2xx status within 15 seconds, and process the notification afterwards.
• When your server does not answer within 15 seconds, or answers 500, 502, 503 or 504, we send it again, up to 3 times, within a few seconds.
• So the same notification can arrive twice, and notifications are not guaranteed to arrive in the order of the changes : read the object's current state rather than applying the notifications one after the other.
• The changes you make yourself through the API, with your own token, are not notified back to you.
• A notification can still be lost (your server down for a while, for example) : once a night, re-read the period you care about to reconcile (see Best practices).

Important : when you receive a webhook, read the object and update your system, but never send it back to us with a PUT request : it could lead to an infinite loop.

Errors

Yoplanning uses HTTP response status codes to indicate the success or failure of your API requests. In general, there are three status code ranges you can expect:

• 2xx success status codes confirm that your request worked as expected
• 4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted)
• 5xx error status codes are rare and indicate an error with Yoplanning’s servers. You can still get this error in some rare case if the data you provided is not valid

4xx errors include some data to help you identify what was the problem. Here is an example:
{"price":["This field is required."]}
Keys: The name of the fields that have wrong value.
Values: A list of string describing the errors corresponding to this field.

Best practices

Every request you send is work on our side and counts against your limits (see Throttling). Most integrations only need a small part of what they request: these rules keep your calls fast and far from the limits.

Always send a date window

A list without date filters reads the team's whole history, years of data, on every page. Send a lower and an upper bound: a lower bound alone still returns everything planned after it.
Bad : https://yoplanning.pro/api/v3.1/teams/{teamId}/session-groups/?offset=0&limit=100
Good : https://yoplanning.pro/api/v3.1/teams/{teamId}/session-groups/?start_date__gte=2026-12-01&start_date__lte=2026-12-31

• Each endpoint lists the filters it accepts. A filter or a suffix that is not listed is ignored, and you get the whole list : /api/v3.1/teams/{teamId}/orders/ and /api/v3.1/teams/{teamId}/unavailabilities/ take __gt / __lt, not __gte / __lte.
• To get what overlaps a window, use start_date__lt (the end of the window) with end_date__gt (its start).
• Send one date per filter, like 2026-12-01 or 2026-12-01T08:00:00, never two dates in the same value.

Paginate a window, not the whole history

Each page runs the query again and skips every row before offset : offset=15000 makes us read 15,000 rows to send you 100. To read a long period, cut it into windows (a month, a week) and paginate inside each one by following next.
Bad : https://yoplanning.pro/api/v3.1/teams/{teamId}/orders/?offset=21500&limit=100
Good : https://yoplanning.pro/api/v3.1/teams/{teamId}/orders/?creation_date__gt=2026-10-01&creation_date__lt=2026-11-01&limit=100, then the next url of each page, until it is null.

Keep the default page size

The default limit is 100. Bigger pages are slower to build and to send, and a limit above the maximum is lowered, not refused : always follow next rather than computing the offsets from the limit you asked for.
Bad : ?limit=1000000
Good : ?limit=100, then next.

Use webhooks to follow changes

Re-reading the same data every few minutes sends you the same objects again and again. Rather than asking us whether something changed, let us tell you : with webhooks, we notify you when an order or a client is created, updated or deleted, and you read only that object (see Webhooks). To get webhook access on orders, contact our support.

• last_update and its filters (last_update__gt, last_update__lt) on orders, clients and staff fees are deprecated : this date does not move on every change (a confirmation, a cancellation, a payment...), so a synchronisation built on it misses changes without telling you.
• On online products and availabilities, last_modified__gt still asks for what changed since your last run : use as the bound the highest last_modified you received (in UTC), not your own clock.
• Once a night, re-read the period you care about to reconcile, in case a notification was lost.

Bad : every 5 minutes, all the orders of the team, or orders/?last_update__gt=2026-10-22T09:15:03.
Good : webhooks on orders, plus a nightly https://yoplanning.pro/api/v3.1/teams/{teamId}/orders/?creation_date__gt=2026-10-01&creation_date__lt=2026-11-01

One list with expand, not one request per object

Fetching objects one by one in a loop, often in parallel, is what reaches the limit of concurrent requests. One list request returns up to 100 objects, and expand brings their nested objects with them (see Expand fields).
Bad : a request to /api/v3.1/teams/{teamId}/orders/{id}/ for each order.
Good : https://yoplanning.pro/api/v3.1/teams/{teamId}/orders/?creation_date__gt=2026-10-01&creation_date__lt=2026-11-01&expand=items.session_group,payments

Cache what rarely changes

Products (with their places) and categories change a few times a season. Read them once, keep them, and refresh them once a day or when a product webhook arrives.
Bad : reading /api/v3.1/teams/{teamId}/online-products/ before each booking.
Good : a copy on your side, refreshed daily, also for /api/v3.1/categories/.

Back off on 429

A 429 answer means you reached a limit (see Throttling). Wait the number of seconds given in its Retry-After header before sending again, and never retry right away in a loop : it only keeps you over the limit.
Bad : retrying a refused request immediately, or in parallel.
Good : a few workers at most, and a pause of Retry-After seconds after a 429.

Run each job once

The same synchronisation running on two machines doubles the requests, and both share the limits of your token : they reach them twice as fast. Run each job from a single scheduler, and do not start a run while the previous one is still going.

Identify yourself

Send a User-Agent header naming your company and a contact, not the default of your HTTP library (node, python-requests, curl) : when an integration loads the API, it is how we can reach you.
User-Agent: MyCompany-Sync/2.3 (tech@mycompany.com)

Tutorial: Sell activities online

Introduction

Retrieve your teams data

Get the list of products

Get availabilities for a product

(Optional) Retrieve available options (resources)

(Optional) Check everything is still available

(Optional) Hold the places while your client pays

(Optional) Create a payment via Payment Manager

Place the order