> ## Documentation Index > Fetch the complete documentation index at: https://docs.letshum.com/llms.txt > Use this file to discover all available pages before exploring further. # Ordering and recovery > Validate an exact broadband offer, obtain authorization, submit once, and recover lost or uncertain responses # Ordering and recovery Hum separates preparation, authorization, submission, and retrieval. Keep those boundaries visible to the user and in client logic. ```mermaid theme={null} sequenceDiagram participant User participant Host participant Hum participant Fulfillment Host->>Hum: check_availability Hum-->>Host: executable offer_id Host->>Hum: validate_order Hum-->>Host: requested fields or exact review Host->>User: present exact review User-->>Host: authorize current terms Host->>Hum: create_order once Hum-->>Host: queued or persisted outcome Hum->>Fulfillment: asynchronous submission Host->>Hum: get_order Hum-->>Host: recorded fulfillment evidence ``` ## Validate without committing Start `validate_order` with the lookup and exact executable offer returned by availability. Hum creates a draft, refreshes the selected offer, and returns either the next requirement or a review. Validation creates no order and sends no fulfillment request. Continue with `checkout_id`. `required_fields` defines the checkout contract and can include fields already filled. `field_errors` identifies the actual missing or invalid values; its paths are relative to `details`. Reuse customer facts already supplied, ask only for what is still needed, and send changes with the current `expected_revision`. Place `customer`, `installation`, `consents`, and `internet_addons` inside `details`, never at the tool root. While validation is `checking`, wait at least `retry_after_seconds` and poll with only `checkout_id`. Resending an edit increments the revision and restarts validation. If a revision is stale, retrieve the checkout, wait if it is still checking, then edit at the returned revision. Starting again with the same lookup and offer returns the existing draft. Do not ask for card data, Social Security numbers, existing-account credentials, or payment authorization. Hum may request customer identity and contact fields, a mailing address, billing preferences, installation preferences, provider consents, a four-digit service PIN, or date of birth when the selected provider requires them. The returned field paths are authoritative. ## Build and revalidate the cart Validation can return `equipment_options` before the draft is ready. Present each option's name, price, included status, selection type, current quantity, and quantity limit. Send the complete selection in `details.internet_addons` using only returned option IDs and positive integer quantities. * Omit `internet_addons` to retain the current selection or initial defaults. * Send `[]` to decline optional equipment. * Select at most one option marked `radio`. * When a dependent option appears after selecting its parent, retain the parent in the next complete selection. * Never send client-supplied prices, SKUs, or equipment references. Keep the customer's equipment preference throughout selection and review. Customer-owned gear, included provider gear, and optional paid gear are distinct. A free provider gateway does not meet an own-equipment request. Use returned option names and catalog facts to check ownership; price or included status alone does not establish it. If the selected offer lacks the requested option, inspect another qualified offer or explain the limit and ask the customer to choose. An empty options list alone does not prove the ISP cannot provide equipment. Hum rebuilds the cart from current qualification and product data. A removed selection returns a field error. A changed product, fee, discount, or total can return `offer_changed` with the previous and current carts. Present the change and obtain a fresh decision. Any cart edit or revalidation change invalidates an earlier confirmation. ## Handle validation states | Status | Meaning and next step | | - | - | | `checking` | Hum is refreshing or preparing the draft. Wait for the returned delay and poll with only `checkout_id`; do not resend an edit. | | `needs_information` | Correct actual `field_errors`, reusing known facts, and edit at the current revision. `required_fields` can include filled paths. | | `ready` | Compare the review with the customer's request, present it, and obtain authorization for its current `terms_hash`. | | `offer_changed` | Present the previous and current offer and cart. After the customer's decision, start fresh availability and select a current offer. | | `unavailable` | Start fresh availability and inspect current offers. Do not repeatedly start the same failed draft or claim no service. | | `expired` | Revalidate the current checkout; if the offer expired, start fresh availability. Obtain new authorization after the next ready review. | | `failed` | No ready review exists. Start fresh availability before another attempt; if failure recurs, explain the limit and stop retrying. | | `error` | Follow the safe error and `next_action`. For a stale revision, retrieve before editing. | ## Present the exact review When validation is `ready`, first compare the cart with the customer's budget, minimum speed, equipment ownership, billing, and installation choices. `ready` means technical validity, not that the cart meets those choices. Resolve any mismatch before seeking authorization. Show the returned review rather than rebuilding terms from an earlier availability response. Include every returned: * provider and plan fact * monthly price, regular price, and promotion period * included product and equipment line item * one-time and recurring fee * total amount and returned bundle discount * contract and data-limit condition * installation choice and preferred timing * billing preference and consent * unknown or unavailable fact Distinguish recurring monthly pricing from one-time fees and the returned cart total. The total is not necessarily the monthly bill or an amount due now. Do not count an overlapping offer fee and cart line twice. Preserve billing opt-outs; a price adjustment that Hum did not return is unknown. Requested installation dates are preferences, not confirmed appointments. Sensitive customer values are omitted from the review and receipt. Never repeat a service PIN or full date of birth in customer-facing prose, even if the customer supplied them earlier. Keep checkout IDs, option IDs, terms hashes, and validation tokens in structured tool fields rather than the customer-facing review. Do not echo sensitive values into logs or support messages. ## Obtain authorization The host owns its authorization interface. Authorization must cover the current review and its exact `terms_hash`. General intent to shop, an approval for an older revision, silence, or an approval for different terms does not authorize submission. Do not call `create_order` when the host cannot obtain this authorization. ## Submit once Call `create_order` with the ready checkout, its validation token, the matching terms hash, `confirmed: true`, and a stable idempotency key. The key identifies this exact intended order. Keep it stable for an identical replay; never reuse it for another checkout, person, offer, or review. Hum records the authorized order locally before asynchronous fulfillment. A normal create response can arrive before fulfillment completes. `queued` means the local record is durable and submission is queued. It does not mean the ISP accepted the customer or that installation is scheduled. ## Recover a lost response Use `get_order` with the same `checkout_id` after a normal submission and whenever the create call times out, disconnects, returns a transport error, or loses its response. | Observation | Required action | | - | - | | A create response returned an order state | Keep the checkout ID and retrieve later for updates. | | The create response was lost or uncertain | Call `get_order` first. Do not make a new checkout and do not blindly resubmit. | | Retrieval returns `queued`, `submitting`, accepted, rejected, or unknown | Present that state accurately and follow `next_action`. Do not call create again. | | Retrieval returns `not_submitted` | Follow the exact returned `next_action`. Do not infer that submission is safe merely from the status name. | | Retrieval cannot prove the outcome | Preserve the checkout and correlation ID and use Hum's reconciliation or support guidance. | An error marked retryable does not override this rule. Retrieval comes first whenever a create call might have crossed the submission boundary. ## Fulfillment states These states report evidence in Hum's fulfillment path: | Status | What Hum can say | What it does not mean | | - | - | - | | `queued` | Hum durably recorded the authorized order and queued submission. | The fulfillment system or ISP accepted it. | | `submitting` | Fulfillment submission is in progress. | The submission succeeded. | | `accepted_by_fulfillment` | Hum recorded acceptance by the fulfillment system. | The ISP accepted the customer, confirmed serviceability, or scheduled installation. | | `rejected_by_fulfillment` | Hum recorded rejection by the fulfillment system. | A broader no-service result for the address. | | `submission_unknown` | Hum cannot prove whether the fulfillment system accepted the submission. Reconciliation is required. | Failure, success, or permission to retry. | | `not_submitted` | Hum has no recorded fulfillment submission for the checkout under the released rules. | Automatic permission to call `create_order`; follow `next_action`. | Do not translate these into the generic states used by Hum's partner analytics or widget. The MCP does not track provider installation, final ISP acceptance, account activation, payment, cancellation, or modification. ## Support escalation When the result directs you to support, include: * the safe correlation ID * the displayable order reference, if one exists * the status and last checked time * the client name and version Do not send validation tokens, checkout capabilities, service PINs, birth dates, contact details, or raw request and response bodies by email. Contact [support@letshum.com](mailto:support@letshum.com). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.