The Order object
An accepted quote with fixed items, prices and delivery, and its payment state.
Fields
id string · required
Immutable order ID and customer reference: OM- followed by eight uppercase Crockford Base32 characters. Pass it unchanged; there is no separate order-number field.
Min length: 11 · Max length: 11
created_at string (date-time) · required
quote_id string · required
Server-generated public quote ID: quote_ plus 32 lowercase hexadecimal digits representing an opaque random value. Immutable and opaque; not a storage path or content hash.
Min length: 38 · Max length: 38
currency string · required
Lowercase ISO 4217 currency for all monetary fields on this order. Currently usd.
items array · required
shipping_address object · required
Saved US recipient address. New quotes return a five-digit ZIP code.
shipping_address fields
name string · required
Delivery recipient; may differ from the buyer.
Min length: 1 · Max length: 255
company string · optional
Optional recipient company.
Min length: 1 · Max length: 255
line1 string · required
Street address.
Min length: 1 · Max length: 200
line2 string · optional
Optional apartment, suite, or additional address line.
Min length: 1 · Max length: 200
city string · required
Destination city/locality.
Min length: 1 · Max length: 100
state string · required
Supported two-letter US state or territory code, or AA/AE/AP military region.
Min length: 1 · Max length: 2
postal_code string · required
Five-digit ZIP code on new quotes. Older saved snapshots may retain ZIP+4.
Min length: 1 · Max length: 10
country string · required
Literal US.
Always: "US"
Min length: 1 · Max length: 2
phone string · optional
Recipient contact; required where the selected carrier/service requires it.
Min length: 1 · Max length: 50
email string (email) · optional
Min length: 1 · Max length: 254
buyer object · optional
Optional buyer details, separate from the delivery recipient. The authenticated account owns the quote and order.
buyer fields
name string · optional
Buyer name.
Min length: 1 · Max length: 255
company string · optional
Buyer company.
Min length: 1 · Max length: 255
email string (email) · optional
Min length: 1 · Max length: 254
shipping_option object · required
Selectable shipping service with a price and estimated transit time after dispatch. Returns at most one service per transit-day option, ordered by price. Null timing means unavailable; estimates are not guaranteed delivery dates.
shipping_option fields
id string · required
Opaque service-generated ID for an option within a particular quote. Not a carrier rate ID. Cannot be transferred to another quote.
name string · required
Customer-facing shipping service label.
Min length: 1
carrier string · optional
Optional carrier name, when a carrier is committed for this option.
Min length: 1
totals object · required
Manufacturing and shipping charges in integer minor currency units. Total excludes tax.
totals fields
subtotal integer · required
Sum of model line subtotals, excluding shipping and tax. Integer minor currency units.
Minimum: 0
shipping integer · required
Carrier rate for the estimated parcel, including its packing weight. No general free-shipping credit; an account-specific arrangement can price one service at 0. Integer minor currency units (for USD, cents).
Minimum: 0
total integer · required
Amount to review before ordering: subtotal + shipping. Tax is excluded in V1. Integer minor currency units (for USD, cents).
Minimum: 0
estimated_transit_business_days object | null · required
Carrier transit days when supplied; otherwise the supported service estimate. Starts at handoff, excludes production, and is not guaranteed.
estimated_transit_business_days fields
At least one of these conditions applies:
object
min integer · required
Minimum: 0
max integer · required
Minimum: 0
null
null
estimated_delivery object | null · required
Currently null because production timing is not available. Carrier transit alone is not an arrival-date promise.
estimated_delivery fields
At least one of these conditions applies:
object
earliest string (date) · required
latest string (date) · required
null
null
external_id string · optional
Optional customer reference, without uniqueness or deduplication guarantees.
Max length: 255
purchase_order_number string · optional
Optional buyer purchase-order reference; not payment authorization.
Max length: 255
metadata object · optional
Optional customer key/value strings. Up to 50 keys, each 1–40 characters; values up to 500 characters. Unicode category C characters (including control and format characters) are rejected in keys and values. No secrets. Not interpreted for pricing, permissions or deduplication.
status string · required
Order lifecycle: awaiting_payment, expired, confirmed, in_production, shipped, delivered, on_hold or cancelled. Staff set in_production, shipped, delivered and on_hold. Customer cancellation is allowed only in awaiting_payment or confirmed, subject to repair-coverage guards.
Allowed values: awaiting_payment, expired, confirmed, in_production, shipped, delivered, on_hold, cancelled
updated_at string (date-time) · required
events array · required
Complete inline append-only history in ascending sequence. No truncation or separate event endpoint in v1. Lifecycle milestone times can be derived from events[].
events item fields
id string · required
sequence integer · required
Minimum: 1
type string · required
Stable event name; handle unknown additions.
Allowed values: order.created, order.expired, order.confirmed, order.in_production, order.shipped, order.delivered, order.on_hold, order.resumed, order.cancelled, payment.requires_action, payment.processing, payment.paid, payment.failed, payment.cancelled, payment.refund_pending, payment.refunded, payment.refund_failed
at string (date-time) · required
reason string | null · required
data object · required
estimated_ship_date string (date) | null · required
Current estimate for final carrier handoff, in origin local date; null if unknown. Calendar date without timezone. Do not directly compare it to destination-local estimated_delivery dates.
estimated_delivery object | null · required
Current full-order completion window, destination local dates; null if unknown. Does not overwrite individual shipment delivery times.
estimated_delivery fields
At least one of these conditions applies:
object
earliest string (date) · required
latest string (date) · required
null
null
hold object | null · required
Set while the order is on_hold; otherwise null.
hold fields
At least one of these conditions applies:
object
code string · required
Allowed values: address_problem, printability, payment, other
message string · required
null
null
payment object · required
Order-bound payment state, independent of preparation/fulfillment. amount/currency come from accepted quote. A saved method or return redirect is not proof of payment. Receipt links may be absent; never expose client secrets here. Refund states describe full-order refunds in v1. Cancellation before production refunds the full accepted total, including shipping. Refund completion is asynchronous; refund_failed requires support.
payment fields
status string · required
Order payment state. Refund states describe full-order refunds.
Allowed values: unpaid, requires_action, processing, paid, failed, cancelled, refund_pending, refunded, refund_failed
amount integer · required
Minimum: 0
currency string · required
method object | null · required
method fields
At least one of these conditions applies:
object
id string · required
brand string · required
last4 string · required
null
null
paid_at string (date-time) | null · required
receipt_url string (uri) | null · required
Receipt link after successful payment, when available; otherwise null. Retrieve the order for current payment details.
error object · optional
Error code, message and optional field details. HTTP errors return this object directly; asynchronous processing errors appear on the resource. Branch on code, not message.
pricing_version string · required
Opaque identifier for the pricing schedule used. Store it for reference; do not parse it or calculate prices from it. A calculation does not lock prices; review a quote before ordering. Business pricing versions change at calendar-month boundaries; unaccepted quotes then require refreshing.
shipment object | null · required
Set when the order ships; null before. delivered_at is set on delivery.
shipment fields
At least one of these conditions applies:
object
carrier string · required
service string · required
tracking_number string | null · required
tracking_url string (uri) | null · required
shipped_at string (date-time) · required
Carrier handoff of the whole order, not label purchase.
delivered_at string (date-time) | null · required
Delivery time; set when the order is delivered.
null
null
preparation object · required
Preparation of accepted model/size configurations. Status currently remains pending: production preparation and fulfillment execution are not enabled. Processing, completed and failed are reserved preparation states. Payment does not establish completed preparation.
preparation fields
status string · required
Allowed values: pending, processing, completed, failed
items array · required
items item fields
model_id string · required
Immutable model ID: MD- followed by eight uppercase Crockford Base32 characters. Use this same ID in the website, URLs and API; pass it unchanged.
Min length: 11 · Max length: 11
status string · required
Allowed values: pending, processing, completed, failed
error object · optional
Error code, message and optional field details. HTTP errors return this object directly; asynchronous processing errors appear on the resource. Branch on code, not message.
longest_dimension_mm number · required
Longest bounding-box dimension in millimeters, 30–200 inclusive. Fractional values are accepted. Uniformly scale all axes. At model creation this is the default and inspection reference size; each pricing/quote item explicitly selects its own size. Callers convert other units to millimeters.
Minimum: 30 · Maximum: 200
repair_required boolean · optional
Paid repair and revalidation must complete before production.
file_revision integer · optional
Pinned customer file revision. Renames and resizes do not create a new revision.
Minimum: 1
repair_order_id string · optional
Originating paid mesh-repair order for this exact revision. Reuse its repair work; payment alone is not proof of completed preparation.
Min length: 11 · Max length: 11
invoice object | null · optional
Paid invoice summary; download using GET /orders/{order_id}/invoice. Null for unpaid orders or historical orders without a captured billing profile.
invoice fields
At least one of these conditions applies:
object
number string · required
issued_at string (date-time) · required
null
null
expires_at string (date-time) | null · required
Deadline to start a new payment: 24 hours after created_at. Null once the order leaves awaiting_payment. Existing attempts get at least one hour from attempt creation to finish; after both deadlines, unfinished collection is cancelled before the order expires. Verified success during reconciliation confirms the order; unresolved provider outcomes keep it awaiting_payment. Success discovered after the order has expired is refunded without confirming.
Returned by
Example
JSON
{
"id": "OM-XMF1NT2E",
"created_at": "2026-09-18T18:00:00.000000Z",
"quote_id": "quote_6c82bd3e319b4bb099310d54a761879e",
"currency": "usd",
"items": [
{
"model_id": "MD-739YQ549",
"quantity": 2,
"unit_price": 3000,
"subtotal": 6000,
"repair": {
"required": false,
"applied": false,
"reason": null,
"status": "not_applied",
"fee": 0,
"covered_by_order_id": null
},
"longest_dimension_mm": 100,
"dimensions_mm": {
"x": 50,
"y": 100,
"z": 40
}
}
],
"shipping_address": {
"name": "Alex Example",
"company": "Example Retail",
"line1": "123 Example Street",
"city": "Seattle",
"state": "WA",
"postal_code": "98101",
"country": "US"
},
"buyer": {
"company": "Example Store",
"email": "orders@example.com"
},
"shipping_option": {
"id": "shipopt_6c82bd3e319b4bb099310d54a761879e",
"name": "Standard",
"totals": {
"subtotal": 6000,
"shipping": 1000,
"total": 7000
},
"estimated_transit_business_days": {
"min": 3,
"max": 5
},
"estimated_delivery": null
},
"external_id": "checkout-123",
"purchase_order_number": "PO-2026-0042",
"metadata": {
"project": "launch"
},
"updated_at": "2026-09-18T18:00:00.000000Z",
"status": "awaiting_payment",
"events": [
{
"id": "evt_00000000000000000000000000000001",
"sequence": 1,
"type": "order.created",
"at": "2026-09-18T18:00:00.000000Z",
"reason": null,
"data": {
"status": "awaiting_payment"
}
}
],
"estimated_ship_date": null,
"estimated_delivery": null,
"hold": null,
"payment": {
"status": "unpaid",
"amount": 7000,
"currency": "usd",
"method": null,
"paid_at": null,
"receipt_url": null
},
"shipment": null,
"pricing_version": "pv_2026_09_a",
"preparation": {
"status": "completed",
"items": [
{
"model_id": "MD-739YQ549",
"status": "completed",
"longest_dimension_mm": 100
}
]
},
"expires_at": "2026-09-19T18:00:00.000000Z"
}API v1 preview