---
title: "How to use the Booking API for your own booking screens in Dumpster Controls"
url: "https://dumpstercontrols.io/help/online-booking/use-the-booking-api-for-your-own-booking-screens"
description: "The Booking API lets a developer build custom booking screens on your website and call the Dumpster Controls engine for sizes, live prices, availability."
date_modified: "2026-10-05"
type: help
tokens: 2328
token_budget: 2000
format: markdown for AI agents, generated at build from the same content as the HTML page
---

Online Booking · updated 2026-10-05

# How to use the Booking API for your own booking screens in Dumpster Controls

The Booking API lets a developer build custom booking screens on your website and call the Dumpster Controls engine for sizes, live prices, availability, service area and promo checks, and quotes. It is included free on every plan, with no approval. Your keys live in Online Booking, Developers.

## Before you start

- Online Booking switched on, with Stripe connected and at least one active dumpster size
- An admin account (only admins see and manage the keys)
- A developer, or an AI coding tool, to call the API from your site

1. ## Open the Developers tab
  In "Online Booking", click the "Developers" tab (the last one). The section "Open Booking API: your keys" shows your publishable key, your allowed domains and the server key controls.
2. ## Copy the publishable key and add your domain
  The publishable key (dc_pk_live_...) is meant to go in your website, so it is public by design: it only identifies your company, and prices, dates and payments are enforced on our servers. Under "Allowed domains", add your website (for example https://yourcompany.com) and click "Add". Browser calls with the publishable key are accepted only from those domains.
3. ## Need to call from your backend? Create a server key
  Click "Create server key". The key (dc_sk_booking_...) is shown once; copy it and keep it out of client code. You can have up to two active and revoke any of them.
4. ## Send a test quote
  Click "Send a test quote". The app calls the API with your publishable key: your sizes, then a 7-day quote for the first one. The JSON answer appears on the screen. Nothing is created or charged.
5. ## Call the endpoints from your site
  Base URL: https://gcwyoiihrupbfqqlcurh.supabase.co/functions/v1/booking-api/v1 with the header Authorization: Bearer dc_pk_live_... (browser) or dc_sk_booking_... (server).
  ```
  GET /company (profile and booking status)
  GET /sizes (sizes with live prices)
  GET /availability?from=YYYY-MM-DD&to=YYYY-MM-DD (closed days)
  POST /check (delivery_date, zip, promo_code)
  POST /quote (size_id, rental_days, promo_code)
  POST /intents (the full order and customer: the server prices it, runs every rule and creates the Stripe PaymentIntent)
  POST /confirm (session_id, payment_intent_id: creates the order after the card is confirmed)
  GET /sessions/:id (state of a session)
  ```
  The full reference with request bodies, responses, the order flow and error codes is at dumpstercontrols.io/developers/booking/api, and the machine-readable spec at dumpstercontrols.io/openapi-booking.json.
6. ## Take the payment on your page and confirm the order
  After POST /intents, your page mounts the Stripe Payment Element with the client_secret and the publishable key from the response (for Canadian companies also the stripe.account), confirms the card with Stripe.js, then calls POST /confirm with session_id and payment_intent_id. The order lands on your dispatch board already paid, the customer gets the email and SMS, and the office gets its alerts, exactly like a booking from the hosted page. If the customer closes the page between the card and the confirm call, call POST /confirm again with the same session_id and payment_intent_id (it is idempotent) or poll GET /sessions/:id. Nobody is charged without an order: the authorization is only captured when the order is created, and an authorization that never becomes an order is released or expires on its own. Within about 15 minutes of an authorized card without an order, the customer and the company are told by email and SMS so the office can finish it by hand.
7. ## Webhooks: get told when an order lands
  In the same Developers tab, under "Webhooks", add an https URL of your site or CRM and pick the events: booking.completed (order created and confirmed), booking.held (received, under manual review) and booking.released (a held order approved). The secret (dcwh_...) is shown once; every delivery is signed with the X-DC-Signature header exactly like the data API, so the verification code in "How to verify webhook signatures" applies. Up to three endpoints; an endpoint is switched off after 20 consecutive failures and you get an email.
8. ## Materials with their own prices (optional)
  If you charge a different price for the same dumpster depending on the material (clean concrete, asphalt, soil), configure it in Inventory, Materials, and turn on the switch "Pricing by material" at the top: it is off by default, and until you turn it on every material costs the size price. Once on, GET /materials lists your materials, which sizes accept each one and the material price per size; your developer sends material to POST /quote and POST /intents and the server prices the order by it. The order and the invoice line show the material. There is no API endpoint to create or edit materials: the API reads what you configured in the app. Lesson 15 of the course has the details, and the Inventory article "How to charge a different price by material and limit heavy materials to certain sizes" covers the screen.

## What happens next

- Rotate the publishable key any time with "Rotate"; the old one keeps working for 24 hours so your site never breaks.
- Limits: 120 requests per minute per key and per IP, on every plan. No daily window.
- The "Prompt 3" in the Developers tab tells Claude, Lovable or Codex to build these screens with the API, with your publishable key and domain already filled in.

## Troubleshooting

### The API answers origin_not_allowed.

The page calling it is on a domain that is not in your allowed domains. Add the exact origin (https plus the domain) under "Allowed domains".

### The API answers unauthorized from my server.

Server calls need a server key (dc_sk_booking_...), not the publishable key. Create one under "Server key".

### Can the API change my prices?

No. The keys only read what the public booking page shows and ask for quotes. Prices, dates, promo codes and payments are decided on our servers.

## Related guides

- [Lesson 1: what the Booking API is and how the pieces fit](https://dumpstercontrols.io/help/booking-api/lesson-1-what-the-booking-api-is-and-how-the-pieces-fit)
- [Lesson 9: junk removal with the Booking API (/junk/*)](https://dumpstercontrols.io/help/booking-api/lesson-9-junk-removal-with-the-booking-api)
- [How to embed the booking widget on your website in Dumpster Controls](https://dumpstercontrols.io/help/online-booking/embed-the-booking-widget-on-your-website)
- [How to build your dumpster rental website with AI and connect online booking in Dumpster Controls](https://dumpstercontrols.io/help/online-booking/build-your-dumpster-rental-website-with-ai)
- [How to get online booking on your website three ways in Dumpster Controls](https://dumpstercontrols.io/help/online-booking/integrate-online-booking-into-your-website-three-ways)
- [Verify webhook signatures (HMAC)](https://dumpstercontrols.io/help/api/verify-webhook-signatures)
- [How to charge a different price by material and limit heavy materials to certain sizes](https://dumpstercontrols.io/help/inventory/charge-a-different-price-by-material)

© 2026 Dumpster Controls. All rights reserved. Made in the USA.

## 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.

---

Source: https://dumpstercontrols.io/help/online-booking/use-the-booking-api-for-your-own-booking-screens (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 .