Ordering and recovery

Hum separates preparation, authorization, submission, and retrieval. Keep those boundaries visible to the user and in client logic.

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.

​Ordering and recovery

​Validate without committing

​Build and revalidate the cart

​Handle validation states

​Present the exact review

​Obtain authorization

​Submit once

​Recover a lost response

​Fulfillment states

​Support escalation