Bookings

Overview

Bookings are one of the most vital parts of our system. A booking is created in one of two ways: In the first, a users utilises our booking platform in order to book themselves on to an event, the "booker" key will be the userOd. In the second, they can be booking directly by an event runner. When a user has been booked directly, the "booker" key will be the user id of the event runner that booked them on. As well as this, the key "bookedManually" will be true.

When a user cancels their booking, it's updated to reflect this change & vice-versa. In the case where the event is set to "Register Interest", the booking will have two keys "userStatus", and "orgStatus" that represent the bookings progression through the process.

When a user attends the event, the booking is finally updated with an "attended" state which represents whether the user was registered at the event of not by the event runner.

All routes of the booking API require an authorization header set with your auth token, or an API key if you are an organisation that has contacted us for access.

GET

Get bookings for a user.

Endpoint

https://book.plinth.org.uk/api/bookings

Query Parameters

One of the following is required:

{
  memberId: "MEMBER_ID", // Member ID, Member Id that a booking was made for
  funderMemberId: "FUNDER_MEMBER_ID", // Funder Member ID, used to view programme bookings
}

Response Object

[
  {
    "id": "string", // booking id
    "attending": true | false, // False if a user cancels their booking
    "attended"?: true | false, // Whether or not the user attended the event (added after a register has been taken)
    "bookedManually"?: true | false, // Was the booking made manually by the event runner
    "booker": "string",  // Id of the booker (userId for self-booking, adminId for a manual booking
    "created": "2023-08-25T17:13:45.400Z", // Isostring for when the booking was created.
    "date" "2023-08-25", // YYYY-MM-DD date of the event
    "start": "2023-09-02T11:00:00.000Z", // Isostring for when the event starts
    "end": "2023-09-02T11:40:00.000Z", // Isostring for when the event ends
    "eventId": "string", // Event id the booking was made for
    "free": true | false, // Whether or not the event is free or not
    "managedBy": "string", // Id of the organisation that runs the event
    "memberId": "string", // Id of the member that this booking is for
    "name": "Event Name", // Name of the event
    "orderId": "string", // Id of the order where this booking was made
    "slotId"?: "string", // If there is a timeslot booked on the event, this is the id of the timeslot.
    "type": "user", // Type of the booking
    "userName": "Name", // name of the user
    "userEmail": "Steve@email.com", // Where to email booking updates
    "fullPrice": 0, // If this is a paid event, will be the price
    "orgStatus": "pending" | "confirmed" | "cancelled" | "waitlist", // If the event is set to register interest, these represent the state the booking is in.
  }
];

Booking/:id

GET

Get the booking with the given id.

Endpoint

https://book.plinth.org.uk/api/bookings/:id

Query Parameters

One of the following is required:

{
}

Response Object

The requested booking

  {
    "id": "string", // booking id
    "attending": true | false, // False if a user cancels their booking
    "attended"?: true | false, // Whether or not the user attended the event (added after a register has been taken)
    "bookedManually"?: true | false, // Was the booking made manually by the event runner
    "booker": "string",  // Id of the booker (userId for self-booking, adminId for a manual booking
    "created": "2023-08-25T17:13:45.400Z", // Isostring for when the booking was created.
    "date" "2023-08-25", // YYYY-MM-DD date of the event
    "start": "2023-09-02T11:00:00.000Z", // Isostring for when the event starts
    "end": "2023-09-02T11:40:00.000Z", // Isostring for when the event ends
    "eventId": "string", // Event id the booking was made for
    "free": true | false, // Whether or not the event is free or not
    "managedBy": "string", // Id of the organisation that runs the event
    "memberId": "string", // Id of the member that this booking is for
    "name": "Event Name", // Name of the event
    "orderId": "string", // Id of the order where this booking was made
    "slotId"?: "string", // If there is a timeslot booked on the event, this is the id of the timeslot.
    "type": "user", // Type of the booking
    "userName": "Name", // name of the user
    "userEmail": "Steve@email.com", // Where to email booking updates
    "fullPrice": 0, // If this is a paid event, will be the price
    "orgStatus": "pending" | "confirmed" | "cancelled" | "waitlist", // If the event is set to register interest, these represent the state the booking is in.
  }

