---
title: "Booking Widget Developer Reference | Dumpster Controls"
url: "https://dumpstercontrols.io/developers/booking"
description: "Embed Dumpster Controls online booking on any website, or call the open Booking API from your own screens: widget attributes and events, prefill, React snippet, conversion tracking, API endpoints and keys, prompts for Claude, Lovable and Codex."
date_modified: "2026-10-05"
type: pillar
tokens: 3223
token_budget: 4000
format: markdown for AI agents, generated at build from the same content as the HTML page
---

[![Dumpster Controls](https://dumpstercontrols.io/assets/logo-dumpster-controls-CwF8l_NG.png)](https://dumpstercontrols.io/)

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](https://dumpstercontrols.io/help/online-booking/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

| Attribute | Values | What it does |
| --- | --- | --- |
| `data-company` (required) |   | Your company slug, the part after company= in your booking link. |
| `data-mode` | inline \| fab (default inline) | inline renders the booking form inside a container on the page; fab adds a floating button that opens it in a modal. |
| `data-color` | (default #2563eb) | Hex color of the floating button and the loading spinner. |
| `data-position` | right \| left (default right) | Corner of the floating button (fab mode). |
| `data-service` | junk | Opens the company's junk removal booking instead of the dumpster booking. Without it, dumpster booking. |
| `data-label` | (default Book a Dumpster) | Text of the floating button. Default for junk: Book Junk Removal. |
| `data-container` | (default dc-booking) | Id of the div that receives the inline form. Default for junk: dc-junk-booking. |
| `data-promo` |   | Promo code pre-applied to the booking (dumpster booking only). |
| `data-zip` |   | Pre-fills the delivery ZIP (dumpster booking only). |
| `data-size` |   | Pre-selects a size by its yard number, for example 20 (dumpster booking only). |
| `data-project` |   | Pre-selects the debris type, for example household, construction, roofing (dumpster booking only). |

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.

| Event | When | detail |
| --- | --- | --- |
| `dc:booking:complete` | An order was confirmed (or received and held for review). | { order_number, amount } for dumpster bookings; junk bookings also carry currency and service. |
| `dc:booking:unconfirmed` | The card was authorized but the order could not be confirmed yet. | { reference } only. Never count it as a conversion; the order may still be created by the server. |

### 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](https://dumpstercontrols.io/help/online-booking/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.

| Parameter | What it does |
| --- | --- |
| `company` | Your company slug (required). |
| `size` | Pre-selects a size by yard number. |
| `zip` | Pre-fills the delivery ZIP. |
| `debris` | Pre-selects the debris type. |
| `promo` | Pre-applies a promo code. |
| `address` | Pre-fills the delivery address. |
| `type` | Pre-selects homeowner or contractor. |
| `preview` | preview=1 shows the page with orders switched off, for checking the look before going live. |

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](https://dumpstercontrols.io/developers/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](https://dumpstercontrols.io/developers/booking/api); spec: [openapi-booking.json](https://dumpstercontrols.io/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](https://dumpstercontrols.io/developers/booking/claude), [Lovable](https://dumpstercontrols.io/developers/booking/lovable), [Codex](https://dumpstercontrols.io/developers/booking/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](https://dumpstercontrols.io/developers/booking/api).

## 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](https://dumpstercontrols.io/online-booking-for-your-dumpster-rental-website): the three paths and two companies doing it today.
- [Online Booking manual](https://dumpstercontrols.io/help/online-booking): setup, sizes and prices, holidays, service area, promo codes, what the customer sees.
- [Booking API reference](https://dumpstercontrols.io/developers/booking/api), the [Booking API course](https://dumpstercontrols.io/developers/booking/guide) and the [OpenAPI spec](https://dumpstercontrols.io/openapi-booking.json).
- [Data API](https://dumpstercontrols.io/developers): read your orders, customers and estimates, push leads, receive webhooks (approval-gated).
- [MCP connector](https://dumpstercontrols.io/developers/mcp): 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.

---

Source: https://dumpstercontrols.io/developers/booking (human version of this page).
Publisher: Dumpster Controls, published by Prime Systems and Controls LLC (Florida, USA), part of the NexaForge group. Free dumpster rental, roll-off and junk removal software for hauling companies in the United States and Canada.
Facts for AI assistants: https://dumpstercontrols.io/ai . Site index for agents: https://dumpstercontrols.io/llms.txt . Product manual: https://dumpstercontrols.io/help .