Site Tools

This is an old revision of the document!


Pricing by Parameters API

What are the Pricing APIs?

The Pricing APIs let you request prices and shipping cost calculation for 3D printing models without uploading them to our website. There are two APIs related to Pricing available on our site:

  • Pricing by Parameters*. Using this API, you can receive prices for the various material and finish combinations based on the dimensions, volume and surface of the model. This API is described on current page
  • Pricing by Model ID. You can get price of previously uploaded models by using this API. All you need to know is ID of the model you want to calculate the price for.

*Note that by using this API it is impossible to calculate prices for some materials: paintable resin, transparent resign, high delail resin and ABS.

Who Should Use this API?

The Pricing API is designed for users who have an application or website that generates models that need to be 3D printed and who wants an instant price before ordering models. If you would like prices to be calculated for your 3D models without transferring your information to i.materialise for performance, security or other reasons, this is the API for you.

Try it Out

We have created demo pages for you so you can test the tool ID and your acquired API code.

The demo page of Pricing by Parameters API on production server:

https://i.materialise.com/api/demo/pricing-by-parameters-api.htm

These fully functioning pages are linked to the pricing engine that is used in our 3D print lab, meaning that the API generated prices are identical to the prices generated by i.materialise’s 3D print lab.

Also, 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 sandbox API code, tool ID and integration with us. This is different from our demo pages which are used to check if a particular API is working and is connected with our production site.

The demo page of Pricing by Parameters API on sandbox server:

https://imatsandbox.materialise.net/api/demo/pricing-by-parameters-api.htm

How Does it Work?

This API requires the personal API code. It is therefore not possible to use AJAX requests. The Pricing API works by posting data to our service. You can use either XML (Extensible Markup Language) or JSON (JavaScript Object Notation) 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 “Documentation” 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 supported 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 prices through the Pricing API, POST a well-structured request via “HTTPS” to this URL:

https://i.materialise.com/web-api/pricing

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

https://imatsandbox.materialise.net/web-api/pricing

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

Documentation

Structure of the Request

The request, in XML or JSON format, needs to follow a certain structure to be able to generate prices. The structure consists of the following sections:

Request Header

The header of your request needs to contain:

Accept:        [preferred Content Type: "application/json" or "text/xml"]
API code:      [API code provided by i.materialise]

Models Section of the Request

Within the same request, it’s possible to request prices for multiple quantities and multiple material and finish options.

Parameter Type Required? Explanation
toolId String (36), required format: GUID No The toolID you received from us. If it’s omitted, the standard 3D print lab pricing algorithms will be used (your specific price factor will not be applied).
modelReference String (100) Yes Free input field which will be repeated in the response (e.g. this can be the model name)
materialId String (36), required format: GUID Yes The materialId is retrieved from the Materials Catalog API. Read more about the Materials Catalog API.
finishId String (36), required format: GUID Yes The finishId is retrieved from the Materials Catalog API. Read more about the Materials Catalog API.
quantity Integer Yes Amount of pieces for this model.
xDimMm Decimal, separated by a period Yes X dimension of the model, mm.
yDimMm Decimal, separated by a period Yes Y dimension of the model, mm.
zDimMm Decimal, separated by a period Yes Z dimension of the model, mm.
volumeCm3 Decimal, separated by a period Yes Volume of the model, cm3.
surfaceCm2 Decimal, separated by a period Yes Total surface of the model, cm2.

Shipment Information Section of the Request

The section is not required. If you would like the shipping cost calculated into the quote, simply add this to the request.

Parameter Type Required? Explanation
countryCode String (2) Yes Code of the country.
stateCode String Yes Code of the state.

For Japan ISO state codes should be used. For instance, “stateCode”: “09” for Totigi. For US according to ISO it should look like “stateCode”: “MI” fot state Michigan.

city String Yes City name.
zipCode String Yes Zip code or postal code.

Currency Section of the Request

The header of your request needs to contain:

Parameter Type Required? Explanation
currency String (3) No (EUR is default)

Following currencies are supported: EUR/USD/JPY/GBP.

Request Examples

Example of Request Using XML

<PricingRequest>
  <Models>
    <Model>
      <ToolID />
      <ModelReference>some model.xml</ModelReference>
      <MaterialID>035f4772-da8a-400b-8be4-2dd344b28ddb</MaterialID>
      <FinishID>bba2bebb-8895-4049-aeb0-ab651cee2597</FinishID>
      <Quantity>2</Quantity>
      <XDimMm>10</XDimMm>
      <YDimMm>10</YDimMm>
      <ZDimMm>10</ZDimMm>
      <VolumeCm3>1</VolumeCm3>
      <SurfaceCm2>6</SurfaceCm2>
    </Model>
  </Models>
  <ShipmentInfo>
      <CountryCode>US</CountryCode>
      <StateCode>AL</StateCode>
      <City>Alabama</City>
      <ZipCode>36006</ZipCode>
  </ShipmentInfo>
  <Currency>USD</Currency>
