Cart Item Creation API

The Cart Item Creation API allows you to create cart items. 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 be used without the other one.

The Cart Item 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 Item 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 upload a 3D model and create cart item? 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 Item Creation API on sandbox server:

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

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

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

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

https://i.materialise.com/web-api/cartitems/register

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

https://imatsandbox.materialise.net/web-api/cartitems/register

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

All requests to the Cart Item 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.

Cart items can be created one by one but it’s also possible to create several items at once. A cart item section consists of following data:

• Production data: This data is obligatory. Your request need to specify the desired material, finishing, model file measure units, quantity and scale factor to be applied to the model in the file.

• Model dimensional information: This information is optional. Providing the dimensional information in the request will allow our service to verify them and warn you about any inconsistencies between the provided and i.materialise’s calculated model parameters. Since the information is used in the sales price calculation, it might be useful to be warned when the dimensional information sets differ too much. This info doesn’t need to be exact. Till further notice, the request needs to have at least the model information fields with dummy values like “1”.

• Pricing: The pricing data foresees to specify an estimated price and the price your customer should see. The estimated price can be retrieved from one of Pricing API's. Whenever the customer should see the regular sales price, the field mySalesPrice needs to be set to zero.

• Auxiliary info: Additionally, a cart item reference field is foreseen to tag your own reference to this cart item. An example of a cart item section request can be found on the demo page for the Cart Item Creation API: https://i.materialise.com/api/demo/cart-item-creation-api.htm

Content-Type : multipart/form-data 

{
   "cartItems":[
      {
         "toolID":"2054608d-b469-4cab-adeb-cf1c0569e7a1",
         "MyCartItemReference":"some reference",
         "modelID":"",
         "modelFileName":"Box.stl",
         "fileUnits":"mm",
         "fileScaleFactor":"1",
         "materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
         "finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
         "quantity":"1",
         "xDimMm":"1",
         "yDimMm":"1",
         "zDimMm":"1",
         "volumeCm3":"1",
         "surfaceCm2":"1",
         "iMatAPIPrice": "0",
         "mySalesPrice": "0",
      }
   ],
   "currency":"EUR"
}

 
<CartItemsRegistrationRequest>
  <CartItems>
      <CartItem>
          <ToolID>2054608d-b469-4cab-adeb-cf1c0569e7a1</ToolID>
          <MyCartItemReference>some reference</MyCartItemReference>
          <ModelID>06515f8e-5d08-4fcb-912a-b87380d69927</ModelID>
          <ModelFileName></ModelFileName>
          <FileUnits>mm</FileUnits>
          <FileScaleFactor>1</FileScaleFactor>
          <MaterialID>035f4772-da8a-400b-8be4-2dd344b28ddb</MaterialID>
          <FinishID>bba2bebb-8895-4049-aeb0-ab651cee2597</FinishID>
          <Quantity>1</Quantity>
          <XDimMm>10</XDimMm>
          <YDimMm>10</YDimMm>
          <ZDimMm>10</ZDimMm>
          <VolumeCm3>1</VolumeCm3>
          <SurfaceCm2>6</SurfaceCm2>
          <IMatAPIPrice>0</IMatAPIPrice>
          <MySalesPrice>0</MySalesPrice>
      </CartItem>
  </CartItems>
  <Currency>EUR</Currency>
</CartItemsRegistrationRequest>

The <CartItem> block can be repeated more than once in the request. At this moment, 5 models per request are allowed.

The rule of thumb is when you get a cartItemID in response you are free to use it when you’re registering the cart.

Example of Response in XML

<CartItemRegistrationResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Currency>EUR</Currency>
  <CartItems>
    <CartItemResponseDto>
      <MyCartItemReference>some reference</MyCartItemReference>
      <CartItemID>333095fc-6ab2-4c30-b0d1-baecfd708f69</CartItemID>
      <ToolID>2054608d-b469-4cab-adeb-cf1c0569e7a1</ToolID>
      <ModelID>06515f8e-5d08-4fcb-912a-b87380d69927</ModelID>
      <ModelFileName>Box.stl</ModelFileName>
      <FileUnits>Mm</FileUnits>
      <FileScaleFactor>1</FileScaleFactor>
      <MaterialID>035f4772-da8a-400b-8be4-2dd344b28ddb</MaterialID>
      <FinishID>bba2bebb-8895-4049-aeb0-ab651cee2597</FinishID>
      <Quantity>1</Quantity>
      <XDimMm>10.0000000000</XDimMm>
      <YDimMm>10.0000000000</YDimMm>
      <ZDimMm>10.0000000000</ZDimMm>
      <VolumeCm3>1.0000000000</VolumeCm3>
      <SurfaceCm2>6.0000000000</SurfaceCm2>
      <IMatAPIPrice>15.00</IMatAPIPrice>
      <MySalesPrice>15.00</MySalesPrice>
      <MySalesUnitPrice>15.00</MySalesUnitPrice>
      <IMatPrice>15.00</IMatPrice>
      <ValidUntil>2014-11-26T00:00:00+02:00</ValidUntil>
    </CartItemResponseDto>
  </CartItems>
  <UploadTimeMs xsi:nil="true" />
  <ProcessingTimeMs xsi:nil="true" />
  <ResponseSentUnixTimestampUtcMs xsi:nil="true" />
