Order Cancellation by Number API

What is the Order Cancellation by Number API?

The Order Cancellation APIs allow you to cancel an earlier placed order. Order cancellation is possible as long as the order processing didn’t start. Order can be cancelled by using ID of the order (Order Cancellation by ID API) or order number (Order Cancellation by Number API).

Who Should Use this API?

Everyone who has API access and wants to cancel an order.

Try it Out

Do you have questions about how your server should cancel an order? 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 Cancellation by Number API on sandbox server:

https://imatsandbox.materialise.net/api/demo/order-cancellation-by-number-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 Cancellation by Number API on production server:

https://i.materialise.com/api/demo/order-cancellation-by-number-api.htm

How Does it Work?

This API requires the personal API code. It is therefore not possible to use AJAX requests.

The Order Cancellation by Number 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

To cancel the order through the Order Cancellation by Number API, POST a well-structured request via “HTTPS” to this URL:

https://i.materialise.com/web-api/order/CancelOrderByNumber

To use APIs of the sandbox, the POST needs to be submitted to:

https://imatsandbox.materialise.net/web-api/order/CancelOrderByNumber

The server will return a structured response in XML or JSON which your application can parse.

The API code needs to be specified in the API code HTTP header.

Documentation

The Order Cancellation APIs allow to cancel orders within a short time after the orders were placed. As long as the order was not pushed into the processing queue, cancellation is possible. The Order Cancellation APIs require minimally info to be inserted to cancel an order.

Structure of the Request

Request header

The request could look like this (parameters names are case-sensitive):

Parameter	Type	Required?	Explanation
Header> `apiCode`	String (36), required format: Guid	Yes	API code as provided by i.materialise. This parameter should be sent in header of 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 header of request.

General parameters

Specify the orderNumber to cancel the order.

Parameter	Type	Required?	Explanation
`orderNumber`	String (9)	Yes	Order Number of an order generated with the same API code as in the header.

Request examples

Example of request in JSON

{
 "orderNumber": "IMC975580"
}

Example of request in XML

 
<CancelOrderByNumberRequest>
    <OrderNumber>IMC975582</OrderNumber>
</CancelOrderByNumberRequest>

Structure of the Response

Parameter	Type	Always shown?	Explanation
`orderId`	String (36), required format: Guid	Yes	Order ID that you want to cancel. Echoed from the request
`orderNumber`	String(9)	Yes	Number of order that you want to cancel
`isCanceled`	Boolean	Yes	If order is cancelled successfully return “true”, otherwise – “false”
`requestError`	List of parameters	No	Show only if “IsCancelled” is set to false

Response Examples

Example of Response in JSON

{
    "orderId":"e1754c8d-2ed1-43ba-a9b3-3e22314600c1",
    "orderNumber":"IMC975574",
    "isCanceled":true
}

Example of Response in XML

<CancelOrderResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <OrderId>26bbcc7b-8084-4349-bce9-1ebf46180652</OrderId>
  <OrderNumber>IMC975579</OrderNumber>
  <IsCanceled>true</IsCanceled>
</CancelOrderResponse>

Errors Section of the Response

The parameter “RequestError” is added to the request only if request was not processed successfully.

API Code verification

If a wrong/empty API Code is used, then Error 401 is returned with response statusText=”Unauthorized”.

General errors

Those errors are added to the request only if it is impossible to register order. Value of this parameter is set according to the table below.

Code	Message	Error
HTTP/1.1 500	Internal Server Error (sent in header)	Unknown Error. Try again later. If the problem persists, please contact us. Something went wrong (exception for example).
501	Wrong request body. Check if all parameters set correctly.	The structure of request is wrong (some needed parameters are not found or filled in incorrectly)
503	Please, send OrderNumber of order you want to cancel.	Order Number wasn't defined in request
505	Wrong OrderNumber has been applied.	Order is not found or not registered with the applied API code
506	Order was not placed correctly. Contact us for more details.	Order is found but production status of order is “Draft” or payment status is “PaymentNOK”
507	Order has already been cancelled before.	Order is found but status of order is “Cancelled”
508	Impossible to cancel order. Production has already been started. Contact us for more details.	Order is found but status of order is not one of following: • Ordered • Processing
509	Impossible to cancel order. Order processing has already been started. Contact us for more details.	Order is being processed by engineer so it can not be cancelled.

Example of Response with error in JSON

{
    "isCanceled":false,
    "requestError":{
        "message":"Wrong OrderNumber has been applied.",
        "code":505
    }
}

Example of Response with error in XML

<CancelOrderResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <OrderId>26bbcc7b-8084-4349-bce9-1ebf46180652</OrderId>
  <OrderNumber>IMC975579</OrderNumber>
  <IsCanceled>false</IsCanceled>
  <RequestError>
    <Message>Order has already been cancelled before.</Message>
    <Code>507</Code>
  </RequestError>
</CancelOrderResponse>