Skip to content

Bookings on the site ​

What a site that turns the bookings module on has to draw. The rules — when the business is open, how long a slot is, whether a time is still free — live in one place and it is not the page: every address the page talks to is served by the platform on the site's own host, and the page renders what they answer. Those addresses, the visitor's own page, the letters and Turnstile are the booking protocol; this page is what to draw with them.

Turning it on ​

For a business of a kind the platform knows — a salon, a clinic, a car rental, a hotel and the rest — start from its kit: the collections, the rates and the settings below, already laid out for the trade and judged on the way past. What follows is what a kit is made of.

The schema declares the module and points it at two collections:

jsonc
"modules": {
  "bookings": {
    "services":  "services",   // entries carrying `takes` (minutes) and, to be payable, `costs`
    "resources": "masters"     // entries that get occupied; one entry is a solo business
  }
}

The shape the two entry types have to be — takes as a duration, costs as money, hours as a list of day, opens, closes rows — is generated from the module's own declaration in modules, and the validator holds a schema to it: a services type with no takes, or a key of the wrong kind, is refused before any build.

Paid online, or on the spot? Ask before deciding. A rate without costs is bookable and not payable, and that is the ordinary state for a business that takes its money on arrival — a bowling club, a hairdresser with a till. Where the current site books without paying, say so and ask whether paying online is to be added; do not switch a business to online payment because the module can. A price that depends on the day and the hour — a lane 25 € before six and 42 € on a Friday night — is the service's rates instead of costs: rows of day, from, until and costs, a week of opening hours with a price on each row. See A price by the hour of the week below. Not a rate per price zone (the visitor would be left to match the zone to the time, and nothing would check it), and not one price near enough with a footnote (the form would name a sum the till does not).

A resource entry may carry its own weekly hours — a list of day, opens, closes rows, the same shape as the module's — and is then offered only inside them and inside the business's own. The business's hours, days off, the confirmation mode, the cancellation window and the payment policy are the module's settings document, which the client edits in the admin under the diary.

A record, not a post — and every fact once ​

What the module reads is a record the diary occupies or offers, and the panel draws it as a form. Two mistakes the first booking-enabled sites made, both valid schemas, both wrong:

  • The blog's shape copied onto a service or a table. An excerpt, a cover, a body of eight thousand characters and a page at /tables/<slug> for each one. A service is short fields — a name, takes, costs, a line — with no body, and its collection's route is "none" with shown_on naming the price list's page, because it is a row of the price list the form reads. A resource is a name with its own hours, what it does, seats or spots; a master may well have a page and a paragraph about her, a billiard table may not.
  • A fact the module holds, typed again as text. Opening hours as day and time text rows on a page block, beside the hours the owner keeps in the diary; a tariff block with price as text, beside the services' costs. Two copies, and the page's goes stale the day the owner changes the panel's. The hours live in jtk/modules/bookings.json in the repository — the page reads its opening hours from there, through the kit's door (site.module('bookings')) — and the price list is the same services entries the form reads.

