Cart Checkout API

The Cart Checkout API allows you to checkout carts and order them. The carts to check out have to be created through the Cart Creation API.

The Cart Checkout API is meant for applications that place orders directly to i.materialise without redirecting the users of the application to the i.materialise.com site.

Do you have questions about how your server should checkout carts and order them? 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 Checkout API on sandbox server:

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

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

Try out your API code on the demo page. Make sure you don’t mix up API codes of the sandbox and the production site.

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

The Cart Checkout 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 APICode HTTP header.

To checkout and order cart through the Cart Checkout API, POST a well-structured request via “HTTPS” to this URL:

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

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

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

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

You should create HTTP multipart request to be able to send Delivery Note and Invoice files. HTTP multipart request is a type of HTTP request that HTTP clients construct to send file and data over to the server side.

The Cart Checkout API requires that minimally following info is inserted to check out the cart:

- The cart ID that was obtained through the Cart Creation API. The shipment and billing info needs to be filled in in the Cart.
- The shipment service you prefer.

Request header

Request body

Request example

Accept:text/xml
...
APICode:A1F1BAE8-3F1B-4B8D-8D95-D19E17595034
..
Content-Type:multipart/form-data; boundary=----WebKitFormBoundarywjsY9C5toeYrThmi
...

------WebKitFormBoundarywjsY9C5toeYrThmi
Content-Disposition: form-data; name="data"; filename="blob"
Content-Type: text/xml

------WebKitFormBoundarywjsY9C5toeYrThmi
Content-Disposition: form-data; name="MyInvoiceFile"; filename="INVOICE_TEST.pdf"
Content-Type: application/octet-stream

------WebKitFormBoundarywjsY9C5toeYrThmi
Content-Disposition: form-data; name="MyDeliveryNoteFile"; filename="DN_TEST.pdf"
Content-Type: application/octet-stream

General parameters

Example of request in JSON

{
   "cartID":"847b8092-8662-4c78-bcc5-5b7099fecb9d",
   "myOrderReference":"test",
   "directMailingAllowed":"false",
   "shipmentService":"SecondDayAir",
   "myInvoiceLink":"http://mysite.com/invoice.pdf",
   "myDeliveryNoteLink":"http://mysite.com/deliverynote.pdf",
   "remarks":"qwerty",
   "languageCode":"de"
}

Example of request in XML

 
<OrderRegistrationRequest>
    <CartID>847b8092-8662-4c78-bcc5-5b7099fecb9d</CartID>
    <MyOrderReference>OrderReferenceTest</MyOrderReference>
    <DirectMailingAllowed>false</DirectMailingAllowed>
    <ShipmentService>Ground</ShipmentService>
    <MyInvoiceLink></MyInvoiceLink>
    <MyDeliveryNoteLink></MyDeliveryNoteLink>
    <Remarks>Test</Remarks>
    <LanguageCode>fr</LanguageCode>
</OrderRegistrationRequest>

General Information

OrderItem information (OrderItems>OrderItem section) This section is shown for all items added to the cart.

Shipment Information (ShipmentInfo section)

This section is not added to the response if RequestError appers.

Billing Information (BillingInfo section)

This section is not added to the response if RequestError appers.

Example of Response in JSON

{
    "orderNumber":"IMC975574",
    "orderID":"e1754c8d-2ed1-43ba-a9b3-3e22314600c1",
    "requestNumber":"REQ696922",
    "directMailingAllowed":false,
    "cartID":"847b8092-8662-4c78-bcc5-5b7099fecb9d",
    "myOrderReference":"test",
    "currency":"EUR",
    "remarks":"qwerty",
    "myInvoiceLink":"http://mysite.com/invoice.pdf",
    "myDeliveryNoteLink":"http://mysite.com/deliverynote.pdf",
    "iMatConfirmationUrl":"https://i.materialise.com/de/ordering/order-confirmation/e1754c8d-2ed1-43ba-a9b3-3e22314600c1",
    "iMatConfirmationUrlIframe":"https://i.materialise.com/embeded/general/de/ordering/order-confirmation/e1754c8d-2ed1-43ba-a9b3-3e22314600c1",
    "hasInvoiceFile":true,
    "hasDeliveryNoteFile":true,
    "subTotalPrice":26.0000,
    "shipmentCost":12.88,
    "discount":10.0000,
    "vatTax":0.00,
    "totalPrice":28.88,
    "warning":{
        "message":"If Delivery Note or Invoice is provided by you,
         i.materialise cannot be heldresponsible for potential differences  for what is on the document and what is actually shipped",
        "code":200
    },
    "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.00000000000000000000,
            "yDimMm":10.00000000000000000000,
            "zDimMm":10.00000000000000000000,
            "volumeCm3":1.0000000000,
            "surfaceCm2":6.0000000000,
            "quantity":2,
            "orderItemPrice":26.0000,
            "orderItemUnitPrice":13.0000
        }
    ],
    "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"
    }
}

