Booking API course · updated 2026-10-05
Lesson 1: what the Booking API is and how the pieces fit
Before the first call, understand the shape of the system. The Booking API is a thin, open door to the same engine that powers the hosted booking page and the widget. You build the screens; the server prices, validates, screens and creates. This lesson gives you the mental model that makes every other lesson obvious.
Before you start
- A Dumpster Controls account with an admin login
- Online Booking switched on, Stripe connected, at least one active dumpster size (or junk load price)
- ## Three ways to take orders, one engine
Every company can take paid orders online in three ways: the hosted page (dumpstercontrols.io/book?company=slug), the widget (two lines of HTML on any site) and the Booking API (your own screens). All three call the same server functions, apply the same rules and create the same order. The API only removes the screens; it never removes a rule. - ## The flow in one paragraph
Your page reads the company profile and sizes (GET /company, GET /sizes), shows closed days (GET /availability), validates the customer's choices (POST /check), prices the rental (POST /quote), starts the order and gets a Stripe client_secret (POST /intents), takes the card inside the Stripe Payment Element on your page, and confirms the order (POST /confirm). From then on the company sees the order on its dispatch board, the customer gets the confirmation email and SMS, and your site can be told by a webhook (booking.completed). Junk removal has the same shape under /junk/*. - ## What the server decides, always
Prices by rental length, tax and fees come from the company's account and are recomputed before the payment intent is created; the API never accepts a price from the client. Booking switched on, Stripe ready, closed days, service area, promo validity and commercial-account emails are checked before any payment. Every card payment runs through Stripe Radar; in the United States suspicious orders are held for manual review (state held). Refunds and cancellations are not in this API. - ## Vocabulary
session_id: your idempotency id for one booking attempt (you can send it, or the server generates one). payment_intent_id: the Stripe PaymentIntent created by POST /intents. client_secret: the value your page gives to Stripe.js to mount the Payment Element and confirm the card. state: intent_created, confirmed, held, unconfirmed or failed. order_number: the human number of the created order, the same the company sees in the app. total: what the company invoices; gross_total: total plus the processing fee the customer pays under the company's card fee handling. - ## Where everything lives
Base URL: https://gcwyoiihrupbfqqlcurh.supabase.co/functions/v1/booking-api/v1
Keys and allowed domains: in the app, Online Booking, Developers tab.
Reference pages: https://dumpstercontrols.io/developers/booking (widget) and https://dumpstercontrols.io/developers/booking/api (API). Spec: https://dumpstercontrols.io/openapi-booking.json. Both pages have a markdown twin for AI tools: add .md to the URL.
What happens next
- Keep this page open: lessons 2 to 10 go call by call, and lesson 11 is a complete working example you can paste.
Troubleshooting
I only want to show prices on my site, not take orders. Is the API still the right tool?
Yes. GET /sizes and POST /quote are enough, and you can link the customer to the hosted page or the widget for payment. The quote the API shows is exactly what the hosted page charges.
The quote on my screen differs from the hosted page for the same size and dates.
Check the material. A company that prices by material charges the material price; the hosted page and your screen only match when both name the same material (lesson 15). Without a material you get the general price.
Related guides
- Lesson 2: keys, allowed domains and authentication
- How to get online booking on your website three ways in Dumpster Controls
© 2026 Dumpster Controls. All rights reserved. Made in the USA.