Seed the hours in the commit. jtk/modules/bookings.json is read by the import (push_code's push, or import_branch) into the diary's settings, and publish makes them what the preview offers: a demo takes bookings with nobody opening the panel. The owner changes them in the diary afterwards, and the next publish writes them back to the file — one place, edited from either side. Until the first publish the settings are a draft: the setting up already counts them (the launch publishes them), a visitor does not see them yet.

The file is the module's own document, and its shape is the one publish writes: v, and the settings under settings, every row of a list with its _key (the files under jtk/ and modules have every field). jtk create --kit lays it out, and npx @jtakeit/astro schema seeds an empty one when the schema turns bookings on and the file is missing:

json
{
  "v": 1,
  "settings": {
    "zone": "Europe/Warsaw",
    "hours": [{ "_key": "mon", "day": "monday", "opens": 540, "closes": 1020 }],
    "horizon": 30,
    "confirm": "auto",
    "payment": "full"
  }
}

Written any other way — the settings as top-level keys is the mistake that has actually been made — the file is refused (JTK_E_DOCUMENT_INVALID), by the import and by validate_schema, so the diary is never imported empty and then written back empty over the seed. Send the file in validate_schema's files before the push, and it is judged with the schema.

On a contract-2 site the settings are jtk/bookings.json: a document of one block of type bookings_config, the settings as the block's fields — {"blocks": [{"type": "bookings_config", "v": 1, "zone": …}]} — refused in any other shape with JTK_E_MODULE_FILE_INVALID. jtk upgrade contract-3 moves it to jtk/modules/bookings.json.

What is booked is in every language, always. On a site in several languages a service, a master, a class — any entry of a collection the module names — is offered in every language's form, in the original's words where nobody translated it: its collection cannot say untranslated: "hide", and its translation cannot hold it back (a site in several languages). The diary reads the original, so the form names a service by the original's slug (entry.baseSlug), whatever a language calls it.

The validator says both as advice rather than a refusal: JTK_W_MODULE_POST and JTK_W_MODULE_TWIN, under advice in validate_schema's answer, once nothing is refused. Act on them before the first build; they are what the studio would otherwise say after opening the panel.

Prove it without a browser. preflight with try_booking walks the visitor's path under your own session — on the preview before the launch, on the address after: the ticket is exchanged for a cookie, a free slot of the first service a visitor can book — shown, in the site's own language, with a length (takes) and somebody who performs it — is booked through /api/book, and the booking is cancelled again. A booking made under a session that may view the site is a test row, which is why it pays no Turnstile and never reaches the business as a customer's; it is booked under an address on .invalid, so no letter goes and the business is not told of it.

And the whole chain, on the server. preflight with self_check has the server walk a booking through what the owner and the customer do, on the build published now: booked as a visitor and checked against the kit's rule, confirmed, refused, moved by the owner, another time offered and accepted, «it suits», moved and cancelled by the customer, cancelled by the owner, the time free again — every letter written by the code that sends it and read for holes, empty fields, another kind's words and the site's language. Its rows are seen by nobody and told to nobody, and deleted when it ends. A site that takes bookings is not ready until it has passed on the build published now; the brief has the steps, and what it leaves to a person: the form's script, a letter's delivery, the payment.

It books in the shape your form sends, read off the built page: the form marked data-booking on the booking page (page in the bookings' settings) lists the fields it posts in data-sends, and nothing else is sent. It is one list separated by commas — data-sends="service,start,name,phone,email,note"; written with spaces or as a JSON array it is not read, and the check says so before anything is booked. A rate taken several at once is booked for more than its fewest, a site that takes parties for two. So a form that sends units for nights is refused by the edge, and one that never sends count where a stay is one to thirty nights fails before anything is booked. The form from npx @jtakeit/astro create says it and sends nothing it does not say; a form written by hand must list its fields in data-sends, or the check fails as NOT CHECKED — a booking made the platform's way would prove nothing about your form.

Several nights, or several hours, at once ​

A rate sold by the day — a night of a hotel, a day of a car — is taken several times in one booking, and so is a rate by the hour whose most is above one — a studio's hour, one to twelve. The page asks how many with count: on the availability (&count=4) and in the booking's body ("count": 4), the same number on both, so the times offered are the ones a stay that long fits. The platform makes the end and the price from it — the rate's takes and costs times count, and on a business by the day the letting runs from the hand-out hour to the hand-back hour — and never takes either from the page.

  • Absent, it is the rate's fewest. Outside its fewest…most the answer is 400 with the range in the sentence. A visit of several services is taken once. Each service's fewest and most are in the availability answer's services; by the hour, ask «how long» only where most is above one.
  • There is no units, nights or days, and "count": "4" is not 4. Sent from a preview or under the studio's session, either is refused with JTK_E_BOOKING_FIELD_UNKNOWN; from a stranger it is dropped and the stay is booked at its fewest — one night, whatever the form said. Try the form once on the preview.
  • class books «any of this class» where no resource is named, for a business whose rates are sold in classes — a room type, a car class. The answer's resource says which one was given, and class the one promised. /api/availability lists the classes that can be asked for in classes, and a class nothing is in yet — a room type with no room — in empty_classes: say it and do not let it be chosen. Asked anyway, it has no free day, ever.
  • A service nobody performs — a salon's service no master does — is still in services, and is named again in empty_services: say it and do not let it be chosen, the same way. Asked anyway, it has no free time, ever.

A price by the hour of the week ​

A service whose price depends on the day and the hour carries rates instead of costs — never beside it, and the validator refuses both on one entry. Each row is a day, a from, an until and a costs, the same shape as a week of opening hours with a price on each row; a row whose until is before its from runs past midnight, as an hours row does.

jsonc
// jtk/entries/services/bahn.json
{ "id": "0193a5c3-…", "collection": "services", "slug": "bahn", "visible": true,
  "fields": { "title": "Bahn", "takes": 60, "most": 4,
    "rates": [
      { "_key": "fr1", "day": "friday", "from": 540,  "until": 1200, "costs": { "minor": 2500 } },   // 09:00–20:00
      { "_key": "fr2", "day": "friday", "from": 1200, "until": 60,   "costs": { "minor": 4200 } }    // 20:00–01:00
    ] } }

(On a contract-2 site the same entry is a block of its type with costs a bare number of minor units, 2500.)

  • A business open past midnight writes the hours after it on the calendar day whose clock shows them, not as a continuation of the night before: a lane 32 € from 01:00 to 03:00 on a Saturday night is a row for sunday, from: 60, until: 180. A row whose until is before its from (friday 1200 → 60) is the one other shape, for a span that starts before midnight; time_of_day never goes past 1439. A unit is priced by the row of the weekday its start falls on — a bar's 00:30 on Saturday is Saturday's row, or Friday's row running past midnight if there is one.
  • Each unit is priced by the row covering its start, and the booking is the sum. A lane sold by the hour (takes: 60) booked Friday 18:00–21:00 at a before-eight and an after-eight price is two hours at one and one at the other. Not a share by the minute, and not the first hour's price for the whole.
  • The price is the slot's. Every slot in the availability answer carries costs_minor, the full price of the booking starting there for the service and the count asked about — for a flat price too, so a form has no mode to know: print the slot's price beside the chosen time whenever one came. prices is 0 for a service priced by time, because it has no price until a time is chosen; the list of services says «from …» from the rows.
  • An open hour no row covers is not sold. The form is not offered it for this service, a page of its own that asks for it is refused with that time has no price, and the panel says which hours those are, beside the rate — a table copied from a website has a gap somewhere, and this is where it is found rather than by a customer who could not book Tuesday noon. Write the whole week; the panel's list editor is made for ten rows.
  • Two rows on one minute of one day are refused, by the validator before any build and by the import, with both rows named. A price two rows claim is a price nobody can explain to the person charged it.
  • The deposit, the frozen amount, the class. The share is taken of the sum as it is of costs × count; the line on the booking says the sum of its units and is never read from the table again; a class's costs on a letting business outranks the rows as it outranks costs.

The kit's renderBookingForm says «from …» beside a service with rows (pass rates with the entry's other fields) and <jtk-booking> prints the slot's price beside the time; a site's own form reads costs_minor off the slot or ignores it and books exactly what it books today.

What a price depends on ​

A unit's price is the service's table at the unit's moment of the week (costs, or rates), and two more things the same table takes:

  • The unit's index in the booking. A rates row may say which units it is for — from_unit and until_unit, counted from one, until exclusive, open when absent. The club's billiards on a Friday night is three rows on one span: 16 € for any hour, 14.40 € for the second (from_unit: 2, until_unit: 3), 12.80 € from the third (from_unit: 3). The most specific row wins; two rows of one window on one minute are refused as two prices. Absolute prices, never percentages: the row says the number the till charges.
  • The party. A service may say per: "person": its price is times the party — a class per place, a tour, a tasting. Without it, booking: a haircut is one head whatever the party says. In a group each row's share of the party is what its price is times.
  • An add-on: a service with a price and no takes — shoes, a racket, a towel. Taken only beside a timed service in one visit (combine on), priced once per visit, times the party when per: "person"; alone it is no service. The validator advises an add-on on a site whose visits take one service — JTK_W_UNPRICED_HOURS's neighbour, JTK_W_ADDON_ALONE.
  • A package is a service: Late Night, two hours for 45 €, is takes: 120 with rates rows covering only the late window.

Not a price: a percentage, a discount for three lanes, a member's price, a no-show fee (a policy after the fact — the deposit does its work in advance). Seasons by date are the next key on the row, when a hotel asks.

Several of a class in one booking ​

Three lanes for a birthday, two rooms for a family, two cars for a crew: a booking is one resource, and several of a class are a group — the rows one request made, sharing a party, a payment and a page. The owner allows it in the booking settings (Most in one booking, quantity; one by default, and the form never asks). The availability answer carries it as quantity_max, and a slot's free says how many are free there.

  • Send quantity on POST /api/book with a class (or nothing — any of all). Never with a resource named by slug: a name is one thing, and «lanes 2 and 5» is «any two» or two requests. Never on a session (spots): its places are the party.
  • The party is asked once, as now, and seated across the chosen resources: the set that seats it with the least seats over, each row keeping the share seated on it. Fewer free than asked is no booking: 409 {"error": "only 2 free then", "free": 2}, with the number so the form can offer two.
  • The answer is the first row's, as it always was, plus group: { id, quantity, party, bookings: [{ id, resource, resource_name, amount_minor, party, state }], amount_minor } — the sum. A page built before the group reads what it always read and books one.
  • Paid together: /api/pay under the first row's id takes the group's sum, and every row is marked paid. Each row keeps its own price, so one lane cancelled alone is refunded alone.
  • One page, one letter, one reminder. The visitor's page under any row's token lists the group and offers to cancel one or all (POST /api/booking/cancel with "all": true); rows that start together move together. The letters name every lane.

The kit's form draws «How many» when quantity_max is above one, bounded by the chosen slot's free, and the receipt says the lanes and the sum.

Four businesses, one module ​

The module reads three more keys from a resource's card — does, seats, spots — and one from the settings, party, and with them it is a workshop, a consultant, a class or a restaurant without a second module (modules says each in one line). The schema reference carries one worked schema per business, judged by CI: copy the one that matches and change the words.

businessservicesresourcesthe visitor is asked
a workshop of masterseach with takes, costseach master with hours and does — what they perform; empty is everythinga service, then any master who does it or a named one
a consultanteach kind of meetingone resource with hoursa kind of meeting and a time
classesone per kind of class, takes the session lengthone per timetable, with spots and hours naming the sessions; a resource with spots offers the start of each row and nothing in betweena class, a session, and how many places
a restaurantone, a table, takes the turn timeone per table with seats; the business's hours are the service periods, lunch and dinner as two rowsa day, a time, and how many — the smallest table that seats them is theirs

seats and spots are two kinds of resource: a table takes one party that has to fit, a class takes as many bookings as it has places. A card that claims both is refused, and so is a party larger than the settings allow.

The form, by default — the rules a visitor needs ​

The kit's element (@jtakeit/kit 0.5 and later) draws these over the form, and a form drawn by hand keeps them: each one is something a visitor ran into on a real salon's page (10 October 2026) and should not run into again.

  • Two steps: what and when, then who is coming — the choice summarised beside the name (what, with whom, when and until when, how long), a way back.
  • The day as a week of seven from today, closed days struck out, never yesterday: the floor is the browser's today in the browser's own day, not the build's and not UTC's.
  • The times by the part of the day, one part at a time, each tab saying its hours; a part of one or two times joins its neighbour.
  • A master chosen greys out the services they do not do («not with Noa») and unticks them; Anyone brings them back. The resources carry does for this.
  • A time picked stays picked across a change of services if it is still offered; otherwise a line says the visit is a different length now.
  • The end of the visit under the times, from the answer's ends.
  • A 24-hour clock in every language; the markets do not read «11:15 AM».
  • The success shows the link whole, with Copy, and says to keep it — it is the booking's only key. The visitor's page wears the site's clothes (/_jtk/booking.css, the visitor's page).
  • The Turnstile widget in the page's colours and language, not the browser's.
  • The hint says what is missing — a service, a day — never an error body.

