Skip to main content
The v3 Order API is described in more detail in the Swagger definition.

​
Orders endpoints summary

Here follows a summary of the endpoints and what they are used for.

​
Get orders by contact

GET /api/v3/orders
Returns a paged result with links that can be used to get the next or previous result set (default of 10 results per request).

​
Register a new order

POST /api/v3/orders
Creates an order. The creation is asynchronous. Use the information in the response to follow the progress and catch any errors OR send an embedded order action in the payload which will be used when the new order is created.

​
Get a specific order

GET /api/v3/orders/{orderId}
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.

​
Replace an order

PUT /api/v3/orders/{orderId}
Replaces an order. The replacement is asynchronous. Use the information in the response to follow the progress and catch any errors OR send an embedded order action in the payload which will be used when the order is replaced.
The order must be replaced entirely and not partially.

​
Delete an order

DELETE /api/v3/orders/{orderId}
Deletes an order. The deletion is asynchronous. Use the information in the response to follow the progress and catch any errors.

​
Get status of asynchronous request

GET /api/v3/orders/jobs/{jobId}
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.

​
Trigger action

POST /api/v3/orders/{orderId}/action
Trigger action events for a specific order.

​
Update status

POST /api/v3/orders/{orderId}/change-status
Update the internal and/or external status of a specific order.

​
Update delivery method

POST /api/v3/orders/{orderId}/change-delivery
Update delivery method, tracking information, or delivery date on an existing order.

​
Reacting to a requested change

When you request for an order to be changed or created in the system, you might then want to react to it, for example by sending a confirmation email. There are two ways you can handle this:
  1. Use the job reference ID that is returned in the response to poll Engage and see when the requested change is done (which is when the job status has the value “Completed”).
  2. include an embedded order action in the payload of your update/create request to instruct Engage what to do when the change is completed. This is similar to sending an order action to the /action endpoint, except you don’t have to poll for “Completed” status.
See more about order actions here. If using option 2, the order action parameter you’ll send in the request payload will have this structure: 
...
"orderAction": {
    "action": "ConfirmOrder",
    "language": "en-US",
    "data": { ... }
}
...
​
action
string
required
Must be one of:
  • ConfirmOrder
  • ConfirmDelivery
  • ConfirmShipment
  • ConfirmCancellation
  • ConfirmCompletion
  • Custom
​
language
string
Optional UI language tag.
​
data
string
required
Custom personalization data, used by the automation trigger.
This order action, as soon as the change you’ve requested is completed, will cause the Order Action automation trigger to be executed with whatever data you’ve placed in the “data” property. For example, to send an email. When you POST or PUT an order containing an embedded order action, be aware that the embedded action will only be executed if the order is successfully processed and reaches the status “Completed”. If processing fails, due to data validation errors for example, any embedded action will be discarded and may need to be applied manually. To be absolutely sure, extra verification using the job ID can be added.

​
Steps in the order handling process

Here are the general steps in the order handling process: Only one order with the same orderId will ever be created.
  1. 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 given does not exist in Engage. The system will indicate this by returning a status of “CompletedWithErrors”. If this happens, you cannot continue, for example to try and send an action for that order. In this case, you will have to delete the order and create the contact first. Then you can try registering the order again.
  2. The order is now put into order storage.
  3. After the order is stored, the job status endpoint will return a 200 OK with Status: Completed.
  4. 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:
  1. Create the order and ensure you get a “202 Request has been accepted” with a jobId in the response. If you intend to use an embedded order action, make sure to place it in your request payload.
  2. 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 working with the order, poll the status endpoint with the jobId until you get a 200 OK with Status: Completed which means the order has been stored and is ready to use. Or, if you sent an embedded order action in the payload, this will now be automatically triggered.
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.

​
More about 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

The endpoint used to change the order status is: 
POST /api/v3/orders/{orderId}/change-status
This endpoint is asynchronous. It returns a job ID which you can use to track the progress of the update. Alternatively you can send an order action in the payload as described above.
Example payload
{   
  "status": "InProgress",   
  "externalStatus": "Picked",   
  "lastChangedAt": "2025-06-09T10:55:00Z",
  "orderAction": {
     "action": "ConfirmOrder",
     "language": "en-US",
     "data": { ... }
   }
}
​
status
string
Current status of order:
  • “InProgress”
  • “Completed”
  • “Cancelled”
​
externalStatus
string (max 255 chars)
Free-text external status (“Reserved”, “Shipped”).
​
lastChangedAt
ISO 8601 datetime
Timestamp indicating the last change on the order.
​
lastChangedAt
object
Optional. The data that will be sent to the Order Action automation trigger as soon as the requested change is completed.

​
Response

The expected response is 202 Accepted along with a location header you can poll for the status.

​
Change order delivery

This endpoint allows you to update the delivery method, the tracking information, or the 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",
  "orderAction": {
     "action": "ConfirmDelivery",
     "language": "en-US",
     "data": { ... }
   }
}
​
method
string (max 255 chars)
required
Method of delivery.
​
trackingNumber
string (max 255 chars)
Tracking number for the delivery.
​
trackingUri
URI
Tracking number for the delivery.
​
deliveryDate
ISO 8601 datetime
Expected delivery date/time.
​
lastChangedAt
ISO 8601 datetime
Timestamp indicating the last change on the order.
​
orderAction
object
The data that will be sent to the Order Action automation trigger as soon as the requested change is completed.

​
Response

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 and collect) can ensure that Voyado reflects accurate fulfillment progress.
Other things to remember:
  • 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.