Pages · Orders

Orders and lifecycle

Order states, revisions, cancellation and event history.

An order is created from a quote and finalized uploads (see the quickstart). The quote's price, address and shipping are committed for 72 hours; validation confirms against that commitment.

Request limits: at most 100 items per order and 200 tracks per item. Each format's manufacturing limits, such as runtime, are checked by validation. Formats: vinyl_12, vinyl_7, cassette, cd_jewel, cd_jacket.

Each track is { "asset_version_id": …, "side": "A" }, in play order. On a cassette every track needs a side, A or B; validation moves an order with a cassette track missing one to needs_attention with track_side_missing.

States

StateMeaning
receivedThe order is accepted and stored. Next: validation.
validatingFiles, runtime and artwork are checked against the format, and the quote's commitment is confirmed.
needs_attentionSomething must be fixed; attention_reason says what, as a code. Fix it with a revision, or cancel.
materials_holdValid, but materials could not be reserved yet. It moves on to awaiting_payment once they can be.
awaiting_paymentThe card on file is charged once for the committed total. A decline leaves the order here until you save a new card.
releasedPaid and released to production. From here a cancel request opens an exception instead of cancelling.
cancelledCancelled before release. Reserved materials are returned and any payment is refunded.
completeThe carrier has accepted shipments holding every unit the order needs.

Transitions

  • received → validating
  • validating → needs_attention
  • needs_attention → validating
  • validating → materials_hold
  • validating → awaiting_payment
  • materials_hold → awaiting_payment
  • awaiting_payment → materials_hold
  • awaiting_payment → released
  • released → complete
  • received, validating, needs_attention, materials_hold, awaiting_payment → cancelled

Every transition is an event (order.received, order.needs_attention, …) delivered to your webhooks and kept in GET /events. Test orders are never made or shipped.

Fixing an order

Only an order in needs_attention can be revised. POST /orders/{id}/revisions replaces its items (earlier revisions stay as history) and returns it to validation. Each revision needs rights_warranty: true and an Idempotency-Key. Different formats or quantities, a different shipping service, or an expired price commitment need a new quote_id. Revising an order in any other state returns 409 order_not_revisable.

Cancelling

POST /orders/{id}/cancel, optionally with a reason code such as changed_mind. Before release the order is cancelled, reserved materials are returned and any payment is refunded. After release the order does not change: the response is 409 order_released with the exception_id opened for your request.

Listing and history

  • GET /orders lists orders newest first; filter with state and page with limit and starting_after.
  • GET /orders/{id} returns the order with its current items, amount, latest payment, units and shipments.
  • GET /events?order_id=…&after_sequence=… returns one order's events in sequence with no gaps. Use it to reconcile or to recover missed webhooks.
  • GET /events without order_id is the account-wide list, for browsing. An event committed late can land behind a cursor you have already passed, so do not rely on advancing it to see every event.

Units and shipments

Once released, units lists the physical units made for the order and shipments the parcels holding them, with carrier, tracking number and tracking URL when known. The order is complete once the carrier has accepted shipments holding every unit it needs.