The form is the site's, not the kit's ​

The scaffold's src/components/BookingForm.astro is a working base to copy and design: the whole form written out, every field, with the scaffold's look in a <style> beside it, and the behaviour from the kit's <jtk-booking> element. The markup, its classes, its order and its look are the site's. A form that looks unlike the page it is on is the first thing a studio notices, so before it goes out:

  • dress it in the site's design — the same fields and buttons as the contact form, the site's panel around it; rename the classes, wrap the fields, put the contact fields in a row, as the design needs;
  • keep the hooks: the element finds every part by a data-* attribute or an input's name, never by a class (@jtakeit/kit/booking/hooks; the scaffold's docs/booking.md lists them). The rules the behaviour needs — [hidden], which step shows, the ARIA — the element puts on the page itself;
  • put it on the page where the site sends people to book, beside the list of what can be booked.

The pieces the element draws itself — a button per free time, the week of days, the parts of the day, the two steps — carry booking__* classes to style, with their state in ARIA (aria-pressed="true" is chosen).

preflight with try_booking reads the built page: a form that lacks a hook, or a field this business's answer asks for (a party, a second date), fails before anything is booked. A finished site to read shows the base copied and dressed on a real design.

What the customer is told — and the known limits ​

The customer hears of a change to their booking by email, and in Telegram where they linked it: a yes, a refusal, a cancellation, a move — of the time, the length or the master — and another time offered. The owner chooses, in the window that asks, whether the customer is told; a move not told still leaves the reminder, at the new time, and the window says so. A booking the owner wrote down by hand gets no letter, only the reminder, by its email. The letters and the customer's page speak the site's language (the words a booking may say). Every letter goes out in the business's name — From «<the site's name> via jtakeit», the business's name large at the top, no colour or logo of the site — and an answer to it goes to the business's own email: the shared text's field with the role email, or the business fact email. A site that gives neither sends its letters with no address to answer to, so set it in the brief.

What is not told, and is known — say it to the owner rather than promise it:

  • a change of the service alone is shown on the customer's page and in every later letter, with no letter of its own;
  • «відбулося» and «не з’явився» are written down and shown on the page; no letter goes;
  • a booking of several — one per resource, in a group — is told row by row: one letter per row;
  • an offer withdrawn without telling still reads as withdrawn on the customer's page;
  • the price is in no letter and not on the page: a move to a time priced differently is settled with the customer by the owner;
  • the customer's language is not kept: every letter speaks the site's.

A test booking's letter can be sent at once rather than when it is due — POST /v1/sites/{site_id}/bookings/{booking_id}/notice with {"notice": "reminder"} (or received, confirmed, …) — through the API only: no screen of the panel offers it, and a live booking's is refused.

And on the panel: every change to a booking reaches an open diary at once — made, moved, decided, cancelled, answered, forgotten at the end of its retention — except the money: a booking confirmed by its online payment, and a refund, are shown when the screen next reads the diary (a reload, or the next change), not the moment the payment lands.