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
| State | Meaning |
|---|---|
received | The order is accepted and stored. Next: validation. |
validating | Files, runtime and artwork are checked against the format, and the quote's commitment is confirmed. |
needs_attention | Something must be fixed; attention_reason says what, as a code. Fix it with a revision, or cancel. |
materials_hold | Valid, but materials could not be reserved yet. It moves on to awaiting_payment once they can be. |
awaiting_payment | The card on file is charged once for the committed total. A decline leaves the order here until you save a new card. |
released | Paid and released to production. From here a cancel request opens an exception instead of cancelling. |
cancelled | Cancelled before release. Reserved materials are returned and any payment is refunded. |
complete | The carrier has accepted shipments holding every unit the order needs. |
Transitions
received→validatingvalidating→needs_attentionneeds_attention→validatingvalidating→materials_holdvalidating→awaiting_paymentmaterials_hold→awaiting_paymentawaiting_payment→materials_holdawaiting_payment→releasedreleased→completereceived,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 /orderslists orders newest first; filter withstateand page withlimitandstarting_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 /eventswithoutorder_idis 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.