Production-order bulk access migration
Published: 2026-11-04
Target sunset: 2027-02-01
Summary
GET /v1/prodorders and an unfiltered POST /v1/prodorders return every matching production order as one synchronous response. Integrations should migrate bulk reads to paging now. For complete data extracts, Velosity plans to provide an asynchronous export workflow.
The unbounded list operations are targeted for sunset on 2027-02-01. Single-order access through GET /v1/prodorders/{ProductionOrderID} is not affected.
Why this is changing
The unbounded operation fully hydrates each production order, including its task, item, note, tag, history, serialization, traceability, document, and phase-history data. Observed responses are commonly 43–48 MB and take several seconds. A large response increases database work, application memory, garbage collection, network transfer, timeout risk, and retry amplification for both the calling integration and other tenants.
The authenticated account shown in request logs is the API caller; the API middleware only records that identity. Current traffic is primarily automated, making a controlled migration preferable to preserving a costly interactive contract.
Immediate replacement: paging
Use the existing page endpoint:
GET /v1/prodorders/pages/{Page}uses the default page size.POST /v1/prodorders/pages/{Page}accepts aProductionOrderSlicerModel; setLimitto a reasonable page size such as 100–250 and apply relevant filters.GET /v1/prodorders/countor its filteredPOSTcounterpart can provide the expected record count.
Process and release each page before requesting the next. Use bounded retries per page and checkpoint the last completed page. Do not fetch multiple large pages concurrently unless Velosity SUPPORT has confirmed an appropriate concurrency level.
Paging is the fastest available migration, but it is not an ideal archival export: records can be inserted or updated while pages are being read. Consumers requiring a point-in-time extract should use the planned export workflow when available.
Recommended export-all design
Velosity should add an asynchronous, tenant-scoped export resource rather than another synchronous list operation:
- Submit an export request with filters, requested fields, and format.
- Receive
202 Acceptedwith an export job ID and status URL. - Build a point-in-time or high-water-marked snapshot in the background using bounded database batches.
- Write newline-delimited JSON or CSV directly to compressed object storage without retaining the complete export in application memory.
- Poll the status endpoint or receive a webhook when the export is ready.
- Download through a short-lived signed URL; expire and delete the artifact automatically.
The job should enforce one active equivalent export per tenant, idempotency keys, size and retention limits, audit records, cancellation, and tenant authorization. Incremental synchronization should use a stable cursor based on LastUpdatedUTC plus a unique tie-breaker, with deletions represented by a change feed or tombstones. This will usually be preferable to repeated full exports.
Authorization and API visibility
Do not change the legacy operation to RequireRole(SYSTEM) as the migration mechanism. SYSTEM is an internal service role that is intentionally not assignable to users; applying it would immediately break the current customer integration. ROOT-only access would have the same practical effect and would grant an unnecessarily broad identity merely to export tenant data.
Authorization for the replacement should use a narrowly scoped tenant permission or API client scope such as production-orders:export, not a platform-administrator role.
The unbounded operations may be marked deprecated in OpenAPI immediately. They should remain visible with the replacement and sunset date during the migration period; hiding them would make discovery and migration harder and is not an access-control boundary. After sunset, remove them from current API documentation and return a clear retirement response from the legacy routes for a limited transition period.
Proposed timeline
- 2026-11-04: Publish notice, mark the unbounded operations deprecated, and ask known consumers to migrate to paging.
- By 2026-12-01: Confirm that known integrations can page successfully; add telemetry and response headers identifying the deprecation and sunset.
- By 2027-01-04: Deliver and validate the asynchronous export workflow if a point-in-time full extract is required.
- 2027-02-01: Sunset unbounded list behavior. Keep paged, by-ID, and export operations available.
The sunset should move only if the replacement export capability is required, agreed, and not ready—not merely because a consumer has not started migration.
SUPPORT email draft
Subject: Action required: migrate Velosity production-order bulk requests by February 1, 2027
Hello,
We identified that your integration is using the unbounded Velosity production-order endpoint. These requests currently return approximately 43–48 MB at a time and can take several seconds, increasing timeout and retry risk.
Please migrate the integration to the paged production-order endpoint. Guidance, endpoint details, and the proposed retirement timeline are available here:
https://developers.velosity.one/docs/content/production-orders-bulk-access
If the integration requires a complete point-in-time export rather than normal synchronization, please reply with the required fields, format, frequency, expected record count, and whether inserts/updates during an export must be excluded. We are proposing an asynchronous export job for that use case.
The target sunset date for the unbounded list behavior is February 1, 2027. Single-record production-order access is not affected.
Please confirm your migration owner and expected completion date. Velosity SUPPORT can help validate the paged requests in the test environment before production cutover.
Thank you,
Velosity SUPPORT