</PricingRequest>

Example of Request Using JSON

{ 
   "models":[
      {
         "toolID":"",
         "modelReference":"some model.xml",
         "materialID":"035f4772-da8a-400b-8be4-2dd344b28ddb",
         "finishID":"bba2bebb-8895-4049-aeb0-ab651cee2597",
         "quantity":"1",
         "xDimMm":"10",
         "yDimMm":"10",
         "zDimMm":"10",
         "volumeCm3":"1",
         "surfaceCm2":"6"
      }
   ],
   "shipmentInfo": 
    {
        "countryCode": "B",
        "stateCode": "",
        "city": "Leuven",
        "zipCode":  "3001"
    },
    "currency":"EUR"
}

Structure of the Response

Models Section of the Response

This section contains a list of models with the following parameters:

Parameter Type Always shown? Explanation
toolId String (36), required format: GUID No The toolID you received from us. If it’s omitted, the standard 3D print lab pricing algorithms will be used (your specific price factor will not be applied).
modelReference String (100) Yes Free input field which will be repeated in the response (e.g. this can be the model name)
materialId String (36), required format: GUID Yes The materialId is retrieved from the Materials Catalog API. Read more about the Materials Catalog API.
finishId String (36), required format: GUID Yes The finishId is retrieved from the Materials Catalog API. Read more about the Materials Catalog API.
quantity Integer Yes Amount of pieces for this model.
xDimMm Decimal, separated by a period Yes X dimension of the model, mm.
yDimMm Decimal, separated by a period Yes Y dimension of the model, mm.
zDimMm Decimal, separated by a period Yes Z dimension of the model, mm.
volumeCm3 Decimal, separated by a period Yes Volume of the model, cm3.
surfaceCm2 Decimal, separated by a period Yes Total surface of the model, cm2.

Disclaimer Section of the Response

Parameter Type Always shown? Explanation
disclaimer String (250) Yes Informational section

Shipment Information Section of Response

You’ll only see a shipping cost response if your request contains a shipment Information section.
Whenever there is a model for which the price could not be calculated, then the Shipment Information Section will show a shipping error.

Parameter Type Always shown? Explanation
services List of parameters Yes List of shipment services
services>service List of parameters No The response contains the services price, which is the basis of the shipping costs. Section is not shown if shipping address was not specified in the response.
services>service>name String (100) Yes (if parent node Service is added) Name of the service
services>service>value Decimal, separated by a period Yes (if parent node Service is added) The shipment cost for current service. The shipment cost is calculated for all models indicated in the request.
services>service>daysInTransit Integer No Number of days it would take to deliver all models with current service. If number of days is not returned by UPS, this field is empty.
shipmentError String (225) No This parameter is inserted into the response if it’s impossible to calculate the shipment cost. Possible shipment errors are described below.

Currency Section of the Response

Parameter Type Always shown? Explanation
currency String (3) No (EUR is default)

Following currencies are supported: EUR/USD/JPY/GBP.

All prices in the response (model prices and shipment cost) are calculated and returned in currency indicated in this section.

RequestError Section of Response

This response section appears only if request was NOT processed successfully.

Parameter Type Always shown? Explanation
requestError String (250) No This parameter is added to the response only if the request was NOT processed successfully. Possible errors are described below.

Response Examples

Example of Response in XML

<PriceResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<Models>
		<Model>
			<ToolID />
			<MaterialID>035f4772-1234-400b-8be4-2dd344b28ddb</MaterialID>
			<MaterialName>Polyamide</MaterialName>
			<FinishID>bba2bebb-1234-4049-aeb0-ab651cee2597</FinishID>
			<FinishingName>Natural white</FinishingName>
			<Quantity>1</Quantity>
			<TotalPrice>15.73</TotalPrice>
			<XDimMm>10</XDimMm>
			<YDimMm>10</YDimMm>
			<ZDimMm>10</ZDimMm>
			<VolumeCm3>1</VolumeCm3>
			<SurfaceCm2>6</SurfaceCm2>
			<ModelReference>some model.xml</ModelReference>
		</Model>
	</Models>
	<Disclaimer>The prices provided by the API represent a non-binding quotation for the i.materialise services and not an offer for sale. For a binding quotation, please upload the file with the desired model to our server.</Disclaimer>
	<ShipmentCost>
		<Services>
			<Service>
				<Name>Ground</Name>
				<Value>15.27</Value>
				<DaysInTransit>3</DaysInTransit>
			</Service>
			<Service>
				<Name>SecondDayAir</Name>
				<Value>20.61</Value>
				<DaysInTransit>2</DaysInTransit>
			</Service>
		</Services>
	</ShipmentCost>
	<Currency>USD</Currency>
