What the booking widget does
The widget renders inline on the host page, inherits its font and color scheme by default, and submits new requests to your Simple Scheduler workspace over HTTPS. No customer data is stored in the browser; the widget posts directly to our API and the request shows up in your dashboard within seconds.
The one-line embed
Paste this single script tag anywhere in your page, ideally just before the closing body
tag. The script auto-mounts the widget into the element with id="simple-scheduler-booking":
<div id="simple-scheduler-booking"></div>
<script async src="https://simplescheduler.com/embed/booking.js"
data-widget-key="ws_live_abc123"></script>Replace ws_live_abc123 with the public widget key shown in Settings, Booking widget. The key is not a secret; it is
scoped per workspace, rate-limited, and meant to live in client HTML.
Within about one second of page load the widget mounts a small calendar, a service dropdown, and a customer-info form. There is nothing else to install: no NPM package, no build step, no React or jQuery requirement.
Iframe fallback
If your site's Content Security Policy blocks third-party scripts, or if you want the widget to live on a standalone page (a Webflow CMS item, a WordPress page, a Squarespace block), use the iframe form instead:
<iframe
src="https://simplescheduler.com/embed/booking?widget=ws_live_abc123"
title="Book an appointment"
width="100%"
height="720"
loading="lazy"
referrerpolicy="strict-origin-when-cross-origin"
></iframe>The iframe accepts the same query parameters as the script tag (documented below) and adapts its internal layout to the available width. A height of 720px fits the default flow on most desktops; for mobile, prefer a CSS aspect-ratio wrapper or let the iframe size to its container.
Configuration options
Every configuration option is passed as a query parameter on the embed URL (iframe form) or
as a data-* attribute on the script tag. The two forms are interchangeable; data-widget-key on the script tag is the same as ?widget= on the iframe.
| Type | Description | |
|---|---|---|
| widget | string (required) | Your public widget key from Settings, Booking widget. Format: ws_live_xxxxxxxx. |
| service | slug (optional) | Pre-select a service in the dropdown. Use the service slug shown in Settings, Services. |
| customer_email | string (optional) | Pre-fills the email field. Useful for deep-linking from a marketing email. |
| customer_name | string (optional) | Pre-fills the customer name. URL-encode spaces. |
| theme | light, dark, or auto | Defaults to auto (matches the host page's color scheme). |
| accent | hex color (optional) | Overrides the brand accent for a single page. Falls back to the workspace brand color. |
| locale | BCP-47 tag (optional) | Defaults to en-US. Currently supports en-US, en-GB, es-MX. |
Customizing the widget appearance
The widget inherits its font family from the host page and uses your workspace brand color as the accent by default. For pixel-level control, the widget exposes five CSS custom properties scoped to its mounting element:
#simple-scheduler-booking {
--ss-widget-accent: #0E3B47; /* primary buttons + focus rings */
--ss-widget-bg: #FAF7F2; /* widget surface */
--ss-widget-text: #1A2B33; /* body copy */
--ss-widget-muted: #5A6E76; /* secondary text */
--ss-widget-radius: 12px; /* corner radius on cards + inputs */
}Set any of these on a parent element and the widget cascades the new values. If you prefer
to skip CSS entirely, the theme and accent parameters cover most use cases.
For full theme inheritance (the widget tracks your light/dark toggle in real time), set theme=auto and the widget listens for prefers-color-scheme changes plus the standard data-theme attribute on the host's html tag.
Service catalog and time-slot configuration
The widget reads your live service catalog from Simple Scheduler. Every service tagged Bookable in Settings, Services appears in the widget dropdown. Hide services that should not be offered through the widget (consultation-only quotes, for example) by untagging Bookable.
Time slots are computed live against:
- The selected service's default duration and required crew size.
- Your crews' working hours (Settings, Crews).
- Already-booked appointments on the calendar.
- Time-off entries for individual teammates.
- An optional buffer per service (defaults to 0 minutes).
Slot granularity defaults to 30 minutes. Workspaces that prefer 15 or 60-minute increments can change the global setting in Settings, Booking widget, slot increment.
Pre-filled customer info (deep-linking)
For email campaigns and re-booking flows it is useful to drop a customer into the widget with their email and name already filled in. Append URL-encoded query params:
https://simplescheduler.com/embed/booking?widget=ws_live_abc123
&service=weekly-clean
&customer_email=alice%40example.com
&customer_name=Alice%20WongPre-filled values are not authenticated; treat them as hints, not identity claims. The widget verifies the email address on submit via a single-use confirmation link. If you need true authenticated re-booking (already-known customers with no email roundtrip), use the customer portal at /features/customer-portal instead.
Privacy and GDPR
The widget collects only the data needed to schedule the appointment: name, email, phone
(optional), service address, and any notes the customer types. No third-party analytics or
advertising trackers are loaded; the only network calls are to simplescheduler.com.
For sites operating under GDPR, the widget can be configured to show a consent checkbox before submission. Enable it in Settings, Booking widget, GDPR consent, and edit the consent copy and the link to your privacy policy. See our privacy policy for the upstream handling of submitted data.
The widget never sets cookies on the host domain. A short-lived session cookie on simplescheduler.com is used to deduplicate rapid resubmits; it is first-party to our domain and is removed when
the customer closes the tab.
Troubleshooting
- Widget does not render. Open the browser console and look for a 401 or
403 from
simplescheduler.com/embed/. The most common cause is the wrong widget key, or a key that was rotated in Settings without updating the embed snippet. - No time slots offered. Confirm that at least one crew has working hours overlapping the next 14 days and that the selected service is tagged Bookable. A blank slot list with a green badge is almost always an availability configuration issue, not a widget bug.
- Widget looks unstyled. The host page's CSS reset is overriding the
widget's base font size. Scope the reset to your own selectors, or set
#simple-scheduler-booking, #simple-scheduler-booking *toall: revert-layer. - Submissions never arrive. Check the network tab for the request to
/embed/submit. A 200 response means the request landed in your workspace; visit Pending requests in the app. If the response is 429, you have hit the per-IP rate limit; this protects against form spam and clears in a few minutes. - Confirmation email never arrives. Confirmation emails send through Resend from the workspace's verified sending domain. Check the spam folder, and confirm that your sending domain is verified in Settings, Email.
FAQ
- Yes. The widget is included in every Simple Scheduler plan, including the free trial. There is no per-booking fee, no traffic cap, and no add-on charge for the embed; you pay only for your team seats.
Was this helpful?