Concepts

Studio and site

A studio is a business with one or more rooms. When the studio turns its website on, it has a site: a template, theme, texts, legal pages and a canonical host — slug.sites.mrcharles.app by default, or a verified custom domain.

The slug (e.g. studio-uno-madrid) is the public identifier you use on every public endpoint. Find it in the studio dashboard → Website, or in the hosted site’s URL.

A site must be live to be reachable publicly. A studio can only go live after ownership verification (tax id, phone code, business document — reviewed by a person). Until then every public call answers 404 SITE_NOT_LIVE.

Room and booking policy

Each room carries its online policy, set by the studio:

Field	Meaning
`bookable`	Online booking is on and the room is priced, active and has hours
`hourlyCents`, `currency`	Price per hour, minor units (`2000` = €20.00)
`minMinutes`, `maxMinutes`, `stepMinutes`	Allowed durations, e.g. 60 / 480 / 30
`paymentModes`	`card` (deposit now, Stripe) and/or `on_site` (pay at the studio)
`depositPercent`	Share of the price charged now when paying by card
`cancelNoticeHours`	Guests may self-cancel up to this many hours before the start

Availability also depends on the room’s own schedule (or the studio’s opening hours), buffers between bookings, the minimum notice and the booking horizon — all returned with the availability payload.

Hold

A hold is a slot reserved for 12 minutes for a named guest with a contact channel (phone or email). Creating a hold sends a one-time code to that contact. The hold blocks the slot for everyone else while the guest verifies.

pending ──verify code──▶ verified ──confirm──▶ confirmed (a booking exists)
   │  5 wrong codes · 12 min                 │  12 min
   ▼                                         ▼
cancelled / expired                       expired

Booking

Confirming a verified hold creates a booking with a reference MC-XXXXXX, times in UTC and in the studio’s time zone, the price and deposit, the chosen payment mode and a payment status:

`paymentMode`	`status` after confirm	`paymentStatus`
`on_site`	`confirmed`	`unpaid` → studio marks `paid`
`card`	`pending_payment` → `confirmed` by webhook	`pending` → `paid`

A card booking that is not paid within 20 minutes is cancelled by the system and the slot is freed.

Manage link

Every booking comes with a manage token (32 random bytes, shown once, also sent to the guest). With it the guest can see the booking and cancel it while inside the cancellation window. Keep it like a password: it is the only credential a guest has.

Time and money conventions

Dates are YYYY-MM-DD and times HH:MM in the studio’s time zone (timezone, IANA name). Absolute instants (startsAt, expiresAt) are RFC 3339 in UTC.
Money is always integer minor units + ISO 4217 currency. Never send prices; the API computes them.
IDs are UUIDs. References (MC-…) are for humans.