====== Order Status API ======
===== What is the Order Status API? =====
The **Order Status API** allows you to retrieve information about the orders placed at i.materialise through your application or website.
===== Who Should Use this API? =====
The **Order Status API** is for users that have placed orders at i.materialise via **[[cart-checkout-api|Cart Checkout API]]** and want to retrieve information about them without using the user interface of i.materialise.
===== Try it Out =====
Do you have questions about how your server can get information about orders? Visiting our demo page will help you out.
We’ve developed a sandbox server, which is an isolated server (not hooked up to a payment system or production environment, allowing you to test the service without getting billed) to try out your code and integration with us. As the sandbox server is an isolated server, it requires different credentials than the production site.
**The demo page of Order Status API on sandbox server:**
https://imatsandbox.materialise.net/api/demo/order-status-api.htm
The sandbox and production server contain API demo pages which send well-formed API requests to our site.
**The demo page of Order Status API on production server:**
https://i.materialise.com/api/demo/order-status-api.htm
===== How Does it Work? =====
This API requires the personal API code. It is therefore not possible to use AJAX requests.
The **Order Status API** works by posting data to our service.
You can use either XML or JSON formats for posting. The HTTP encoding type of a particular request depends on the type of API you are going to use. This will be described in the corresponding section of this page.
To specify the exact content type which your client can accept and parse, the Accept header in your request has to be set to one of the following encoding types:
• text/json\\
• application/json \\
• text/xml\\
• application/xml
The API code needs to be specified in the API code HTTP header.
To get information about the order through the **Order Status API**, POST a well-structured request via “HTTPS” to this URL:
https://i.materialise.com/web-api/order
To use APIs of the sandbox, the POST needs to be submitted to:
https://imatsandbox.materialise.net/web-api/order
The server will return a structured response in XML or JSON which your application can parse.
===== Documentation =====
The order status can be retrieved in different ways:
• by order ID or order number \\
• by date range and order status \\
Which way to use the **Order Status API** depends on whether you’re looking for the status of all orders within a specific period, or the status of one specific order or a set of orders of which you have the order number or order ID. The orders will be selected based upon the provided API code.
==== Structure of the Request ====
General structure of request is
https://[server_name]/web-api/order?id=[OrderID]&number=[OrderNumber]&status=[StatusCode]&dateFrom=[RequestedDateFrom]&dateTo=[RequestedDateTo]
**Request header**
^Parameter ^Type ^Required? ^Explanation^
|Header>''apiCode'' |String (36) required format: GUID |Yes |API code received from i.materialise. This parameter should be sent in the header of the request.|
|Header>''accept'' |String |No(“text/xml” is used by default) |Preferred Content Type: “application/json” or “text/xml”. This parameter should be sent in the header of the request.|
**General Parameters of the Request**
^ Parameter ^ Type ^ Required? ^ Explanation ^
| ''id'' | String (36): GUID | No (if ''number'' is defined in request) | ID of an order generated with the same API code as in the header. \\ \\ This field cannot be used in combination with the ''number''. |
| ''number'' | String (9) | No (if ''id'' is defined in request)| IMC order number of an order generated with the same API code as in the header. \\ \\ This field cannot be used in combination with the ''id''. |
| ''status'' | Integer | No | Code of the order status. Should be one of the following: \\ \\ 0 (Cancelled): if status of the order is “Cancelled” \\ 1 (Invalid): if status of the order is “Draft” or “PaymentNOK” \\ 2 (Ordered): if status of the order is “Ordered” \\ 3 (Processing): if order is in Processing \\ 4 (InProduction): if order is in Production \\ 5 (ReadyToShip): if order is ready to ship \\ 6 (Shipped): if status of the order is “Shipped” \\ 7 (Delivered): if status of the order is “Delivered” \\ \\ If empty, retrieve all statuses. \\ Multiple statuses per request are possible by adding the ''status'' as new parameter. \\ If no status is requested, orders of all statuses will be retrieved. |
| ''dateFrom'' | Date (DD-MM-YYYY) | No | If ''dateFrom'' is not present in the request, [today]-[6 months] is always used by default. |
| ''dateTo'' | Date (DD-MM-YYYY) | No | If ''dateTo'' is not present in the request, [today] is always used by default. |
| ''languageCode'' | String (3) | No | Language of the site pages: {{page>Tips#language&nofooter&noheader}} Default is EN. |
=== Request examples ===
**Example of request # 1**
https://i.materialise.com/web-api/order?id=35b037c5-b3b7-4eee-b542-5657cc6bdfde
**Example of request # 2**
https://i.materialise.com/web-api/order?status=0&status=2&status=3&status=5&status=6&dateFrom=01-11-2014&dateTo=30-11-2014
==== Structure of the Response ====
^ Parameter ^ Type ^ Always shown? ^ Explanation ^
| ''orderId'' | GUID | Yes | Echoed from the request |
| ''orderNumber'' | String (9) | Yes | Echoed from the request |
|''orderconfirmationLink''| String (255) |Yes |Link to order confirmation|
| ''statusCode'' | Integer | Yes | Code of the order status. Is one of the following:\\ \\ 0 (Cancelled): if status of the order is “Cancelled” \\ 1 (Invalid): if status of the order is “Draft” or “PaymentNOK” \\ 2 (Ordered): if status of the order is “Ordered” \\ 3 (Processing): if order is in Processing \\ 4 (InProduction): if order is in Production \\ 5 (ReadyToShip): if order is ready to ship \\ 6 (Shipped): if status of the order is “Shipped” \\ 7 (Delivered): if status of the order is “Delivered” |
| ''statusName'' | String (100) | Yes | Name of the order status. Is one of the following: \\ \\ 0 (Cancelled): if status of the order is “Cancelled” \\ 1 (Invalid): if status of the order is “Draft” or “PaymentNOK” \\ 2 (Ordered): if status of the order is “Ordered” \\ 3 (Processing): if order is in Processing \\ 4 (InProduction): if order is in Production \\ 5 (ReadyToShip): if order is ready to ship \\ 6 (Shipped): if status of the order is “Shipped” \\ 7 (Delivered): if status of the order is “Delivered” |
| ''isOnHold'' | Boolean | Yes | If the order is “on hold”, “true” appears. |
| ''requestedDate'' | Datetime | Yes | Order creation date |
| ''estimatedShipmentDate'' | Datetime | No | Latest shipment date (can be empty if order has not reached status InProcess) |
| ''shipmentDate'' | Datetime | No (shown if status of order is shipped or higher) | Real shipment date (can be not shown) |
| ''deliveryDate'' | Datetime | No (shown if status of order is delivered or higher) | Estimated delivery date |
| ''trackingNumber'' | String (20) | No (shown if status of order is shipped or higher) | Tracking number (can be not shown) |
|''shipmentService'' |String |Yes |Shipment service name|
|''invoiceNumber'' |String (10) |No (shown if status of order is shipped or higher) |IMA invoice number|
|''invoiceLink'' |String' |No (shown if status of order is shipped or higher) |Link to invoice page|
|''creditNoteNumber'' |String (10) |No (shown if status of order is cancelled and CN is created) |ICN credit note number|
| ''requestError'' | List of parameters | No | Show only if “IsCancelled” is set to false |
| ''currency'' | String (3) | Yes | {{page>Tips#currency&nofooter&noheader}} |
| ''totalPrice'' | Decimal, 2 digits after “.” | Yes | Total price value, shipment cost, VAT and discount included. |
| ''orderRemarks'' | String (250) | N | Remarks that were put during [[cart-checkout-api|Cart Checkout]] |
| ''shippingInfo'' | List of parameters | Yes | Parent node for shipping info. It’s empty if orderError appears in the response. |
| ''billingInfo'' | List of parameters | Yes | Parent node for billing Info. It’s empty if orderError appears in the response. |
| ''orderItems'' | List of parameters | Yes | Parent node for list of order items. It’s empty if orderError appears in the response. |
| ''orderError'' | List of parameters | No | Appears only if it’s impossible to find an order |
**Orders> Order> Shipping Info parameters**
Shipping info is empty if order error appears in response.
^ Parameter ^ Type ^ Always shown? ^ Explanation ^
| ''firstName'' | String (100) | Yes | First name |
| ''lastName'' | String (100) | Yes | Last name |
| ''email'' | String (255) | Yes | Email |
| ''phone'' | String (100) | Yes | Phone |
| ''company'' | String (100) | No | Company, shown if ordered by company |
| ''line1'' | String (100) | Yes | Address line 1 |
| ''line2'' | String (100) | No | Address line 2, shown only if was filled on ordering |
| ''countryCode'' | String (2) | Yes | Country code |
| ''stateCode'' | String (100) | No | State code, shown for US and Japan |
| ''zipCode'' | String (100) | Yes | ZIP code |
| ''city'' | String (100) | Yes | City |
**Orders> Order> Billing Info parameters**
Billing info is empty if order error appears in response
^ Parameter ^ Type ^ Always shown? ^ Explanation ^
| ''firstName'' | String (100) | Yes | First name |
| ''lastName'' | String (100) | Yes | Last name |
| ''email'' | String (255) | Yes | Email |
| ''phone'' | String (100) | Yes | Phone |
| ''company'' | String (100) | No | Company, shown if ordered by company |
| ''vatNumber'' | String (100) | No | VAT number, shown only for companies |
| ''line1'' | String (100) | Yes | Address line 1 |
| ''line2'' | String (100) | No | Address line 2, shown only if was filled on ordering |
| ''countryCode'' | String (2) | Yes | Country code |
| ''stateCode'' | String (100) | No | State code, shown for US and Japan |
| ''zipCode'' | String (100) | Yes | ZIP code |
| ''city'' | String (100) | Yes | City |
**Orders> Order> OrderItems> OrderItem parameters**
OrderItem parameters are empty if order error appears in response.
^Parameter ^Type ^Always shown? ^Explanation^
|''cartItemId'' |String (36) required format: GUID |Yes |ID of cart item|
|''cartItemReference'' |String (100) |Yes |Reference provided by API user during the [[cart-item-creation-api|cart item creation]].|
|''toolId'' |String (36) required format: GUID |Yes |Tool ID of created cart item.|
|''modelId'' |String (36) required format: GUID |Yes |ID of model|
|''orderItemName'' |String |Yes |File name of the uploaded model (with extension). This is also used as cart item name in the cart.|
|''previewPictureUrl'' |String |No |Uploaded preview picture filename. (if it was sent in cart item creation)|
|''materialId'' |String (36) required format: GUID |Yes |ID of material|
|''materialName'' |String |Yes |Name of material|
|''finishID'' |String (36) required format: GUID |Yes |ID of finish|
|''finishName'' |String |Yes |Name of finish|
|''xDimMm'' |Decimal (mm) |Yes |Calculated after processing the request X dimension of the model.|
|''yDimMm'' |Decimal (mm) |Yes |Calculated after processing the request Y dimension of the model.|
|''zDimMm'' |Decimal (mm) |Yes |Calculated after processing the request Z dimension of the model.|
|''volumeCm3'' |Decimal, separated by a period |Yes |Volume of the model, cm3|
|''surfaceCm2'' |Decimal, separated by a period |Yes |Total surface of the model, cm2|
|''quantity'' |Integer |Yes |Quantity|
|''orderItemPrice'' |Decimal, 2 digits after “.” |Yes |The price tool owner going to sell this cart item (for the number of models indicated in quantity).|
|''orderItemUnitPrice'' |Decimal, 2 digits after “.” |Yes |Unit sales price, calculated as orderItemPrice/quantity|
=== Response Examples ===
**Example of Response in JSON**
{
"orders":[
{
"orderID":"b1165fff-90e8-49b1-8504-b383b623c505",
"orderNumber":"IMC975578",
"orderconfirmationLink":"https://i.materialise.com/en/ordering/order-confirmation/e1754c8d-2ed1-43ba-a9b3-3e22314600c1",
"statusCode":3,
"statusName":"Processing",
"isOnHold":false,
"requestedDate":"2014-11-17T11:04:49.61",
"estimatedShipmentDate":"2014-12-01T00:00:00",
"currency":"EUR",
"totalPrice":24.78,
"orderRemarks":"Test",
"shippingInfo":{
"firstName":"John",
"lastName":"Smith",
"email":"test@test.com",
"phone":"1234567",
"company":"No company",
"line1":"North Street",
"line2":"",
"countryCode":"US",
"stateCode":"",
"zipCode":"10001",
"city":"New York"
},
"billingInfo":{
"firstName":"John",
"lastName":"Smith",
"email":"test@test.com",
"phone":"1234567",
"company":"No company",
"vatNumber":"BE0999999922",
"line1":"North Street",
"line2":"",
"countryCode":"BE",
"stateCode":"",
"zipCode":"1020",
"city":"Brussels"
},
"orderItems":[
{
"cartItemID":"01ebe0b0-caf4-4f1e-9ad5-abd28f141944",
"cartItemReference":"some reference",
"toolID":"2054608d-b469-4cab-adeb-cf1c0569e7a1",
"modelID":"489eb85e-4c64-457c-a1fe-83187b8e52d8",
"orderItemName":"Box.stl",
"previewPictureUrl":"https://i.materialise.com/Storage/Models/2014/11/489eb85e-4c64-457c-a1fe-83187b8e52d8/Original/preview_small.jpg",
"materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
"materialName":"Polyamide",
"finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
"finishName":"Natural white",
"xDimMm":10,
"yDimMm":10,
"zDimMm":10,
"volumeCm3":1,
"surfaceCm2":6,
"quantity":2,
"orderItemPrice":26,
"orderItemUnitPrice":13
}
]
}
]
}
**Example of Response in XML**
513bc274-205d-4377-88aa-ed3bc81a2bcf
IMC975582
https://i.materialise.com/en/ordering/order-confirmation/e1754c8d-2ed1-43ba-a9b3-3e22314600c1
3
Processing
false
2014-11-17T19:23:27.527
2014-12-01T00:00:00
EUR
24.78
Test
John
Smith
test@test.com
1234567
No company
North Street
US
10001
New York
John
Smith
test@test.com
1234567
No company
BE0999999922
North Street
BE
1020
Brussels
01ebe0b0-caf4-4f1e-9ad5-abd28f141944
some reference
2054608d-b469-4cab-adeb-cf1c0569e7a1
489eb85e-4c64-457c-a1fe-83187b8e52d8
Box.stl
https://i.materialise.com/Storage/Models/2014/11/489eb85e-4c64-457c-a1fe-83187b8e52d8/Original/preview_small.jpg
035f4772-da8a-400b-8be4-2dd344b28ddb
Polyamide
bba2bebb-8895-4049-aeb0-ab651cee2597
Natural white
10.00000000000000000000
10.00000000000000000000
10.00000000000000000000
1.0000000000
6.0000000000
2
26.0000
13.0000
=== Errors Section of the Response ===
**Errors**
^Code^Message^
|103| An unknown StatusCode has been requested; please make sure you request only following status codes: 0 (Cancelled), 1 (Invalid), 2 (Ordered), 3 (Processing), 4 (InProduction), 5 (ReadyToShip), 6 (Shipped), 7 (Delivered).|
|106| Date range is wrong; please make sure DateFrom is older than DateTo.|
|108| No results found matching the requested parameters, please try other parameters.|
**Warnings**
^Code^Message^
|109| This language code is not supported. Please indicate one of the following: {{page>Tips#language&nofooter&noheader}}|
**Example of Response with error in JSON**
{
"orders":[
],
"requestError":{
"message":"No results found matching the requested parameters,
please try other parameters.",
"code":108
}
}
**Example of Response with error in XML**
Date range is wrong; please make sure DateFrom is older than DateTo.
106