Site Tools

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

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

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

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

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 

https://[server_name]/web-api/cartstatus/statuses

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 

{
    "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"
        },]
}

Example of request in XML 

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

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 

{
    "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"
        }
    ]
}

Response example in XML 

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

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 

{
    "carts":[
        {
            "cartID":"921A2046-66A5-4C5F-B9A6-4BC646FA5E5",
            "cartError":{
                "message":"Specified Cart was not found or wrong format.",
                "code":101
            }
        }
    ]
}

Example of Response with error in XML 

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