Calendar
Your schedule, booking pages and services.
Calendar has public methods for the two sides of a booking. Some act for you, the owner, and take your API key: they read your setup and your bookings, set up resources, services and pages, hold and confirm a time, cancel, and change the plan. Others are the ones a booking page makes for a visitor. They need no key, only the page's key.
Sharing calendars with other people, the views, tasks, day events and Calendar settings are done in the dashboard. They have no public method today.
Send a request to a method with your key:
A good answer has code 1. A change your plan does not include is refused with code -62 and a sentence in data, for example that group sessions need Growth or that your plan holds a number of booking pages. To act on the calendar of an account that shared it with you at the edit level, pass its share_id to the methods that take one.
Read your setup and bookings
get_calendar_setupanswers everything the Calendar screens draw in one call: the bookable people and rooms with their hours, the services, and the published booking pages with their public addresses.get_calendar_bookingslists bookings, upcoming by default. Passpastset totruefor the ones that already happened, newest first, andlimitfor how many. Each row carries the time in the resource's zone, the guest's details and anything they said when booking.get_calendar_slotslists the bookable times of one service on one resource betweenfrom_tsandto_ts(epoch milliseconds), with everything already taken left out.
Set up what can be booked
save_calendar_resourcemakes or updates something that can be booked: a person, a room, a chair or a device. It needs atimezone, an IANA zone such asAsia/Jerusalem, and its hours are read in that zone. Omitresource_idto make a new one.save_calendar_servicemakes or updates what people can book: its length, buffers, notice, how far ahead it can be booked, seats, where it meets (meeting_kind), and, withprice_cents,currencyandcheckout, what it costs and whether it is paid at booking. More than one seat needs a plan that includes group sessions, and taking payment needs a plan that includes payments.save_calendar_pagemakes or updates a booking page: itstitle,intro, theservice_idsit offers, whether it isenabled, itsaccentcolour, itsbg_colorandtext_color(each#rrggbb, or empty to have the page make it from the accent),show_host, whether visitors can change their booking (visitor_changes,change_hours,refund_percent) and the finance account it is paid into (finance_account_id). Making a page past your plan's page limit is refused.delete_calendar_itemremoves a resource, a service or a page byitem_id. Bookings are never deleted this way: they are cancelled.
Book a time yourself
Booking from your own code is two steps, so one time is never sold twice.
Hold the time
hold_calendar_slot reserves a time for a few minutes. Pass resource_id, service_id and start_utc (epoch milliseconds). A good answer has data with occ_id, hold_token and expires_at. Send an idem_key so a repeat of the call returns the same hold instead of taking a second seat.
Confirm it
confirm_calendar_booking turns the hold into a booking. Pass the occ_id and hold_token from the hold, and the guest's name, email, phone and note. A hold that is no longer there has lost the time and is refused.
Change a booking
cancel_calendar_bookingcancels bybooking_idand puts the time back on the public grid. It is safe to call twice. It only frees the time: it does not email the guest or refund a payment, which the dashboard's Cancel appointment does for a guest who booked through your page.notify_calendar_guestsemails everyone invited to one booking, one message each, with the calendar invite attached and an optionalmessageof up to 2000 characters.kindisinvitefor a new appointment andupdatefor a change, which is the default. The email comes from your own mailbox on a plan that includes it, and from Xuda's booking address otherwise, with your address as the reply-to.create_booking_roommakes the Xuda Meet room of a confirmed video booking that has none, and sends each guest the link.
What a booking page calls
A booking page works with its page key, <uid>.<page_id>, and no account.
get_booking_bootstrapanswers what a page needs to draw itself: its title, its services and a fresh anti-bot token.get_public_booking_slotslists the times a visitor can choose, each with a start, an end and a seat count. It never says who holds the other seats.public_book_slottakes a booking from a visitor. Pass thepage_key,service_id,start_utc, thetoken, and the visitor'snameandemail. Add anidem_keyso a double press does not book twice.company_websiteis a trap for bots: leave it empty.- For a service that is paid when booking,
public_start_paid_bookingholds the time and starts the payment,start_booking_paymentsends a held time to Stripe, andpublic_confirm_paid_bookingandconfirm_paid_bookingbook it once the payment has cleared. The payment is read back from Stripe before anything is booked. - A visitor manages a booking from the private link in their email.
get_public_booking,public_cancel_bookingandpublic_reschedule_bookingtake the page key and that link'smanagevalue. They follow the page's rules: whether visitors may change a booking, and up to how many hours before it starts. A paid booking is refunded first, by the page's refund percent.
The plan
get_calendar_plans answers the four tiers with their prices and what each one carries, which plan you are on and whether Calendar is switched on. calendar_set_plan switches it on, changes the tier or switches it off: pass plan_id as calendar_free, calendar_starter, calendar_growth or calendar_business, or set deactivate to true. See Plans and billing.