====== Cart Status API ======

===== What is the Cart Status API? =====

The **Cart Status API** allows you to retrieve information about the status of an API-created cart.

===== Who Should Use this API? =====

The **Cart Status API** is for Users that have created Carts at i.materialise via **[[cart-creation-api|Cart Creation API]]** and forward their Customers to the Cart, Shipping or Payment web page of i.materialise.
This api provides the information whether the Customer placed the Order on the i.materialise website or not and returns the OrderID in case the Order was placed. This OrderID can be used in the **[[order-status-api|Order Status API]]** to get the Order information. 

The returned status can also be used to check whether an extra Item can still be added to the Cart via **[[add-remove-cart-item-api|Add/Remove Cart Item API]]** and whether the Customer checked out the Cart.

===== 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 Cart Status API on sandbox server:**

https://imatsandbox.materialise.net/api/demo/cart-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 Cart Status API on production server:**

https://i.materialise.com/api/demo/cart-status-api.htm

===== How Does it Work? =====

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

The **Cart 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 **Cart Status API**, POST a well-structured request via “HTTPS” to this URL:

<code>https://i.materialise.com/web-api/cartstatus/statuses</code>

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

<code>https://imatsandbox.materialise.net/web-api/cartstatus/statuses</code>

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


===== Documentation =====

==== Structure of the Request ====

General structure of request is

<code>https://[server_name]/web-api/cartstatus/statuses</code>

**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^
|''CartID''	|List of parameters	|Yes	|List of CartIDs. Number of CartIDs should be less than 10.|

=== Request examples ===

**Example of request in JSON**

<code>
{
    "Carts":[
        {
            "CartID": "921A2046-66A5-4C5F-B9A6-4BC646FA5E5A"
        },
        {
            "CartID": "BEE2C269-1DBD-4F67-B9F1-2EA2D3B4917B"
        },
        { 
            "CartID": "59DCCA18-05E7-4F5C-8B4E-89E987EA1E51"
        },
        { 
            "CartID": "5922CA18-05E7-4F5C-8B4E-89E987EA1E51"
        },]
}
</code>

**Example of request in XML**

<code> 
<CartStatusRequest>
    <Carts>
        <Cart>
            <CartID>34ad83cc-d418-4fcd-81f5-b7f38026865f</CartID>
        </Cart>
    </Carts>
</CartStatusRequest>
</code>

==== Structure of the Response ====

^Parameter	^Type	^Always shown?	^Explanation^
|''CartID''	|GUID	|Yes	|The ID of the Cart got from Cart Creation API that was specified in the request.|
|''CartStatus''	|ENUM	|Yes	|Current status of the cart. Possible values are: \\ \\ * Not Ordered – Cart was created over the API but it wasn’t visualized for the Customer on UI \\ \\ * Pending – Cart is open and Items can still be added to the Cart but Cart should be re-opened on UI after that. \\ \\ * Checked Out – Customer started the Ordering Flow, items shouldn’t be added to the same Cart \\ \\ * Ordered – Cart was ordered by the Customer. API returns the ID of the corresponding Order.|
|''CartCreationDateTime''	|DateTime	|Yes	|Cart creation date.|
|''OrderID''	|GUID	|No	|ID of corresponding Order if the cart was converted to the Order. |

=== Response Examples ===

If the request is processed successfully, the response looks like this:

**Response example in JSON**
<code>
{
    "carts":[
        {
            "cartID":"921a2046-66a5-4c5f-b9a6-4bc646fa5e5a",
            "cartCreationDateTime":"2017-06-13T16:28:47",
            "orderID":"7cf9f78f-6631-44be-905a-94cee7a2cd9c",
            "cartStatus":"Ordered"
        },
        {
            "cartID":"bee2c269-1dbd-4f67-b9f1-2ea2d3b4917b",
            "cartCreationDateTime":"2017-06-14T16:46:55.473",
            "cartStatus":"CheckedOut"
        },
        {
            "cartID":"59dcca18-05e7-4f5c-8b4e-89e987ea1e51",
            "cartCreationDateTime":"2017-06-13T14:12:42.933",
            "cartStatus":"Pending"
        }
    ]
}
</code>

**Response example in XML**
<code>
<CartStatusResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Carts>
    <Cart>
      <CartID>921a2046-66a5-4c5f-b9a6-4bc646fa5e5a</CartID>
      <CartCreationDateTime>2017-06-13T16:28:47</CartCreationDateTime>
      <OrderID>7cf9f78f-6631-44be-905a-94cee7a2cd9c</OrderID>
      <CartStatus>Ordered</CartStatus>
    </Cart>
  </Carts>
</CartStatusResponse>
</code>

==== Errors ====

=== API code verification ===
If a wrong/empty API code is used, then a 401 error is returned with the response statusText=”Unauthorized”.

=== General errors ===
The parameter “Error” is added to the request only if the request wasn’t processed successfully. The value of this parameter is set according to the table below. 

^ Code ^ Message ^
| 1 | Unknown error | 
| 501 | Wrong request body. Check if all parameters are set correctly. | 
| 101 | Specified Cart was not found or wrong format. | 
| 102 | You can check no more than 10 CartIDs per one request. | 


**Example of Response with error in JSON**
<code>
{
    "carts":[
        {
            "cartID":"921A2046-66A5-4C5F-B9A6-4BC646FA5E5",
            "cartError":{
                "message":"Specified Cart was not found or wrong format.",
                "code":101
            }
        }
    ]
}
</code>

**Example of Response with error in XML**
<code>
<CartStatusResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Carts>
    <Cart>
      <CartID>34ad83cc-d418-4fcd-81f5-b7f38026865f</CartID>
      <CartError>
        <Message>Specified Cart was not found or wrong format.</Message>
        <Code>101</Code>
      </CartError>
      <CartCreationDateTime xsi:nil="true" />
      <OrderID xsi:nil="true" />
    </Cart>
  </Carts>
</CartStatusResponse>
</code>