Orders

Orders are the top-level container for a customer’s purchase. Each order contains one or more line items, each of which becomes a job.

Create an Order

curl -X POST http://localhost:8787/api/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "customerId": "cust-uuid",
    "lineItems": [
      {
        "skuId": "sku-pla-black-20mm-cube",
        "quantity": 3,
        "options": {
          "color": "#1a1a1a",
          "quality": "standard",
          "infill": 20
        }
      }
    ],
    "shippingAddress": {
      "name": "Jane Smith",
      "line1": "123 Main St",
      "city": "Portland",
      "state": "OR",
      "zip": "97201",
      "country": "US"
    },
    "notes": "Urgent — needed by Friday"
  }'

Response (201 Created):

{
  "id": "ord-abc123",
  "status": "pending_payment",
  "customerId": "cust-uuid",
  "lineItems": [
    {
      "id": "li-uuid",
      "skuId": "sku-pla-black-20mm-cube",
      "quantity": 3,
      "unitPrice": 12.50,
      "total": 37.50
    }
  ],
  "subtotal": 37.50,
  "shipping": 8.00,
  "tax": 3.76,
  "total": 49.26,
  "createdAt": "2024-01-15T10:00:00Z"
}

List Orders

# All orders, paginated
curl "http://localhost:8787/api/orders?page=1&limit=20" \
  -H "X-API-Key: your-api-key"

# Filter by status
curl "http://localhost:8787/api/orders?status=printing" \
  -H "X-API-Key: your-api-key"

# Filter by customer
curl "http://localhost:8787/api/orders?customerId=cust-uuid" \
  -H "X-API-Key: your-api-key"

Get an Order

curl http://localhost:8787/api/orders/ord-abc123 \
  -H "X-API-Key: your-api-key"

Order Statuses

Status	Description
pending_payment	Stripe checkout not yet completed
paid	Payment confirmed, jobs being created
processing	Jobs in validation/slicing
printing	At least one job is printing
post_processing	All jobs printed, in post-process
ready	All jobs ready for fulfilment
shipped	Tracking number assigned
cancelled	Cancelled (may have a refund)
refunded	Fully refunded

Cancel an Order

curl -X POST http://localhost:8787/api/orders/ord-abc123/cancel \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{ "reason": "Customer requested cancellation" }'

Cancellation triggers a Stripe refund for any already-captured payment. Jobs in PRINTING state are cancelled on the printer.

Order Events

Orders emit events that n8n workflows can subscribe to:

Event	Trigger
order.created	New order placed
order.paid	Payment confirmed
order.printing	First job starts printing
order.ready	All jobs completed
order.shipped	Tracking number assigned
order.cancelled	Order cancelled

See Webhooks for how to consume these events.