Developers

Online booking widget: developer reference

Last updated: October 5, 2026

The Dumpster Controls booking widget puts the complete online booking of a dumpster rental company inside any website: sizes with live prices, dates, address check with a placement pin, promo codes, rental agreement and Stripe card payment, with the order landing on the company's dispatch board already paid. This page is the contract: every attribute, event and parameter the widget supports today, plus the prompts that let Claude, Lovable or Codex do the integration. The non-technical walkthrough is in the manual: embed the booking widget on your website.

Three integrations are supported: the hosted page (a link), the widget (an iframe your page loads) and the Booking API (your own screens calling the engine, below). All run the same engine. Included free on every plan; the only cost is card processing when a customer pays by card.

Install in 2 minutes

1. Create a free account, add your dumpster sizes and prices in Inventory, connect Stripe and switch online booking on.
2. Open Online Booking, Install Widget, and choose the format: the form on your page (inline) or a floating button (fab).
3. Copy the code. It already carries your company slug and brand color.
4. Paste it where the booking should appear: an HTML or Embed block, or a script element on React sites.
5. Book a test order, then add the dc:booking:complete listener for Google Ads or Meta Pixel.

Inline: the form on your page

<div id="dc-booking"></div>
<script src="https://dumpstercontrols.io/embed/dc-booking-widget.js" data-company="your-slug" data-mode="inline"></script>

Floating button that opens the booking

<script src="https://dumpstercontrols.io/embed/dc-booking-widget.js" data-company="your-slug" data-mode="fab" data-color="#2563eb" data-position="right" data-label="Book a Dumpster"></script>

Replace your-slug with your company slug. The inline form resizes itself to its content; the floating button loads the booking only when clicked.

Attributes

Both services can live on the same page: one script for the dumpster booking and one with data-service="junk" for junk removal, each with its own container or button position.

Events on the host page

The widget dispatches these events on window of your page. Listen for them to fire your conversion tags.

Conversion tracking example (Google Ads and Meta Pixel)

<script>
window.addEventListener('dc:booking:complete', function (e) {
  // e.detail = { order_number, amount }
  gtag('event', 'conversion', { send_to: 'AW-XXXXXXXXX/XXXXX', value: e.detail.amount, currency: 'USD', transaction_id: e.detail.order_number });
  fbq('track', 'Purchase', { value: e.detail.amount, currency: 'USD' });
});
</script>

Alternatively, set a Booking Confirmed Page URL in Online Booking, Advanced. After a confirmed order the customer is redirected to that page with these query parameters: email, phone, first_name, last_name, dumpster_size, delivery_date, pickup_date, order_number . Use them for Enhanced Conversions or to personalize the page. Manual: track Google Ads conversions.

React, Next.js, Lovable and other app builders

Insert the widget as a script element with the data attributes set on the element, inside the page that shows the booking. Never import the file as a module: it reads its own script tag.

useEffect(() => {
  const s = document.createElement("script");
  s.src = "https://dumpstercontrols.io/embed/dc-booking-widget.js";
  s.dataset.company = "your-slug";
  s.dataset.mode = "inline";
  s.dataset.container = "dc-booking";
  document.body.appendChild(s);
  return () => { s.remove(); };
}, []);
// and in the JSX of that page:
<div id="dc-booking"></div>

Hosted page and prefill

The hosted page is https://dumpstercontrols.io/book?company=your-slug. Link to it from any button, and pre-fill it with these query parameters; the widget attributes above map to the same parameters.

Junk removal has its own hosted page at https://dumpstercontrols.io/junk-checkout/your-slug and the same widget with data-service="junk".

What the engine enforces on the server

• Prices by rental length, tax and fees come from the company's account; the server recalculates every order.
• Closed days (holidays, blackout dates, weekly days off) and the service area radius are checked before payment.
• Promo codes are validated one at a time; the full list is never exposed.
• Every card payment runs through Stripe Radar; in the United States suspicious orders are held for manual review before capture.
• The customer gets email and SMS; the office gets email, SMS, push and an in-app alert. The order lands on the dispatch board already paid.

