# Files, quotes and orders

Follow a deliberate lifecycle and keep the human intent attached to each order.

Stage: sandbox beta. Live purchasing requires explicit activation.

## Document readiness

POST /v1/files registers a filename, MIME type, byte count and SHA-256 checksum in sandbox. It does not upload or inspect document bytes. Run the simulated preflight before creating a quote. A real upload channel, document validation and retention controls are prerequisites for future live document submission.

## An immutable quote

Use the catalog for configuration values. The quote binds product, configuration, quantity, destination and owned file IDs to an amount, currency and expiry. An expired or non-ready quote cannot be ordered. Ask for a new quote when the document, destination or options change.

Sandbox prices are deterministic examples. They do not establish live coverage, production capacity, shipping promises or commercial prices.

## Orders and fulfilment

An order references a quote. Store the returned order ID and your external_reference. Read its production_jobs and shipments independently: an order can involve several jobs or shipments. Events describe changes; retrieval gives the latest projection.

Cancellation, replacement and sandbox refund endpoints require a reason. Their availability depends on the order state. The reference describes each action. A successful simulated refund never represents returned funds.

## Sandbox scenarios

Scenario values: success, preflight_failure, provider_decline, broker_fallback, payment_failure, split_production, late_shipment, undeliverable_mail, cancellation and refund. Set scenario when registering a file or requesting a quote. Advance a sandbox order to exercise the lifecycle.

Use your sandbox to test duplicate requests, conflicting retries, expired quotes, missing scopes and unavailable live access as well as the successful path.