Documentation feedback

Was this helpful?

Updating production-order status

A production order describes the work and material required to complete a Sales Order line item. Its status is the Velosity-defined lifecycle state used by production views, scheduling, reporting, and integrations.

Use PATCH /v1/prodorders/{productionOrderID}/completion to complete an order. Use PATCH /v1/prodorders/status for other lifecycle changes. The dedicated completion endpoint makes the completion timestamp, retry behavior, and active-clock conflict explicit.

Status values

status statusText Meaning
-2 Cancelled The order was cancelled. For a normal cancellation, use the cancellation endpoint described below so task and material cleanup also occurs.
1 Planned The order exists but is not yet ready for the shop floor.
2 Released The order is available for production work and can appear in production queues.
3 Work In Progress Work has started on the order.
4 Completed Production is complete. In the optional Shipping module, the associated line item becomes available for shipping.
10 On Hold Work is paused.

statusText is read-only and derived from status. Send only status; do not attempt to update statusText. For example, an order with status: 4 is returned with statusText: "Completed".

A production-order phase is different. Phases are optional, tenant-defined labels such as Engineering Review, Waiting for Material, or Out for Plating. Do not use a phase as a substitute for the status integration contract.

Typical lifecycle and allowed transitions

A production order typically moves from Planned to Released, then Work In Progress, and finally Completed. On Hold and Cancelled support exception handling.

The API also permits selected direct or backward transitions used for corrections and external-system synchronization:

Current status Allowed target statuses
Planned Planned, Released, Work In Progress, Completed, On Hold, Cancelled
Released Released, Planned, Work In Progress, Completed, On Hold, Cancelled
Work In Progress Work In Progress, Planned, Released, Completed, On Hold, Cancelled
On Hold On Hold, Planned, Released, Work In Progress, Completed, Cancelled
Completed Completed only
Cancelled Cancelled only

Submitting the current status again is allowed and makes integration retries safe. Unsupported numeric values and disallowed transitions return 400 Bad Request without changing the order.

Complete an order

PATCH /v1/prodorders/{productionOrderID}/completion
Content-Type: application/json
X-APIKEY: _your API key_

Send the authoritative UTC completion timestamp when the source system has one:

{
  "actualCompletionUTC": "2026-10-28T21:15:00Z"
}

To use the API server's current UTC time, omit the property and send {}. The first stored completion timestamp wins: repeating the request does not replace it, even when a retry sends a different value.

A successful request returns 200 OK with the persisted result:

{
  "productionOrderID": "_production order ID_",
  "status": 4,
  "actualCompletionUTC": "2026-10-28T21:15:00Z"
}

actualCompletionUTC represents production completion. A caller may intentionally use a shipment or PGI timestamp when that is its authoritative completion event, including when closing historical orders.

If the order has an active production clock entry, the API returns 409 Conflict and does not complete the order. Clock out the active entry before retrying.

Change another status

PATCH /v1/prodorders/status
Content-Type: application/json
X-APIKEY: _your API key_

For example, to release an order:

{
  "productionOrderID": "_production order ID_",
  "status": 2
}

The API loads the current production order by ID before applying the change. Callers do not need to send salesOrderID, salesOrderLineItemID, phase, tasks, or statusText.

Response

A successful request returns 200 OK. The response body is the number of production-order rows updated and is normally:

1

An integration can then retrieve the order with GET /v1/prodorders/{ProductionOrderID} and verify the status:

{
  "productionOrderID": "_production order ID_",
  "status": 2,
  "statusText": "Released"
}

Errors and retry behavior

HTTP status Meaning
400 Bad Request The production-order ID is missing, the numeric status is unsupported, or the requested transition is not allowed.
401 Unauthorized The request is not authenticated.
404 Not Found No production order exists with the supplied ID.
409 Conflict Completion was rejected because the production order has an active clock entry.
500 Internal Server Error The update failed. The status workflow is transactional, so status, history, audit/events, related synchronization, and webhook outbox work are rolled back together.

Use bounded retries for transient server or network failures. Repeating the current status is allowed, so a caller can safely retry when it did not receive a response. Retrieve the order after an ambiguous result if the integration must confirm the final state before continuing.

Production-order status versus task status

The production order and its router tasks have separate statuses. Task statuses are INCOMPLETE, WIP, COMPLETED, and CANCELLED.

Completing the production order does not update its tasks. An incomplete or in-progress task retains its existing task status. This preserves the task-level record when an external system knows the overall order shipped but does not have authoritative completion data for every production step.

For an integration whose source of truth only indicates that the overall order shipped, calling the completion endpoint is sufficient. Do not mark tasks Completed unless the integration can assert that each task was completed.

When authoritative task-level completion data is available, submit the updated task collection through:

PATCH /v1/prodorders/{ProductionOrderID}/tasks

When every submitted task is Completed, that workflow automatically sets the parent production order to Completed. Task updates must follow the router sequence. Completing a task also closes its matching open production-time interval.

Cancellation

Do not normally cancel an order by setting status to -2 through the status endpoint. Use the cancellation workflow instead:

POST /v1/prodorders/{ProductionOrderID}/cancel

The cancellation workflow preserves the history of work already performed and additionally cancels incomplete tasks, resets their planned times, adjusts corresponding Sales Order line-item tasks, and updates selected bill-of-material quantities. A direct status change does not perform that cancellation-specific cleanup.

A successful status update runs the normal production-order processing in one transaction:

  • Appends status history and creates audit and event records.
  • Preserves persisted Sales Order, line-item, phase, task, and other context when the request contains only ID and status.
  • When all production orders for the related Sales Order line item are Completed, marks that line item Finished.
  • Marks applicable production material requests Delivered when completion criteria are met.
  • Adds configured production-order status webhooks to the delivery outbox.

Status changes are visible in the production order's History and Events views. Changing an order to Released also makes it eligible for production-queue visibility; changing it to Completed can make its associated line item available to Shipping.

See Webhooks for event configuration, payloads, delivery behavior, signatures, and receiver guidance.