</CartItemRegistrationResponse>

Example of Response in JSON

{
    "currency":"EUR",
    "cartItems":[
        {
            "myCartItemReference":"some reference",
            "cartItemID":"ef7ee059-55cf-43b2-9413-3dd8e6dff49e",
            "toolID":"2054608d-b469-4cab-adeb-cf1c0569e7a1",
            "modelID":"eaba63a6-f9a0-4103-9d84-3c6e07ba282a",
            "modelFileName":"Box.stl",
            "fileUnits":"mm",
            "fileScaleFactor":1.0,
            "materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
            "finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
            "quantity":10,
            "xDimMm":10.0000000000,
            "yDimMm":10.0000000000,
            "zDimMm":10.0000000000,
            "volumeCm3":1.0000000000,
            "surfaceCm2":6.0000000000,
            "iMatAPIPrice":69.00,
            "mySalesPrice":69.00,
            "mySalesUnitPrice":6.90,
            "iMatPrice":69.00,
            "validUntil":"2014-11-26T00:00:00+02:00"
        }
    ]
}

Example of Response with error in JSON

{
    "currency":"EUR",
    "error":{
        "message":"At least one of item in the request contains an error.",
        "code":404
    },
    "cartItems":[
        {
            "myCartItemReference":"some reference",
            "cartItemError":{
                "message":"We cannot process this model. Check if model is correct.",
                "code":303
            },
            "toolID":"2054608d-b469-4cab-adeb-cf1c0569e7a1",
            "modelID":"3e64b3ed-e591-49d1-bac4-266571c7b2a7",
            "modelFileName":"2print_bad.stl",
            "fileUnits":"mm",
            "fileScaleFactor":1.0,
            "uploadStatus":"StillNeedsFixing",
            "materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
            "finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
            "quantity":1,
            "xDimMm":73.7159000000,
            "yDimMm":118.8810000000,
            "zDimMm":27.3087000000,
            "volumeCm3":85.2411000000,
            "surfaceCm2":354.9360000000,
            "iMatAPIPrice":0.0,
            "mySalesPrice":0.0,
            "mySalesUnitPrice":0.0
        }
    ]
}

Example of Response with error in XML

<CartItemRegistrationResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Currency>EUR</Currency>
  <Error>
    <Message>At least one of item in the request contains an error.</Message>
    <Code>404</Code>
  </Error>
  <CartItems>
    <CartItemResponseDto>
      <MyCartItemReference>some reference</MyCartItemReference>
      <CartItemError>
        <Message>SalesPrice cannot be less than IMatPrice.</Message>
        <Code>209</Code>
      </CartItemError>
      <CartItemID xsi:nil="true" />
      <ToolID>2054608d-b469-4cab-adeb-cf1c0569e7a1</ToolID>
      <ModelID xsi:nil="true" />
      <FileUnits>Mm</FileUnits>
      <FileScaleFactor>1</FileScaleFactor>
      <MaterialID>035f4772-da8a-400b-8be4-2dd344b28ddb</MaterialID>
      <FinishID>bba2bebb-8895-4049-aeb0-ab651cee2597</FinishID>
      <Quantity>1</Quantity>
      <XDimMm xsi:nil="true" />
      <YDimMm xsi:nil="true" />
      <ZDimMm xsi:nil="true" />
      <VolumeCm3 xsi:nil="true" />
      <SurfaceCm2 xsi:nil="true" />
      <IMatAPIPrice>15</IMatAPIPrice>
      <MySalesPrice>14</MySalesPrice>
      <MySalesUnitPrice>14</MySalesUnitPrice>
      <IMatPrice xsi:nil="true" />
      <ValidUntil xsi:nil="true" />
    </CartItemResponseDto>
  </CartItems>
  <UploadTimeMs xsi:nil="true" />
  <ProcessingTimeMs xsi:nil="true" />
  <ResponseSentUnixTimestampUtcMs xsi:nil="true" />
</CartItemRegistrationResponse>