State & recovery

Recover an uncertain write without creating a second booking, charge or financial obligation. Command acceptance and current resource state answer different questions.

Persist before sending

Every mutation needs one valid UUID Idempotency-Key. Persist the UUID, operation, exact method/path/body and returned resource identities in your durable request record before sending. Quote/preview POSTs are reads and create no receipt; they do not require this header.

A response can contain action=accepted, succeeded, action_required or unknown. These are retained command acceptance facts, not a refreshed settlement or delivery ledger. The JSON envelope contains data and request_id; errors carry status/code/title/request ID and applicable validation/missing-input details.

Resolve uncertain delivery

Keep the original UUID and submitted facts after a timeout, disconnect or uncertain response.
Retry the same method/path/body with that UUID and the same still-authorized key. Do not create another checkout or financial report to discover the first result.
Accepted replay returns the original status/resource identities with replayed=true. Changed normalized facts conflict rather than replace the command.
Follow the returned resource_type/resource_id to its current GET. Read actual payment, booking/session, approval, fulfillment and required-action state.
Use that resource's documented confirmation, retry or resolution capability. Each distinct command has its own persisted UUID; uncertain delivery reuses that command's UUID.

Native checkout, external checkout, payment report, amendment, add-on purchase, cancellation and external refund have separate current reads. A retained receipt does not become a live status response.

Keep financial identities too

HTTP receipt scope includes the authorizing credential and operation. A replacement key with current permissions can recover a known tenant-owned resource, but cannot read the old key's private receipt.

Retain real collection/refund/cycle identities in addition to request UUIDs. A fresh HTTP UUID does not make an arbitrary second financial report a duplicate without the financial identity. Do not change a provider request identity while its result is undetermined or switch tender to discover the result.

Interpret errors in context

Result	Response
`401 invalid_key`	Correct missing, invalid or revoked credentials. Current authority still applies to recovery.
`403`	Resolve account, feature or permission refusal; do not escalate automatically.
`404 not_found`	The resource is absent or inaccessible under current contextual authority.
`409`	Inspect the operation-specific conflict, stale selection or reconciliation requirement.
`422 incomplete_selection`	Collect returned missing inputs; other validation/domain codes are operation-specific.
`503`	Retry infrastructure/calendar uncertainty only where documented; honor `Retry-After` and preserve write identity.

An error is not universal proof that no money was collected. Log sanitized request IDs, UUIDs and returned resource IDs for support; never log studio keys, browser payment secrets or raw personal/payment payloads.

What completion means

A paid resource can still await staff approval. Queued notifications have unknown delivery. A cancellation can retain an outstanding external refund obligation. Null/unsupported invoice facts are not an issued invoice. Read these facts explicitly instead of collapsing them into a single success flag.

Disabling new commercial entry preserves authorized accepted-resource reads/replay/recovery under current account/key/public-API authority. It does not bypass revocation or permission changes. If the sandbox/provider prerequisite is missing, the integration trial is blocked, not passed; public guide availability does not authorize writer enablement.