Cart Creation API

The Cart Creation API allows you to create a cart. Preparing a cart is a 2 step approach. First, cart items need to be created. Then these cart items need to be added to a cart. These 2 actions are done through 2 separate APIs: the Cart Item Creation API and Cart Creation API. The split up is done to allow maximum flexibility in the creation of a cart. However, one cannot used without the other one.

The Cart Creation API is for users that have an application or website that generates 3D models. The 3D models can be uploaded or retrieved by our server. You either want to add a 3D print service to your application as an option, or you want to make models 3D printing the core of your business. The Cart Creation API can be used for the following business flows:

• White label approach: Your application or website uses the Cart Item Creation API and Cart Creation API in combination with the Cart Checkout API to place the order on your behalf at our back end system. The payment of your customer will then be handled by your application or website.
• Controlled cart approach: After the creation of a cart, your server reroutes the customer to i.materialise where the customer proceeds with the order. Our server will provide rerouting URLs to the i.materialise cart or the i.materialise shipping info page. There will also be links to embeddable pages.

Do you have questions about how your server should create cart with cart items? 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 Creation API on sandbox server:

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

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

The Cart Creation 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 create cart through the Cart Creation API, POST a well-structured request via “HTTPS” to this URL:

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

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

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

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

All requests to the Cart Creation API should be made through a secure connection (e.g. SSL). Cart and cart items will stay valid for a period of 15 days.

In order to register a cart you need to provide the set of valid cart item IDs that were the result of the cart item registrations.

A cart registration consists of following data:

• A list of cart item IDs to add to the cart
• URL information
• Shipping info to prepare checkout of the cart and get a shipment cost estimation
• Billing info to prepare checkout of the cart

{
    "MyCartReference": "My cart",
    "Currency": "USD",
    "LanguageCode": "de",
    "ReturnUrl": "http://mysite.com/success.html",
    "OrderConfirmationUrl": "http://mysite.com/confirm.html",
    "FailureUrl": "http://mysite.com/failure.html",
    "CartItems":[
       { 
          "CartItemID": "1bcc76b0-c437-46de-9c3f-93ec919f8234"
          
       },
       { 
          "CartItemID": "059a45de-6185-4cf9-b694-8b6f3c57c4f2"
          
       },
],
    "ShippingInfo": {
      "FirstName": "John",
      "LastName": "Smith",
      "Email": "demo@demo.com",
      "Phone": "1234567",
      "Company": "No company",
      "Line1": "North Street",
      "CountryCode": "US",
      "StateCode":"NY",
      "ZipCode": "10001",
      "City": "New York"
    },
    "BillingInfo": {
      "FirstName": "John",
      "LastName": "Smith",
      "Email": "demo@demo.com",
      "Phone": "1234567",
      "Company": "No company",
      "Line1": "North Street",
      "CountryCode": "BE",
      "ZipCode": "1020",
      "City": "Brussels",
      "VatNumber": "BE0999999922"
    }
}

 
<CartRegistrationRequest>
  <MyCartReference>My cart</MyCartReference>
  <Currency>USD</Currency>
  <LanguageCode>fr</LanguageCode>
  <IframeTheme />
  <ReturnUrl>http://mysite.com/success.html</ReturnUrl>
 <OrderConfirmationUrl>http://mysite.com/confirm.html</OrderConfirmationUrl>
  <FailureUrl>http://mysite.com/failure.html</FailureUrl>
  <CartItems>
    <CartItem>
      <CartItemID>77c51365-e732-4d52-84a9-2d4e7777a52b</CartItemID>
    </CartItem>
    <CartItem>
      <CartItemID>36590f9e-5c2e-4a46-af63-2299a0f6b87b</CartItemID>
    </CartItem>
  </CartItems>
  <ShippingInfo>
    <FirstName>John</FirstName>
    <LastName>Smith</LastName>
    <Email>demo@demo.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>demo@demo.com</Email>
    <Phone>1234567</Phone>
    <Company>No company</Company>
    <Line1>North Street</Line1>
    <Line2 />
    <CountryCode>BE</CountryCode>
    <ZipCode>1020</ZipCode>
    <City>Brussels</City>
    <VatNumber>BE0999999922</VatNumber>
  </BillingInfo>
