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. |
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 "302 Found", which means that the order has been correctly stored and is available for updates.