Booking API: your own screens, our engine

Need fully custom booking screens? The open Booking API exposes everything the hosted page does: sizes with live prices, availability, service area and promo checks, quotes, and the order itself with card payment through the Stripe Payment Element (POST /intents, then POST /confirm). No approval, included free, no usage window. The server prices every order and runs every booking rule. Keys and allowed domains live in Online Booking, Developers. Full reference, order flow, errors and the AI prompt: developers/booking/api; spec: openapi-booking.json.

Prompts for AI builders

Dumpster Controls is documented for AI builders: Claude, Lovable and Codex can integrate it from this page, and we publish the prompts. Replace the values in curly braces. Tool-specific steps: Claude, Lovable, Codex .

Build the whole site with online booking

Build a complete marketing website for my dumpster rental company. Company: {name}, {city, state}, serving {areas}. Sizes: {10, 15, 20, 30 yard} with starting prices {prices}. Services: {residential cleanouts, construction, roofing}. Phone {phone}. Tone: direct, local, no hype. Pages: home, sizes and prices, service area, about, contact, book online. For online booking, do NOT build a form or a checkout. Embed the Dumpster Controls booking widget exactly as documented at https://dumpstercontrols.io/developers/booking.md using my company slug "{slug}": inline mode on the "book online" page, and a floating "Book a Dumpster" button on every other page. Put a "Book online" button in the header that links to the booking page. Each size card links to the booking page with that size preselected. Mobile first, fast, accessible, with local SEO (title, description, schema.org LocalBusiness).

Add online booking to a site that already exists

Add online dumpster booking to this site using the Dumpster Controls widget. Read https://dumpstercontrols.io/developers/booking.md first and follow it exactly. My company slug is "{slug}". Create a /book page with the inline widget and add a floating "Book a Dumpster" button on the other pages. Do not build any form or payment step yourself; the widget handles pricing, dates, address and card payment. If this is a React or Next.js site, insert the widget as a script element with the data attributes set on the element, never as an import. Fire my Google Ads and Meta Pixel conversions from the dc:booking:complete event as documented.

For fully custom screens, the third prompt lives on the Booking API reference.

FAQ

Where do I find my company slug?

In Dumpster Controls, open Online Booking. Your booking link is dumpstercontrols.io/book?company=your-slug; the slug is the part after company=. The Install Widget screen prints the code with it already filled in.

Does the widget work on React, Next.js, Lovable or Webflow?

Yes. On HTML-based builders paste the snippet in an HTML or Embed block. On React and Next.js, and on builders that generate React such as Lovable, insert the widget as a script element with the data attributes set on the element, inside the page that shows the booking. Never import it as a module.

Can I test without taking real orders?

Open your hosted page with preview=1 (dumpstercontrols.io/book?company=your-slug&preview=1). It shows your real sizes and prices with orders switched off. A real test order can be refunded from Order History.

Can I build my own booking screens and only call a backend?

Yes, with the Booking API below: sizes with live prices, availability, service area and promo checks, quotes, and the full order with card payment (POST /intents, Stripe Payment Element, POST /confirm), from your own screens, with no approval. The server prices every order, runs every booking rule and the fraud screening, and creates the order on the dispatch board exactly like the hosted page does. Keys live in Online Booking, Developers.

Is there a fee for the widget or per booking?

No. Online booking, the hosted page and the widget are included on the free plan for any fleet size. The only cost is card processing when a customer pays by card through Dumpster Controls.

More

• Online booking for your dumpster rental website: the three paths and two companies doing it today.
• Online Booking manual: setup, sizes and prices, holidays, service area, promo codes, what the customer sees.
• Booking API reference, the Booking API course and the OpenAPI spec.
• Data API: read your orders, customers and estimates, push leads, receive webhooks (approval-gated).
• MCP connector: Claude working inside your Dumpster Controls account.
• Support: support@dumpstercontrols.io.

Page URL: https://dumpstercontrols.io/developers/booking. Machine-readable version: https://dumpstercontrols.io/developers/booking.md. Updated 2026-10-05.