</CartRegistrationRequest>

<CartRegistrationResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <CartID>d7964c2c-0645-4b55-acb5-8b40fdf5b312</CartID>
  <CartReference>My cart</CartReference>
  <Currency>USD</Currency>
  <IMatCartPageUrl>https://i.materialise.com/de/cart/quotation/d7964c2c-0645-4b55-acb5-8b40fdf5b312</IMatCartPageUrl>
  <IMatShipmentPageUrl>https://i.materialise.com/de/ordering/quotation/d7964c2c-0645-4b55-acb5-8b40fdf5b312</IMatShipmentPageUrl>
  <IMatEmbededCartPageUrl>https://i.materialise.com/embeded/general/de/cart/quotation/d7964c2c-0645-4b55-acb5-8b40fdf5b312</IMatEmbededCartPageUrl>
  <IMatEmbededShipmentPageUrl>https://i.materialise.com/embeded/general/de/ordering/quotation/d7964c2c-0645-4b55-acb5-8b40fdf5b312</IMatEmbededShipmentPageUrl>
  <Discount>0.0000</Discount>
  <SubTotalPrice>64.90</SubTotalPrice>
  <VatTaxPercentage>0.00</VatTaxPercentage>
  <ValidUntil>2014-12-24T00:00:00+01:00</ValidUntil>
  <ExpectedShipmentDate>2014-12-23T00:00:00+01:00</ExpectedShipmentDate>
  <ShipmentDateComment>If ordered today, 90% certainty that it is shipped before or at this date.</ShipmentDateComment>
  <RequestNumber>REQ582082</RequestNumber>
  <ShipmentCost>
    <Services>
      <Service>
        <Name>Ground</Name>
        <Value>10.94</Value>
        <DaysInTransit>3</DaysInTransit>
      </Service>
      <Service>
        <Name>SecondDayAir</Name>
        <Value>15.91</Value>
        <DaysInTransit>2</DaysInTransit>
      </Service>
      <Service>
        <Name>NextDayAirSaver</Name>
        <Value>33.88</Value>
        <DaysInTransit>1</DaysInTransit>
      </Service>
    </Services>
  </ShipmentCost>
  <CartItems>
    <CartItemResponseDto>
      <MyCartItemReference>some reference</MyCartItemReference>
      <CartItemID>77c51365-e732-4d52-84a9-2d4e7777a52b</CartItemID>
      <ToolID>2054608d-b469-4cab-adeb-cf1c0569e7a1</ToolID>
      <ModelID>6a24345b-42ff-4d6c-8c0b-4037c4205b88</ModelID>
      <ModelFileName>Box.stl</ModelFileName>
      <MaterialID>035f4772-da8a-400b-8be4-2dd344b28ddb</MaterialID>
      <FinishID>bba2bebb-8895-4049-aeb0-ab651cee2597</FinishID>
      <Quantity>1</Quantity>
      <XDimMm>10.00000000000000000000</XDimMm>
      <YDimMm>10.00000000000000000000</YDimMm>
      <ZDimMm>10.00000000000000000000</ZDimMm>
      <VolumeCm3>1.0000000000</VolumeCm3>
      <SurfaceCm2>6.0000000000</SurfaceCm2>
      <MySalesPrice>32.45</MySalesPrice>
      <IMatPrice>18.72</IMatPrice>
      <MySalesUnitPrice>32.45</MySalesUnitPrice>
    </CartItemResponseDto>
    <CartItemResponseDto>
      <MyCartItemReference>some reference</MyCartItemReference>
      <CartItemID>36590f9e-5c2e-4a46-af63-2299a0f6b87b</CartItemID>
      <ToolID>2054608d-b469-4cab-adeb-cf1c0569e7a1</ToolID>
      <ModelID>6a24345b-42ff-4d6c-8c0b-4037c4205b88</ModelID>
      <ModelFileName>Box.stl</ModelFileName>
      <MaterialID>035f4772-da8a-400b-8be4-2dd344b28ddb</MaterialID>
      <FinishID>bba2bebb-8895-4049-aeb0-ab651cee2597</FinishID>
      <Quantity>1</Quantity>
      <XDimMm>10.00000000000000000000</XDimMm>
      <YDimMm>10.00000000000000000000</YDimMm>
      <ZDimMm>10.00000000000000000000</ZDimMm>
      <VolumeCm3>1.0000000000</VolumeCm3>
      <SurfaceCm2>6.0000000000</SurfaceCm2>
      <MySalesPrice>32.45</MySalesPrice>
      <IMatPrice>18.72</IMatPrice>
      <MySalesUnitPrice>32.45</MySalesUnitPrice>
    </CartItemResponseDto>
  </CartItems>
  <ShippingInfo>
    <FirstName>John</FirstName>
    <LastName>Smith</LastName>
    <Email>demo@demo.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>demo@demo.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>
