Orders

An order is one shipment of approved variants to one address. Placing it prices the lines, quotes shipping, charges your card, and creates a paid fabrication job for each line.

Quote shipping first (optional)

{
  "rates": [
    { "rate_id": "cb45…", "carrier": "USPS", "service": "Ground Advantage", "amount_cents": 578, "currency": "usd", "estimated_days": 3 },
    { "rate_id": "9a1e…", "carrier": "USPS", "service": "Priority Mail Express", "amount_cents": 3343, "currency": "usd", "estimated_days": 2 }
  ],
  "note": "Pass a rate_id as shipping.rate_id when you place the order, or let shipping.method pick standard (cheapest) or expedited (fastest)."
}

Show these to your customer, or skip this call and let shipping.method choose.

Place the order

{
  "external_reference": "SHOP-5001",
  "items": [
    { "sku": "WB-S", "quantity": 12 },
    { "sku": "WB-L", "quantity": 1 }
  ],
  "ship_to": {
    "name": "Pat Buyer",
    "company": "Example Robotics",
    "street1": "301 College St",
    "city": "Greenville",
    "state": "SC",
    "zip": "29601",
    "country": "US",
    "email": "pat@example.com"
  },
  "shipping": { "method": "standard" }
}

Fields

items	Required. 1 to 50 of { variant_id or sku, quantity }. Variants must belong to an approved product on your account.
ship_to	Required. name, street1, city, state, zip; optional company, street2, country (default US), email, phone.
shipping.method	standard (cheapest) or expedited (fastest). Default standard.
shipping.rate_id	A rate from the rates call, if your customer chose one. Overrides method.
external_reference	Your order number. Returned everywhere, shown to Glyph staff.
notes	Optional. Packing or engraving notes for the shop.

201, paid and waiting for release:

{
  "id": "d38f2acc-4f4d-4bcb-906d-98a190b351be",
  "status": "paid",
  "next": "awaiting_production",
  "external_reference": "SHOP-5001",
  "subtotal_cents": 20600,
  "shipping_cents": 648,
  "total_cents": 21248,
  "shipping": { "method": "standard", "carrier": "USPS", "service": "Ground Advantage", "rate_id": "cb45…" },
  "payment": { "status": "paid", "paid_at": "2026-10-12T21:30:02.118+00:00", "refunded_at": null, "error": null },
  "shipment": null,
  "items": [
    { "sku": "WB-S", "quantity": 12, "unit_price_cents": 1500, "line_total_cents": 18000, "job": { "id": "…", "status": "paid" } },
    { "sku": "WB-L", "quantity": 1, "unit_price_cents": 2600, "line_total_cents": 2600, "job": { "id": "…", "status": "paid" } }
  ]
}

Twelve units crossed the price break, so WB-S was charged at 15.00 instead of 18.00.

402, the card was declined or none is saved. The order is recorded as payment_failed; nothing is built. Fix billing and place it again.

{ "id": "…", "status": "payment_failed", "next": "update_card_and_retry", "error": "Card declined (insufficient_funds).", "billing": "Update the card on file, then place the order again." }

409 with details when a line cannot be priced: unknown sku, inactive variant, or a product that is not approved.

{ "error": "Order cannot be priced.", "details": [ "items[0]: no approved, active variant WB-XL on this account." ] }

422 when no USPS rate exists for the address. 503 when shipping or storage is unavailable; retry with the same Idempotency-Key.

Follow it

Order status → next

paid	awaiting_production. Charged; a person at Glyph releases it.
in_production	in_production. Jobs are in the shop queue.
shipped	complete. shipment holds carrier, tracking_number, tracking_url, shipped_at.
payment_failed	update_card_and_retry.
cancelled	cancelled. payment.status is refunded if it had been paid.

Each line's job shows the fabrication job's own status, which moves through queued, scheduled, running, done, shipped.

Cancel

{ "id": "…", "status": "cancelled", "next": "cancelled", "payment": { "status": "refunded", "paid_at": "…", "refunded_at": "…", "error": null } }