Order API
The v3 Order API is described in more detail in the Swagger definition. Here follows a summary of the endpoints.
Method | Endpoint | Description |
|---|---|---|
GET | /api/v3/orders | Get orders by contact Gets all orders for a contact. Returns a paged result with links that can be used to get the next/previous result set (by default 10 per request). |
POST | /api/v3/orders | Register new order Creates an order. The creation is asynchronous. Use the information in the response to follow the progress and catch any errors. |
GET | /api/v3/orders/{orderId} | Get specific order Gets a specific order by its unique order identifier. If the optional contactId is supplied, a verified check is made that the order is connected to the contact. |
PUT | /api/v3/orders/{orderId} | Replace order Replaces an order. The replacement is asynchronous. Use the information in the response to follow the progress and catch any errors. Note that the order must be replaced as a whole and not partially. |
DELETE | /api/v3/orders/{orderId} | Delete order Delete an orders. The deletion is asynchronous. Use the information in the response to follow the progress and catch any errors |
GET | /api/v3/orders/jobs/{jobId} | Get status of the asynchronous request Returns job status of the request made to change an order. All endpoints that create or change orders are asynchronous. These requests return a "201 Accepted" and a link to this endpoint where the client can poll for the progress of the change. If the request is successful, the return is a "302 Redirect" to the updated resource. If the request cannot be processed, the return is an Error. |
POST | /api/v3/orders/{orderId}/action | Trigger action events for a specific order. |
POST | /api/v3/orders/{orderId}/change-status | Update the internal and/or external status of a specific order. See section below. |
POST | /api/v3/orders/{orderId}/change-delivery | Update delivery method, tracking information, or delivery date on an existing order. See section below. |
API usage
The API uses an asynchronous pattern. This means that when you send in an order it is received, stored and validated in separate processes.
To check the progress of the order receival process, use the /api/v3/orders/jobs status endpoint.
Here are the steps in the order handling process:
Important
Only one order with the same orderId will ever be created.
The order request is posted to the /orders endpoint, where the format is validated.
If the format is valid then "202 Request has been accepted" will be received in the response along with a jobId, a status, the orderId and href, a HTTPS link at the job-status endpoint.
If the order format you sent was wrong, you'll get the response "400 Bad Request" along with a list of errors.
If an order with that orderId already exists, you'll get "409 Order already exists".
Due to asynchronous processing, in a high load scenario multiple requests might create the same order with the same orderId. Here the API might reply “202 Request has been accepted” but the order might already has already been created by another request. The job status endpoint in that case will respond with “409 Order already exists”.
There is also the case where the order data has the correct format, but the contact with the contact data given does not exist in Engage. The system will indicate this by returning a status of "CompletedWithErrors". If this happens, you cannot continue and try to, for example, send an action for that order. In this case, delete the order and create the contact first. Then you can try registering the order again.
The order is now put into order storage.
After the order is stored, the job status endpoint will return a 200 OK with Status: Completed.
Later, the order is connected to a contact and the article and store references are validated.
If a contact is missing a warning is added to the Integration log.
If article or store references are incorrect, a warning is logged to the integration log.
This process is easiest to navigate if you follow this pattern:
Create the order and ensure you get a "202 Request has been accepted" with a jobId in the response.
The next step depends on your integration needs:
If you have no further processing to do on your side, you are done. The "202 Request has been accepted" response means that Engage has received the order and will process and store it.
If you need to continue to work with the order, you can ping the status endpoint with the jobId until you get back a 200 OK with Status: Completed which means the order has been stored and is available to use.
Important
When the errorDetails value is "Version conflict", it indicates that a concurrent operation has been detected. This happens when more than one request tries to perform an update on the same order. The first request starts processing and creates / updates the order asynchronously. A subsequent request, arriving while the first is still finalizing the update, will trigger a version conflict error because the order has already been saved or updated by the first request. This mechanism ensures that every order is created or updated only once.
Details of change-status and change-delivery
These asynchronous endpoints are used for updating the status and delivery details of existing orders. These are useful when you need to keep order information in sync with external systems like warehouses, logistics providers, or ERPs, without replacing the entire order.
Change order status
This endpoint is asynchronous and returns a job reference to allow you to track the update.
POST /api/v3/orders/{orderId}/change-status
Example payload:
{
"status": "InProgress",
"externalStatus": "Picked",
"lastChangedAt": "2025-06-09T10:55:00Z"
}Field | Type | Description |
|---|---|---|
status | string | Current status of order, for example "InProgress", "Completed" |
externalStatus | string (max 255 chars) | Free-text external status ("Reserved", "Shipped") |
lastChangedAt | ISO 8601 datetime | Timestamp indicating the last change on the order |
The expected response is "202 Accepted" along with a location header you can poll for status:
Change order delivery
This endpoint allows you to update the delivery method, tracking information, or delivery date for an existing order.
POST /api/v3/orders/{orderId}/change-delivery
Example payload:
{
"method": "DHL Home Delivery",
"trackingNumber": "1234567890",
"trackingUri": "https://dhl.com/track?1234567890",
"deliveryDate": "2025-06-08T12:00:00Z",
"lastChangedAt": "2025-06-09T10:55:00Z"
}Field | Type | Description |
|---|---|---|
method | string (max 255 chars) | Method of delivery |
trackingNumber | string (max 255 chars) | Tracking number for the delivery. |
trackingUri | URI | Tracking URI for the delivery. |
deliveryDate | ISO 8601 datetime | Expected delivery date/time |
lastChangedAt | ISO 8601 datetime | Timestamp indicating the last change on the order |
The expected response is "202 Accepted" along with a location header you can poll for status:
Use cases
Fulfillment Systems:
Update delivery status post-shipment with real-time data from logistics providers (e.g., DHL, PostNord, Bring).
Warehouse Automation:
Mark an order as “Picked” or “Packed” once physically handled, syncing external warehouse workflow with order status in Voyado.
Omnichannel Coordination :
Retailers using hybrid logistics (e.g., ship-from-store, click & collect) can ensure that Voyado reflects accurate fulfillment progress.
Notes
Omitted fields are treated as intentional nulls and stored as null.
Both endpoints require a valid orderId.
Validation errors and missing orders return 400 or 404 respectively.