Example of Response in XML

<OrderRegistrationResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <OrderNumber>IMC975575</OrderNumber>
  <OrderID>d6399ee3-7465-4ada-9726-eeba1861aaf2</OrderID>
  <RequestNumber>REQ696922</RequestNumber>
  <DirectMailingAllowed>false</DirectMailingAllowed>
  <CartID>847b8092-8662-4c78-bcc5-5b7099fecb9d</CartID>
  <MyOrderReference>OrderReferenceTest</MyOrderReference>
  <Currency>EUR</Currency>
  <Remarks>Test</Remarks>
  <MyInvoiceLink />
  <MyDeliveryNoteLink />
  <IMatConfirmationUrl>https://i.materialise.com/fr/ordering/order-confirmation/d6399ee3-7465-4ada-9726-eeba1861aaf2</IMatConfirmationUrl>
  <IMatConfirmationUrlIframe>https://i.materialise.com/embeded/general/fr/ordering/order-confirmation/d6399ee3-7465-4ada-9726-eeba1861aaf2</IMatConfirmationUrlIframe>
  <HasInvoiceFile>true</HasInvoiceFile>
  <HasDeliveryNoteFile>true</HasDeliveryNoteFile>
  <SubTotalPrice>26.0000</SubTotalPrice>
  <ShipmentCost>8.78</ShipmentCost>
  <Discount>10.0000</Discount>
  <VatTax>0.00</VatTax>
  <TotalPrice>24.78</TotalPrice>
  <Warning>
    <Message>If Delivery Note or Invoice is provided by you, i.materialise cannot be heldresponsible for potential differences  for what is on the document and what is actually shipped</Message>
    <Code>200</Code>
  </Warning>
  <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>
  <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>
</OrderRegistrationResponse>

The parameter RequestError will be added if request was NOT processed successfully. If the request was NOT processed successfully, the OrderItems, ShippingInfo, BillingInfo and ShipmentCost sections will be empty.

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.

Warnings

Parameter “Warning” is added according to the table below.

Example of Response with error in JSON

{
    "orderID":"00000000-0000-0000-0000-000000000000",
    "directMailingAllowed":false,
    "cartID":"00000000-0000-0000-0000-000000000000",
    "hasInvoiceFile":false,
    "hasDeliveryNoteFile":false,
    "subTotalPrice":0.0,
    "shipmentCost":0.0,
    "discount":0.0,
    "vatTax":0.0,
    "totalPrice":0.0,
    "requestError":{
        "message":"Wrong ShipmentService has been applied.",
        "code":123
    },
    "warning":{
        "message":"If Delivery Note or Invoice is provided by you,
         i.materialise cannot be heldresponsible for potential differences  for what is on the document and what is actually shipped",
        "code":200
    },
    "orderItems":[
        
    ],
    "shippingInfo":{
        
    },
    "billingInfo":{
        
    }
}

Example of Response with error in XML

<OrderRegistrationResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <OrderID>00000000-0000-0000-0000-000000000000</OrderID>
  <DirectMailingAllowed>false</DirectMailingAllowed>
  <CartID>00000000-0000-0000-0000-000000000000</CartID>
  <HasInvoiceFile>false</HasInvoiceFile>
  <HasDeliveryNoteFile>false</HasDeliveryNoteFile>
  <SubTotalPrice>0</SubTotalPrice>
  <ShipmentCost>0</ShipmentCost>
  <Discount>0</Discount>
  <VatTax>0</VatTax>
  <TotalPrice>0</TotalPrice>
  <RequestError>
    <Message>Please, use either a MyDeliveryNoteLink or a DeliveryNoteFile, but not both.</Message>
    <Code>111</Code>
  </RequestError>
  <Warning>
    <Message>If Delivery Note or Invoice is provided by you, i.materialise cannot be heldresponsible for potential differences  for what is on the document and what is actually shipped</Message>
    <Code>200</Code>
  </Warning>
  <OrderItems />
  <ShippingInfo />
  <BillingInfo />
</OrderRegistrationResponse>