API v1 preview

# 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

[Line item object](https://ottomfg.com/docs/line-item-object.md)

`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_ship_date` string (date) | null · optional

Quotes only: estimated carrier handoff if the order is paid now, in origin local date. Null once the quote expires. Orders omit it; read the order's estimated_ship_date.

`estimated_delivery` object | null · required

Quotes: estimated arrival window if the order is paid now, in destination local dates, including production. Null once the quote expires or when transit is unknown. Orders keep null; read the order's estimated_delivery.

**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.

[Error object](https://ottomfg.com/docs/error-object.md)

`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.

[Error object](https://ottomfg.com/docs/error-object.md)

`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

- [Create an order](https://ottomfg.com/docs/create-order.md)
- [List orders](https://ottomfg.com/docs/list-orders.md)
- [Get an order](https://ottomfg.com/docs/get-order.md)
- [Cancel an order](https://ottomfg.com/docs/cancel-order.md)

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

Source: https://ottomfg.com/docs/order-object