</CartRegistrationResponse>

{
    "cartID":"a1b27d90-4a3a-4a25-be1f-71a62eb0e78e",
    "cartReference":"My cart",
    "currency":"USD",
    "iMatCartPageUrl":"https://i.materialise.com/fr/cart/quotation/a1b27d90-4a3a-4a25-be1f-71a62eb0e78e",
    "iMatShipmentPageUrl":"https://i.materialise.com/fr/ordering/quotation/a1b27d90-4a3a-4a25-be1f-71a62eb0e78e",
    "iMatEmbededCartPageUrl":"https:/i.materialise.com/embeded/general/fr/cart/quotation/a1b27d90-4a3a-4a25-be1f-71a62eb0e78e",
    "iMatEmbededShipmentPageUrl":"https://i.materialise.com/embeded/general/fr/ordering/quotation/a1b27d90-4a3a-4a25-be1f-71a62eb0e78e",
    "discount":0.0000,
    "subTotalPrice":64.90,
    "vatTaxPercentage":0.00,
    "validUntil":"2014-12-24T00:00:00+01:00",
    "expectedShipmentDate":"2014-12-23T00:00:00+01:00",
    "shipmentDateComment":"If ordered today,
     90% certainty that it is shipped before or at this date.",
    "requestNumber":"REQ209809",
    "shipmentCost":{
        "services":[
            {
                "name":"Ground",
                "value":10.94,
                "daysInTransit":3
            },
            {
                "name":"SecondDayAir",
                "value":15.91,
                "daysInTransit":2
            },
            {
                "name":"NextDayAirSaver",
                "value":33.88,
                "daysInTransit":1
            }
        ]
    },
    "cartItems":[
        {
            "myCartItemReference":"some reference",
            "cartItemID":"1bcc76b0-c437-46de-9c3f-93ec919f8234",
            "toolID":"2054608d-b469-4cab-adeb-cf1c0569e7a1",
            "modelID":"6a24345b-42ff-4d6c-8c0b-4037c4205b88",
            "modelFileName":"Box.stl",
            "materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
            "finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
            "quantity":1,
            "xDimMm":10.00000000000000000000,
            "yDimMm":10.00000000000000000000,
            "zDimMm":10.00000000000000000000,
            "volumeCm3":1.0000000000,
            "surfaceCm2":6.0000000000,
            "mySalesPrice":32.45,
            "iMatPrice":18.72,
            "mySalesUnitPrice":32.45
        },
        {
            "myCartItemReference":"some reference",
            "cartItemID":"059a45de-6185-4cf9-b694-8b6f3c57c4f2",
            "toolID":"2054608d-b469-4cab-adeb-cf1c0569e7a1",
            "modelID":"6a24345b-42ff-4d6c-8c0b-4037c4205b88",
            "modelFileName":"Box.stl",
            "materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
            "finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
            "quantity":1,
            "xDimMm":10.00000000000000000000,
            "yDimMm":10.00000000000000000000,
            "zDimMm":10.00000000000000000000,
            "volumeCm3":1.0000000000,
            "surfaceCm2":6.0000000000,
            "mySalesPrice":32.45,
            "iMatPrice":18.72,
            "mySalesUnitPrice":32.45
        }
    ],
    "shippingInfo":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"demo@demo.com",
        "phone":"1234567",
        "company":"No company",
        "line1":"North Street",
        "line2":"",
        "countryCode":"US",
        "stateCode":"NY",
        "zipCode":"10001",
        "city":"New York"
    },
    "billingInfo":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"demo@demo.com",
        "phone":"1234567",
        "company":"No company",
        "vatNumber":"BE0999999922",
        "line1":"North Street",
        "line2":"",
        "countryCode":"BE",
        "stateCode":"",
        "zipCode":"1020",
        "city":"Brussels"
    }
}

