Site Tools

This is an old revision of the document!


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 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:

en/de/fr

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

Following currencies are supported: EUR/USD/JPY/GBP.

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
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.
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

<OrderRetrievalResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Orders>
    <Order>
      <OrderID>513bc274-205d-4377-88aa-ed3bc81a2bcf</OrderID>
      <OrderNumber>IMC975582</OrderNumber>
      <OrderconfirmationLink>https://i.materialise.com/en/ordering/order-confirmation/e1754c8d-2ed1-43ba-a9b3-3e22314600c1</OrderconfirmationLink>
      <StatusCode>3</StatusCode>
      <StatusName>Processing</StatusName>
      <IsOnHold>false</IsOnHold>
      <RequestedDate>2014-11-17T19:23:27.527</RequestedDate>
      <EstimatedShipmentDate>2014-12-01T00:00:00</EstimatedShipmentDate>
      <ShipmentDate xsi:nil="true" />
      <DeliveryDate xsi:nil="true" />
      <Currency>EUR</Currency>
      <TotalPrice>24.78</TotalPrice>
      <OrderRemarks>Test</OrderRemarks>
      <ShippingInfo>
        <FirstName>John</FirstName>
        <LastName>Smith</LastName>
        <Email>test@test.com</Email>
        <Phone>1234567</Phone>
        <Company>No company</Company>
        <Line1>North Street</Line1>
        <Line2 />
        <CountryCode>US</CountryCode>
        <StateCode />
        <ZipCode>10001</ZipCode>
        <City>New York</City>
      </ShippingInfo>
      <BillingInfo>
        <FirstName>John</FirstName>
        <LastName>Smith</LastName>
        <Email>test@test.com</Email>
        <Phone>1234567</Phone>
        <Company>No company</Company>
        <VatNumber>BE0999999922</VatNumber>
        <Line1>North Street</Line1>
        <Line2 />
        <CountryCode>BE</CountryCode>
        <StateCode />
        <ZipCode>1020</ZipCode>
        <City>Brussels</City>
      </BillingInfo>
      <OrderItems>
        <OrderItemResponseDto>
          <CartItemID>01ebe0b0-caf4-4f1e-9ad5-abd28f141944</CartItemID>
          <CartItemReference>some reference</CartItemReference>
          <ToolID>2054608d-b469-4cab-adeb-cf1c0569e7a1</ToolID>
          <ModelID>489eb85e-4c64-457c-a1fe-83187b8e52d8</ModelID>
          <OrderItemName>Box.stl</OrderItemName>
          <PreviewPictureUrl>https://i.materialise.com/Storage/Models/2014/11/489eb85e-4c64-457c-a1fe-83187b8e52d8/Original/preview_small.jpg</PreviewPictureUrl>
          <MaterialID>035f4772-da8a-400b-8be4-2dd344b28ddb</MaterialID>
          <MaterialName>Polyamide</MaterialName>
          <FinishID>bba2bebb-8895-4049-aeb0-ab651cee2597</FinishID>
          <FinishName>Natural white</FinishName>
          <XDimMm>10.00000000000000000000</XDimMm>
          <YDimMm>10.00000000000000000000</YDimMm>
          <ZDimMm>10.00000000000000000000</ZDimMm>
          <VolumeCm3>1.0000000000</VolumeCm3>
          <SurfaceCm2>6.0000000000</SurfaceCm2>
          <Quantity>2</Quantity>
          <OrderItemPrice>26.0000</OrderItemPrice>
          <OrderItemUnitPrice>13.0000</OrderItemUnitPrice>
        </OrderItemResponseDto>
      </OrderItems>
    </Order>
  </Orders>
</OrderRetrievalResponse>

Errors Section of the Response

Example of Response with error in JSON

CodeMessage
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.
{
    "orders":[
        
    ],
    "requestError":{
        "message":"No results found matching the requested parameters,
         please try other parameters.",
        "code":108
    }
}

Example of Response with error in XML

<OrderRetrievalResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Orders />
  <RequestError>
    <Message>Date range is wrong; please make sure DateFrom is older than DateTo.</Message>
    <Code>106</Code>
  </RequestError>
</OrderRetrievalResponse>