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

Frequently asked questions

Is Dumpster Controls really free?

Yes. The software is free: dispatch, online booking, the driver app, invoicing, the Tresha AI assistant and every other feature, with no monthly fee, no trial period and no credit card to sign up. The only cost on the free plan is optional card processing when a customer pays by card through the platform: 2.99% plus $3.99 per transaction on the free plan. An optional Unlimited plan at $169 per month lowers that to 2.99% plus $0.30. Prices as published on dumpstercontrols.io/pricing on 2026-09-23.

Do you charge per driver, per truck or per order?

No. There is no per-driver, per-truck, per-user or per-order fee, and no order limit. A company with one truck and a company with twenty pay the same for the software: nothing.

Is there a contract?

No. There is no contract, no minimum term and no setup fee. You create the account yourself, and on the free plan there is nothing to cancel because nothing is billed. The optional Unlimited plan is billed month to month.

Which countries and languages are supported?

Dumpster Controls serves hauling companies in the United States and Canada. The app interface and the Tresha AI assistant are available in English, Spanish and Portuguese. The public pages, such as the blog, the help center and the landfill finder, are in English.

How do I switch from another dumpster software?

Create a free account at dumpstercontrols.io/login, with no sales call and no credit card. Then import your customers from a CSV file using the template provided in the app; past orders can also be imported from a CSV. Container sizes and pricing are set up in Settings. The landfill database, with 1,750 active US and Canadian landfills as counted on 2026-10-01, is already loaded, so disposal sites do not need to be typed in. Step-by-step guides are at dumpstercontrols.io/help.