</PriceResponse>

Example of Response in JSON

{
{
	"models":[
		{
			"modelReference":"some model.xml",
			"toolID":"20ef6277-52f5-1234-a306-1282ab8bc035",
			"materialID":"035f4772-1234-400b-8be4-2dd344b28ddb",
			"materialName":"Polyamide",
			"finishID":"bba2bebb-1234-4049-aeb0-ab651cee2597",
			"finishingName":"Natural white",
			"quantity":1,
			"totalPrice":12.50,
			"xDimMm":10.0,
			"yDimMm":10.0,
			"zDimMm":10.0,
			"volumeCm3":1.0,
			"surfaceCm2":6.0
		}
	],
	"disclaimer":"The prices provided by the API represent a non-binding quotation for the i.materialise services and not an offer for sale. For a binding quotation, please upload the file with the desired model to our server.",
	"shipmentCost":{
		"services":[
			{
				"name":"Standard",
				"value":6.68,
				"daysInTransit":1
			},
			{
				"name":"Express",
				"value":9.00,
				"daysInTransit":1
			}
		]
	},
	"currency":"EUR"
}

Errors

Below described all possible errors which can appear in both Pricing APIs (Pricing by Parameters and Pricing by Model ID).

Wrong API Code

If a wrong/empty API code is used, then you’ll see a 401 error response: statusText=”Unauthorized”.

Messaging for RequestError Response

The RequestError response shows up only if the request was NOT processed successfully.

Code Error Message
206 Wrong currency

Following currencies are supported: EUR/USD/JPY/GBP.

101 The structure of the request is wrong (some needed parameters are not found or filled in incorrectly) Wrong request body. Check if all parameters are set correctly.
- Something else (exception for example) Unknown Error. Try again later. If the problem persists, please contact developers[at].materialise.com.

Example of Response in XML

<PriceResponse>
  <RequestError>This currency is not supported, please specify EUR/USD/JPY/GBP</RequestError>
  <Error>
    <Message>This currency is not supported, please specify EUR/USD/JPY/GBP</Message>
    <Code>206</Code>
  </Error>
</PriceResponse>

Example of Response in JSON

{
    "requestError":"This currency is not supported,
     please specify EUR/USD/JPY/GBP",
    "error":{
        "message":"This currency is not supported,
         please specify EUR/USD/JPY/GBP",
        "code":206
    }
}

Messaging for models>pricingError Response

The models>pricingError message appears if the price for a model cannot be calculated. Each model can have its own pricing error. Pricing errors appear when some parameters are filled in incorrectly, or when it’s impossible to calculate online prices according to i.materialise rules.

Code Error Message
201 toolId is wrong/belongs to someone else Wrong toolID has been applied. To verify toolID, please contact developers@i.materialise.com.
202 modelReference is empty or contains more than 100 symbols modelReference cannot be empty or more than 100 symbols.
203 materialID is empty or wrong An unknown material ID for has been requested, please check the IDs in the Materials Catalog API.
204 finishID is empty or wrong An unknown ID for the color/finish has been requested, please check the IDs in the Materials Catalog API.
205 quantity is not a positive integer Quantity is wrong, please use only positive integer.
207 xDimMm is not a positive decimal XDimMm is wrong, please use only positive decimals.
208 yDimMm is not a positive decimal YDimMm is wrong, please use only positive decimals.
209 zDimM is not a positive decimal ZDimMm is wrong, please use only positive decimals.
210 volumeCm3 is not a positive decimal VolumeCm3 is wrong, please use only positive decimals.
211 surfaceCm2 is not a positive decimal SurfaceCm2 is wrong, please use only positive decimals.
212 scaleFactor is not positive float Wrong scaleFactor. Please make sure you set this parameter correctly.
213 modelID is wrong/empty or model was uploaded by another user/partner. Wrong modelID. Please make sure you set this parameter.
214 Model is deleted from database. Your model has been deleted from database. Please upload model to get a price.
215toolId was deactivated Specified toolID is no more active.
Code Error Message
220 No online price for this material through the API We don’t offer an online price for this material/finish through the API.
221 Dimensions are too large for the priority service The dimensions of the model are outside the allowed range to offer it as a priority model. The allowed range is <X1xY1xZ1> – <X2xY2xZ2> mm.
222 Dimensions are too large, too small for a specific finish (e.g. velvet) The dimensions of the model are outside the allowed range for <materialName> <finishName> model. The allowed range is <X1xY1xZ1> – <X2xY2xZ2> mm.
223 Dimensions too large or too small The dimensions of the model are outside the allowed range for <materialName>. The allowed range is <X1xY1xZ1> – <X2xY2xZ2> mm.
224 Price is too high The price for this model is too high, so we are unable to offer an online price. Please request an offline price through our website.
225 If the requested material is “Ceramics” and X+Y+Z is larger than 400 mm The dimensions of the model are outside the allowed range for ceramics. The sum of the X,Y and Z dimensions should be below 400 mm.
226 If the requested material is “Ceramics” and X+Y+Z is below 120 mm The dimensions of the model are outside the allowed range for ceramics. The sum of the X,Y and Z dimensions should be greater than 120 mm.
227 Dimensions for Ceramics are too large or too small The dimensions of the model are outside the allowed range for ceramics. The model should fit the range of <X1xY1xZ1>.
228 If requested material is “Ceramics” and wall thickness is too small The dimensions of the model are outside the allowed range for ceramics. Please make sure the wall thickness of your model is at least <thickness> mm.
229 If parameter IfSuccessfulyProcessed is “false” (model fixing is still needed after autofixing) Unfortunately price cannot be calculated for this model through the API. Model needs to be fixed first.
230 If price is requested for the Materials where support parameters are required to calculate the correct price. If price is requested for the SLS Materials when the ShrinkWrap Pricing was enabled for the toolID. Not possible to calculate the price for this Material using this API. Use the Pricing by ModelID
231 Dimensions of the model are too small for Mammoth Resin. The allowed range is <X1xY1xZ1> – <X2xY2xZ2> mm. You can try another resin.
0 Something else Unknown Error. Try again later. If the error keeps occurring, please contact developers[at]i.materialise.com.

Example of PricingError in XML

<Models>
    <Model>
      <ToolID />
      <MaterialID>d7ed51be-aaa1-40ea-8ca7-8763c65fc66e</MaterialID>
      <FinishID>496ce425-aaa1-4320-b78a-2dfa7c41657b</FinishID>
      <Quantity>1</Quantity>
      <TotalPrice>0</TotalPrice>
      <XDimMm>10</XDimMm>
      <YDimMm>10</YDimMm>
      <ZDimMm>10</ZDimMm>
      <VolumeCm3>1</VolumeCm3>
      <SurfaceCm2>6</SurfaceCm2>
      <PricingError>
        <Message>We don’t offer an online price for this material</Message>
        <Code>220</Code>
      </PricingError>
      <ModelReference>some model.xml</ModelReference>
    </Model>
  </Models>

Example of pricingError in JSON

"models":[
    {
        "modelReference":"some model.xml",
        "toolID":"20ef6277-52f5-4551-a306-1282ab8bc035",
        "materialID":"d7ed51be-aaa1-40ea-8ca7-8763c65fc66e",
        "finishID":"496ce425-aaa1-4320-b78a-2dfa7c41657b",
        "quantity":1,
        "totalPrice":0.0,
        "xDimMm":10.0,
        "yDimMm":10.0,
        "zDimMm":10.0,
        "volumeCm3":1.0,
        "surfaceCm2":6.0,
        "pricingError":{
        "message":"We don’t offer an online price for this material",
        "code":220
        }
     }
],

Messaging for ShipmentCost > ShipmentError parameter

Error Message
The price is not calculated for at least one model from the list of requested models We cannot calculate the shipment cost because the price for some models you requested cannot be calculated.
The country code is not indicated or left blank countryCode is required. Please use an international country code (e.g. BE for Belgium).
The country code is not found in our database Wrong countryCode. Please use an international country code (e.g. BE for Belgium).
The state code is required for the indicated country stateCode is required for the requested country. Please use an American/Canadian state code (e.g. MI for Michigan).
The state code is not found in our database for the requested country Wrong stateCode is is required for the requested country. Please use an American/Canadian state code (e.g.: MI for Michigan).
City is not indicated or left blank City is required
Zip code is not indicated or left blank Zip code is required
Shipment can't be done to the specified country Shipping service is not provided for this country. Please specify different shipping country.
UPS returns an error message. It can occur when there’s a wrong combination of zip code, city and country, or when the model’s weight is over the UPS limit, or some other UPS errors. UPS error message
Something else (exception for example) Unknown error. Please try again later.

Example of ShipmentError in XML

<ShipmentCost>
  <ShipmentError>ZipCode is required.</ShipmentError>
</ShipmentCost>

Example of ShipmentError in JSON

"shipmentCost":{
    "shipmentError":"Wrong CountryCode. Please use international country code (e.g.: BE for Belgium)."
},