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. When Hum returns required_fields, collect only those values and send them with the exact expected_revision. A stale revision is rejected so that older information cannot overwrite the current 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.

Handle validation states

Status	Meaning and next step
`checking`	Hum is refreshing or preparing the draft. Wait for the returned delay and poll with `checkout_id`.
`needs_information`	Collect the returned `required_fields`, correct any `field_errors`, and send them with the current revision.
`ready`	Present the exact review and obtain authorization for its `terms_hash`.
`offer_changed`	The selected offer no longer matches the earlier facts. Present the change and obtain a fresh selection or acceptance before continuing.
`unavailable`	The offer cannot proceed. Return to current availability or another executable offer as directed.
`expired`	The validation or offer expired. Refresh through the returned next action; do not submit an old token.
`failed`	Validation could not finish. Preserve the checkout and follow the returned next action.
`error`	Read the structured error, retry guidance, and next action.

Present the exact review

When validation is ready, 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
one-time and recurring fee
contract and data-limit condition
installation choice and preferred timing
billing preference and consent
unknown or unavailable fact

Sensitive customer values are omitted from the review and receipt. Do not echo them into a review, log, or support message.

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

​Handle validation states

​Present the exact review

​Obtain authorization

​Submit once

​Recover a lost response

​Fulfillment states

​Support escalation