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

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

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

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

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

<code>
{
 "orderNumber": "IMC975580"
}
</code>

**Example of request in XML**

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

==== 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**

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

**Example of Response in XML**

<code>
<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>
</code>

===  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**

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

**Example of Response with error in XML**

<code>
<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>
</code>