Dumpster Controls · agent page

This is the agent-optimized version of https://dumpstercontrols.io/help/booking-api/lesson-6-start-the-order-with-post-intents: the same content as the human page, without scripts, styles, animations or navigation. People should open the full page.

Canonical page
https://dumpstercontrols.io/help/booking-api/lesson-6-start-the-order-with-post-intents
Last updated
2026-10-05
Tokens
1,622 tokens (cl100k_base), within the 2,500-token budget for a help page
Size
11 KB for this page, against 35 KB for the human page (67% smaller)
Markdown
https://dumpstercontrols.io/help/booking-api/lesson-6-start-the-order-with-post-intents.md, or send Accept: text/markdown to the canonical URL
Cite as
Lesson 6: POST /intents, the server prices the order and opens the payment. Dumpster Controls. https://dumpstercontrols.io/help/booking-api/lesson-6-start-the-order-with-post-intents (accessed 2026-11-20).
More for agents
Facts sheet · llms.txt · llms-full.txt · All agent pages · Product manual

Booking API course · updated 2026-10-05

Lesson 6: POST /intents, the server prices the order and opens the payment

This is the call that turns a filled form into a payment waiting for a card. You send the order and the customer; the server prices it again, runs every rule and the fraud screening, creates the Stripe PaymentIntent and gives you a client_secret. No price travels from your page to ours.

Before you start

  • Lesson 5: you have a size_id, rental_days, a delivery date that passed /check and, if used, a valid promo code
  1. ## Request
    ```
    POST /intents
    {
    "size_id": "<uuid>",
    "rental_days": 7,
    "delivery_date": "2026-11-10",
    "pickup_date": "2026-11-17",
    "delivery_address": "123 Main St",
    "delivery_city": "Orlando",
    "delivery_state": "FL",
    "delivery_zip": "32801",
    "placement_lat": 28.5383,
    "placement_lng": -81.3792,
    "debris_type": "household",
    "notes": "Gate code 4471. Paver driveway, please bring plywood.",
    "customer": { "name": "Jane Doe", "email": "jane@example.com", "phone": "4075550100", "type": "residential", "company_name": null },
    "promo_code": "SAVE10",
    "terms_accepted": true,
    "session_id": "your-own-id-optional"
    }
    ```
    Required: size_id, rental_days (1 to 365), delivery_date (YYYY-MM-DD), delivery_address (street number and name), delivery_zip, customer.name, customer.email, customer.phone, terms_accepted = true. pickup_date defaults to delivery_date plus rental_days. customer.type is residential or contractor. notes is optional plain text up to 500 characters (where to place the dumpster, gate code, surface): it is saved on the order as the placement notes the driver sees; HTML and control characters are removed. session_id is 8 to 64 characters (letters, digits, _ or -); send your own to make retries idempotent.
  2. ## Response
    ```
    { "data": {
    "session_id": "...", "payment_intent_id": "pi_...", "client_secret": "pi_..._secret_...",
    "stripe": { "publishable_key": "pk_live_...", "account": null },
    "currency": "usd",
    "amount": { "total": 350, "total_cents": 35000, "processing_fee": 14.46, "processing_fee_cents": 1446, "gross_total": 364.46, "gross_total_cents": 36446, "card_fee_handling": "customer_pays" },
    "next": "Confirm the card with Stripe.js ..."
    } }
    ```
    Keep session_id, payment_intent_id and client_secret in memory for the next two lessons. For Canadian companies stripe.account is the connected account id: initialize Stripe.js with it (lesson 7).
  3. ## What happens on the server
    In order: the input is validated (400 invalid_body with field), the price is recomputed from the company's account, booking must be on and Stripe ready, the date must be open and the ZIP inside the service area, the promo must be valid, the email must not belong to a commercial account of the company (409 account_customer), the rate limits and the card-testing gate are checked, the card fee is computed under the company's handling, and the PaymentIntent is created on Stripe with the risk tier of the company (manual capture for review when the company holds suspicious orders). A record of the attempt is kept so the company can see abandoned checkouts.
  4. ## Errors you should handle
    400 invalid_body: show the message next to the field. 409 booking_offline, payments_not_ready: show the company's phone. 409 date_past, date_closed, out_of_service_area: send the customer back to that step with the message. 409 account_customer: the message tells the customer to order through their account or call. 409 already_authorized: this session already has an authorized payment; go straight to POST /confirm with its payment_intent_id. 429 rate_limited: wait Retry-After seconds. 502 upstream: try again in a few seconds.
  5. ## Idempotency
    Send the same session_id on a retry and the server reuses the open PaymentIntent instead of creating a new one. If the payment was already authorized you get 409 already_authorized with the hint to confirm. Generate a new session_id only for a genuinely new attempt (a different size, date or customer).
  6. ## material and material_acknowledged
    Send material (a slug from GET /materials) when the company prices by material; the server prices the order by it and the order carries the material. When that material has requires_ack, send material_acknowledged: true after showing the explanation; otherwise 400 invalid_body with field material_acknowledged and the explanation in the message. A debris_type equal to an active material slug is treated as the material; sending both with different values is 400. 409 material_not_allowed works as in POST /quote. The price is resolved once here and frozen with the payment: editing prices in the account afterwards does not change this order.

What happens next

  • Nothing has been charged yet. The customer still has to confirm the card (lesson 7) and your page still has to call POST /confirm (lesson 8).

Troubleshooting

The amount in /intents differs from my last /quote.

The company changed a price or a promo between the two calls, or the promo became invalid. Always show the amount from /intents on the payment step; it is what the card will be charged.

Related guides

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