PUT

Modify a user booking. This is called most commonly when a user cancels a booking, or an organisation cancels a booking. It's also used in the case of waiting lists when the a user is confirmed or denied a place, or a user changes their details.

Endpoint

https://book.plinth.org.uk/api/bookings

Query Parameters

One of the following is required:

{
}

Response Object

We return the modified resource in its entirety.

  {
    "id": "string", // booking id
    "attending": true | false, // False if a user cancels their booking
    "attended"?: true | false, // Whether or not the user attended the event (added after a register has been taken)
    "bookedManually"?: true | false, // Was the booking made manually by the event runner
    "booker": "string",  // Id of the booker (userId for self-booking, adminId for a manual booking
    "created": "2023-08-25T17:13:45.400Z", // Isostring for when the booking was created.
    "date" "2023-08-25", // YYYY-MM-DD date of the event
    "start": "2023-09-02T11:00:00.000Z", // Isostring for when the event starts
    "end": "2023-09-02T11:40:00.000Z", // Isostring for when the event ends
    "eventId": "string", // Event id the booking was made for
    "free": true | false, // Whether or not the event is free or not
    "managedBy": "string", // Id of the organisation that runs the event
    "memberId": "string", // Id of the member that this booking is for
    "name": "Event Name", // Name of the event
    "orderId": "string", // Id of the order where this booking was made
    "slotId"?: "string", // If there is a timeslot booked on the event, this is the id of the timeslot.
    "type": "user", // Type of the booking
    "userName": "Name", // name of the user
    "userEmail": "Steve@email.com", // Where to email booking updates
    "fullPrice": 0, // If this is a paid event, will be the price
    "orgStatus": "pending" | "confirmed" | "cancelled" | "waitlist", // If the event is set to register interest, these represent the state the booking is in.
  }

Batch

Make or update multiple bookings at once. All bookings must be for the same programme. Either all updates will fail, or all will succeed.

POST

This is the route on which bookings are made for an event & user. We do not expose details on this route publically.

Endpoint

https://book.plinth.org.uk/api/bookings/batch

PUT

Modify a number of bookings for a user. Normally called when an events start/end time is modified, and all the bookings for that event need to be modified in bulk.

Endpoint

https://book.plinth.org.uk/api/bookings

Body

{
  "eventId": "string",
  "start": Isostring,
  "end": IsoString,
  "orgStatus": "pending" | "confirmed" | "cancelled" | "waitlist"
}

Response Object

We return the modified resource in its entirety.

  {
    "id": "string", // booking id
    "attending": true | false, // False if a user cancels their booking
    "attended"?: true | false, // Whether or not the user attended the event (added after a register has been taken)
    "bookedManually"?: true | false, // Was the booking made manually by the event runner
    "booker": "string",  // Id of the booker (userId for self-booking, adminId for a manual booking
    "created": "2023-08-25T17:13:45.400Z", // Isostring for when the booking was created.
    "date" "2023-08-25", // YYYY-MM-DD date of the event
    "start": "2023-09-02T11:00:00.000Z", // Isostring for when the event starts
    "end": "2023-09-02T11:40:00.000Z", // Isostring for when the event ends
    "eventId": "string", // Event id the booking was made for
    "free": true | false, // Whether or not the event is free or not
    "managedBy": "string", // Id of the organisation that runs the event
    "memberId": "string", // Id of the member that this booking is for
    "name": "Event Name", // Name of the event
    "orderId": "string", // Id of the order where this booking was made
    "slotId"?: "string", // If there is a timeslot booked on the event, this is the id of the timeslot.
    "type": "user", // Type of the booking
    "userName": "Name", // name of the user
    "userEmail": "Steve@email.com", // Where to email booking updates
    "fullPrice": 0, // If this is a paid event, will be the price
    "orgStatus": "pending" | "confirmed" | "cancelled" | "waitlist", // If the event is set to register interest, these represent the state the booking is in.
  }