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. |
API usage
When using the API, bear in mind that it 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 order ID will ever be created.
The order request is posted to the API, where the format is automatically validated.
If the format is valid, a "202 Accepted" will be received in the response along with a job ID and a link to the job-status endpoint.
If the order format is wrong, you'll get the response "400 BadRequest" along with a list of errors.
If an order with that order ID already exists, you'll get "409 Conflict - order with OrderId already exists".
Due to asynchronous processing, in a high load scenario where multiple requests create the same order with the same order ID, the API might reply “202 Accepted” but the order might already has already been created by another request. The job status endpoint will then reply “409 Conflict”.
The order is now put into order storage.
After the order is stored, the job status endpoint will return a 302 Redirect to the new resource.
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 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 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.