Example of Response with error in JSON

{
    "cartID":"109b9f82-d425-4ebb-8b11-4c85611508eb",
    "cartReference":"My cart",
    "currency":"USD",
    "iMatCartPageUrl":"https://i.materialise.com/en/cart/quotation/109b9f82-d425-4ebb-8b11-4c85611508eb",
    "iMatShipmentPageUrl":"https://i.materialise.com/en/ordering/quotation/109b9f82-d425-4ebb-8b11-4c85611508eb",
    "iMatEmbededCartPageUrl":"https://i.materialise.com/embeded/general/en/cart/quotation/109b9f82-d425-4ebb-8b11-4c85611508eb",
    "iMatEmbededShipmentPageUrl":"https://i.materialise.com/embeded/general/en/ordering/quotation/109b9f82-d425-4ebb-8b11-4c85611508eb",
    "discount":0.0000,
    "subTotalPrice":32.56,
    "vatTaxPercentage":0.00,
    "validUntil":"2014-11-29T00:00:00+02:00",
    "expectedShipmentDate":"2014-11-28T00:00:00+02:00",
    "shipmentDateComment":"If ordered today,
     90% certainty that it is shipped before or at this date.",
    "requestNumber":"REQ220207",
    "cartItems":[
        {
            "myCartItemReference":"some reference",
            "cartItemID":"01ebe0b0-caf4-4f1e-9ad5-abd28f141944",
            "toolID":"2054608d-b469-4cab-adeb-cf1c0569e7a1",
            "modelID":"489eb85e-4c64-457c-a1fe-83187b8e52d8",
            "modelFileName":"Box.stl",
            "materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
            "finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
            "quantity":2,
            "xDimMm":10.00000000000000000000,
            "yDimMm":10.00000000000000000000,
            "zDimMm":10.00000000000000000000,
            "volumeCm3":1.0000000000,
            "surfaceCm2":6.0000000000,
            "mySalesPrice":32.56,
            "iMatPrice":26.30,
            "mySalesUnitPrice":16.28
        }
    ],
    "shippingInfo":{
        "shippingInfoError":{
            "message":"ZipCode cannot be empty or longer than 9 symbols.",
            "code":715
        },
        "firstName":"John",
        "lastName":"Smith",
        "email":"test@test.com",
        "phone":"1234567",
        "company":"No company",
        "line1":"North Street",
        "line2":"",
        "countryCode":"US",
        "stateCode":"NY",
        "zipCode":"",
        "city":"New York"
    },
    "billingInfo":{
        "billingInfoError":{
            "message":"Wrong Email format.",
            "code":804
        },
        "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 with error in XML

<CartRegistrationResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <CartID>00000000-0000-0000-0000-000000000000</CartID>
  <Discount>0</Discount>
  <SubTotalPrice>0</SubTotalPrice>
  <VatTaxPercentage>0</VatTaxPercentage>
  <ValidUntil>0001-01-01T00:00:00</ValidUntil>
  <ExpectedShipmentDate xsi:nil="true" />
  <RequestError>
    <Message>Cart reference cannot be empty or more than 100 symbols.</Message>
    <Code>508</Code>
  </RequestError>
  <CartItems />
  <ShippingInfo />
  <BillingInfo />
</CartRegistrationResponse>