Booking API course · updated 2026-10-05
Lesson 15: materials, the price depends on what goes in
Some companies charge a different price for the same dumpster depending on what goes in it (clean concrete, asphalt, brick, soil) and only accept heavy materials in smaller sizes. This lesson covers GET /materials and the material field on POST /quote and POST /intents. The company configures all of it in the app (Inventory, Materials: which sizes accept each material, the price per size, included tons, the switch "Pricing by material", off by default); this API only reads it, there is no endpoint to create or edit materials. Nothing changes for a company that does not price by material.
Before you start
- Lessons 3, 5 and 6
- A company that turned on pricing by material in Inventory, Materials (off by default)
- ## Read the materials
```
GET /materials returns data { enabled, required, materials[], note }. enabled means the company prices by material; required means ask the material before the size. Each material has slug, label, explanation (what counts as that material), requires_ack (the customer must confirm the explanation), is_catch_all (the general option that is always available), is_heavy, size_policy (all or listed) and sizes[]: with listed, only those sizes accept the material; each size carries price (replaces the 7-day base; null = the size price), max_weight_tons, overage_mode (inherit, flat, per_ton) and overage_per_ton.
``` - ## Material-first screens
When required is true: step 1 asks what the customer is disposing of (the materials, in sort_order, with label and explanation), step 2 shows only the sizes that material allows (sizes[] when size_policy is listed, every size from GET /sizes when all) at the material price, then dates, address and the card. When enabled is false keep your usual size-first flow. - ## Quote and start with a material
```
POST /quote { size_id, rental_days, material } returns pricing material or general, material {...} and the usual lines: with pricing material, base is the material price for 7 days, days beyond 7 use the size's extra day rate, fees and tax are unchanged, and a percentage promo applies to the material price. POST /intents takes the same material plus material_acknowledged: true when requires_ack is true. The server resolves the material once and freezes it with the payment, so the order keeps that price even if the office edits it later.
``` - ## Errors to handle
400 invalid_body field material: unknown slug (details.allowed lists the valid ones). 400 invalid_body field material_acknowledged: the material requires the customer's confirmation (the explanation is in the message). 400 invalid_body field debris_type: you sent material and a different debris_type. 409 material_not_allowed: the material is not available in that size; details.allowed_sizes (id, label, yards, price) are the sizes to offer. - ## Compatibility
Clients that never send material keep today's prices and responses. One exception: on a company that prices by material, a debris_type equal to an active material slug (for example concrete) is priced as that material and may be refused with material_not_allowed. Send material explicitly to be precise. - ## What the office sees
The order shows the material, the invoice line reads size and material (for example 10 Yard, Clean Concrete) with the included weight of that rule, and the order keeps a snapshot of the rule the customer accepted, with the acknowledgement time. Webhooks carry material and material_label.
What happens next
- Test one quote per material against the office's price list before going live; the Developers tab's test quote already uses the first priced material when the company has one.
Troubleshooting
GET /materials returns enabled false but the office configured prices.
Pricing by material is off by default for every company. The office turns it on with the switch at the top of Inventory, Materials; until then the list is visible but every material costs the size price.
The same size costs less with a material than without.
That is the company's choice: some materials (clean concrete) are cheaper to dispose of. The material price replaces the size price; it is not added to it.
Related guides
- Lesson 3: GET /company and GET /sizes, the data your screens start from
- Lesson 5: POST /check and POST /quote, validate and price before the card
- Lesson 6: POST /intents, the server prices the order and opens the payment
- How to charge a different price by material and limit heavy materials to certain sizes
© 2026 Dumpster Controls. All rights reserved. Made in the USA.