home
Materials
Use the /materials/v1 API endpoint to get up-to-date information about Shapeways’ materials.
GET - List materials
Retrieves information on all available 40+ Shapeways’ materials.
Request
GET /materials/v1
Response
parameters
type
description
result
string
A 'result' field stating 'success'
materials
object
Material objects
{
"<materialId>":{
"id":"<materialId>",
"type":"object",
"description":"Material Object",
"properties":{
"title":{
"type":"string",
"description":"Material name"
},
"supportsColorFiles":{
"type":"boolean",
"description":"Material supports color"
},
"printerId":{
"type":"int",
"description":"Printer id that this material is printed on"
},
"swatch":{
"type":"string",
"description":"The url for the material swatch"
},
"restrictions":{
"id":"restrictions",
"type":"object",
"description":"Material Restriction Object",
"properties":{
"<restrictionId>":{
"id":"<restrictionId>",
"type":"object",
"description":"Material Restriction Object",
"properties":{
"restrictionId":{
"type":"int",
"description":"Material Restriction ID"
},
"restrictionName":{
"type":"string",
"description":"Material Restriction Name"
},
"restrictionEntityIds":{
"type":"array",
"description":"Material Restriction Entity Ids",
"default":[
],
"items":{
"type":"int",
"description":"Material Restriction Entity Id"
}
}
}
}
}
}
}
}
}
nextActionSuggestions
object
Suggestions for next actions
GET - Material information
Retrieves information for a specific material (Specified by the materialId)
Request
GET /materials/{materialId}/v1
parameters
type
required
description
materialId
int
required
Material id
Response
parameters
type
description
result
string
A 'result' field stating 'success'
materialId
int
Material ID
title
string
Material name
supportsColorFiles
boolean
Material supports color
printerId
int
Printer id that this material is printed on
swatch
string
The url for the material swatch
restrictions
object
Material Restriction Object
{
"<restrictionId>":{
"id":"<restrictionId>",
"type":"object",
"description":"Material Restriction Object",
"properties":{
"restrictionId":{
"type":"int",
"description":"Material Restriction ID"
},
"restrictionName":{
"type":"string",
"description":"Material Restriction Name"
},
"restrictionEntityIds":{
"type":"array",
"description":"Material Restriction Entity Ids",
"default":[
],
"items":{
"type":"int",
"description":"Material Restriction Entity Id"
}
}
}
}
}
nextActionSuggestions
object
Suggestions for next actions
Models
Easily manage your Shapeways’ 3D models with the /models/v1 API endpoint.
POST - Upload a model
Uploads a new model. See Upload a model for instructions and code examples.
Request
POST /models/v1
parameters
type
required
description
file
string
required
Model file data
fileName
string
required
Model filename (with correct file extension)
uploadScale
float
optional
Model scale in meters
- 1.0 (default) - meter
- 0.001 - millimeter
- 0.0254 - inch
- 0.001 - millimeter
- 0.0254 - inch
hasRightsToModel
boolean
required
You have the rights to model
You have the rights or have authorization to use this model
- 0 - You do not have rights to, nor have authorization to use this model
- 1 - You have rights to, or have authorization to use this model
- 0 - You do not have rights to, nor have authorization to use this model
- 1 - You have rights to, or have authorization to use this model
acceptTermsAndConditions
boolean
required
You accept the Shapeways' Terms and Conditions
You accept the Terms and Conditions.
- 0 - You do not accept the Terms and Conditions
- 1 - You accept the Terms and Conditions
- 0 - You do not accept the Terms and Conditions
- 1 - You accept the Terms and Conditions
title
string
optional
Model title
description
string
optional
Model description
isPublic
boolean
optional
Model visibility
- 1 - Public Model
- 0 (default) - Private Model (viewable only with a private key)
- 0 (default) - Private Model (viewable only with a private key)
isClaimable
boolean
optional
Whether a model is claimable with a claim key - Default: false
isForSale
int
optional
Model is for sale
- 0 (default) - Model cannot be purchased
- 1 - Model can be purchased
- 1 - Model can be purchased
isDownloadable
boolean
optional
Model is downloadable
- 0 (default) - Model cannot be downloaded
- 1 - Model can be downloaded
- 1 - Model can be downloaded
tags
array
optional
Model tags
{
"type":"string",
"description":"The name of the tag."
}
materials
object
optional
Material objects
{
"<materialId>":{
"id":"<materialId>",
"type":"object",
"description":"Material Object",
"properties":{
"markup":{
"type":"float",
"description":"Markup amount"
},
"isActive":{
"type":"boolean",
"description":"Is this material active"
},
"price":{
"type":"float",
"description":"Price (USD)"
}
}
}
}
defaultMaterialId
int
optional
The material id for this model's default material
categories
array
optional
Array of category ids.
{
"type":"int",
"description":"Category Id"
}
Response
parameters
type
description
result
string
A 'result' field stating 'success'
modelId
int
Model ID
modelVersion
int
Model version
title
string
Model title
fileName
string
Model filename
contentLength
int
The file size of the uploaded file in bytes
fileMd5Checksum
string
The md5 checksum of the file
description
string
Model description
isPublic
boolean
Can be seen by the public
isClaimable
boolean
Can be claimed via claimKey
isForSale
boolean
Model is for sale
isDownloadable
boolean
Model is downloadable
materials
object
Material objects
{
"<materialId>":{
"id":"<materialId>",
"type":"object",
"description":"Material Object",
"properties":{
"markup":{
"type":"float",
"description":"Markup amount"
},
"isActive":{
"type":"boolean",
"description":"Is this material active"
},
"price":{
"type":"float",
"description":"Price"
}
}
}
}
secretKey
string
Model secret key
The secret key is used to allow ANY user to access a private model. The model can be accessed using the url query parameter ?key=[key] at the end of the url
claimKey
string
Model claim key
The claim key is used to allow ANY user to claim a model into their own account. The claim function should be used when your app is generating models using your own permanent access tokens.To enable a user to claim a model, send them to shapeways.com/model/claim/[modelId] with a query parameter of ?key=[key].If the model is not "claimable" this key will be blank. Once a model is set to claimable, it cannot be set to public or for-sale.The page will redirect to the model edit view after it has been claimed.
defaultMaterialId
int
The material id for this model's default material
categories
object
Category Objects
{
"<categoryId>":{
"id":"<categoryId>",
"type":"object",
"description":"Category Object",
"properties":{
"title":{
"type":"string",
"description":"Category title"
},
"parentId":{
"type":"int",
"description":"Category's parent category. For topmost categories, 0 will be returned to indicate that there is no parent."
}
}
}
}
tags
string
Tags
urls
object
Url Objects
{
"<address>":{
"id":"<address>",
"type":"object",
"description":"Url Object",
"properties":{
"address":{
"type":"string",
"description":"Url Address"
}
}
}
}
spin
string
SPIN
printable
string
Model Printability
nextActionSuggestions
object
Suggestions for next actions
GET - List models
Retrieves a list of models in the Shapeways account.
Request
GET /models/v1
parameters
type
required
description
page
int
optional
The model page, starting with 1. Each page contains 36 models.
Response
parameters
type
description
result
string
A 'result' field stating 'success'
models
array
List of models
{
"modelId":{
"type":"int",
"description":"Model ID"
},
"modelVersion":{
"type":"int",
"description":"Model version"
},
"title":{
"type":"string",
"description":"Model title"
}
}
nextActionSuggestions
object
Suggestions for next actions
GET - Model information
Retrieves information for a specific model like material printability and price (Specified by the modelId). See Get model information for instructions and code examples.
Request
GET /models/{modelId}/v1
parameters
type
required
description
modelId
int
required
Model id
Response
parameters
type
description
result
string
A 'result' field stating 'success'
modelId
int
Model ID
modelVersion
int
Model version
title
string
Model title
fileName
string
Model filename
contentLength
int
The file size of the uploaded file in bytes
fileMd5Checksum
string
The md5 checksum of the file
fileData
string
Model file data
description
string
Model description
isPublic
boolean
Can be seen by the public
isClaimable
boolean
Can be claimed via claimKey
isForSale
boolean
Model is for sale
isDownloadable
boolean
Model is downloadable
materials
object
Material objects
{
"<materialId>":{
"id":"<materialId>",
"type":"object",
"description":"Material Object",
"properties":{
"markup":{
"type":"float",
"description":"Markup amount"
},
"isActive":{
"type":"boolean",
"description":"Is this material active"
},
"price":{
"type":"float",
"description":"Price"
}
}
}
}
secretKey
string
Model secret key
The secret key is used to allow ANY user to access a private model. The model can be accessed using the url query parameter ?key=[key] at the end of the url
claimKey
string
Model claim key
The claim key is used to allow ANY user to claim a model into their own account. The claim function should be used when your app is generating models using your own permanent access tokens.To enable a user to claim a model, send them to shapeways.com/model/claim/[modelId] with a query parameter of ?key=[key].If the model is not "claimable" this key will be blank. Once a model is set to claimable, it cannot be set to public or for-sale.The page will redirect to the model edit view after it has been claimed.
defaultMaterialId
int
The material id for this model's default material
categories
object
Category Objects
{
"<categoryId>":{
"id":"<categoryId>",
"type":"object",
"description":"Category Object",
"properties":{
"title":{
"type":"string",
"description":"Category title"
},
"parentId":{
"type":"int",
"description":"Category's parent category. For topmost categories, 0 will be returned to indicate that there is no parent."
}
}
}
}
tags
string
Tags
urls
object
Url Objects
{
"<address>":{
"id":"<address>",
"type":"object",
"description":"Url Object",
"properties":{
"address":{
"type":"string",
"description":"Url Address"
}
}
}
}
spin
string
SPIN
printable
string
Model Printability
printerId
int
Printer id that this material is printed on
swatch
string
The url for the material swatch
restrictions
object
Material Restriction Object
{
"<restrictionId>":{
"id":"<restrictionId>",
"type":"object",
"description":"Material Restriction Object",
"properties":{
"restrictionId":{
"type":"int",
"description":"Material Restriction ID"
},
"restrictionName":{
"type":"string",
"description":"Material Restriction Name"
},
"restrictionEntityIds":{
"type":"array",
"description":"Material Restriction Entity Ids",
"default":[
],
"items":{
"type":"int",
"description":"Material Restriction Entity Id"
}
}
}
}
}
nextActionSuggestions
object
Suggestions for next actions
DELETE - Delete a model
Deletes a model from the Shapeways’ account (Specified by the modelId).
Request
DELETE /models/{modelId}/v1
parameters
type
required
description
modelId
int
required
ID of the model to delete.
Response
parameters
type
description
result
string
A 'result' field stating 'success'
modelId
int
ID of the model that was deleted.
nextActionSuggestions
object
Suggestions for next actions
Orders
Use the /orders/v1 API endpoint to integrate with Shapeways fulfillment services to seamlessly place and manage orders.
POST - Place an order
Creates and places a new order. See Placing your first order instructions and code examples.
Request
POST /orders/v1
parameters
type
required
description
firstName
string
required
First name for shipping address
lastName
string
required
Last name for shipping address
state
string
required
Shipping address state or region.
In the US, must be the 2-letter abbreviation.
city
string
required
Shipping address city name
address1
string
required
Street Address
address2
string
optional
Apartment or Suite
address3
string
optional
Company or c/o
zipCode
string
required
Shipping address zip code.
In the US, zipCode must be less than 10 characters. In GB zipCode must be less than 7 chars
phoneNumber
string
required
Customer phone number. Must be 10 digits in the US and CA
items
array
required
Set of items in your order
{
"type":"object",
"description":"Item in your order",
"properties":{
"modelId":{
"type":"int",
"description":"Model id"
},
"materialId":{
"type":"int",
"description":"Material id"
},
"quantity":{
"type":"int",
"description":"Quantity of models in this material"
}
}
}
incentives
array
optional
Set of incentives to apply to the order
{
"type":"string",
"description":"Incentive code"
}
paymentVerificationId
string
optional
Shapeways-issued id to authorize payments for your app
paymentMethod
string
required
Payment method for this order
- credit_card - use the credit card you have on file with Shapeways to process this order
shippingOption
string
required
Shipping option for this order
- Cheapest - use the cheapest shipping option available
- Fastest - use the fastest shipping option available. If multiple options are the fastest, use the cheapest
- Fastest - use the fastest shipping option available. If multiple options are the fastest, use the cheapest
manufacturingSpeed
string
optional
Manufacturing speed for this order
- Economy - Save by not hurrying. Economy will take approximately 10 business days longer than Priority when manufactured capacity is available
- Priority - (Usually +30% more per item) Get in front of the line. Ensure your deliveries with our published manufacturing times
- Priority - (Usually +30% more per item) Get in front of the line. Ensure your deliveries with our published manufacturing times
refNumber
string
optional
Reference number associated with this order.
- 20 characters max.
- This string will be printed on the packing slip inside the box and on the downloadable PDF invoice.
- This string will be printed on the packing slip inside the box and on the downloadable PDF invoice.
metadata
array
optional
metadata
{
"type":"object",
"description":"Metadata can only be used by certain applications.",
"properties":{
"modelId":{
"type":"int",
"description":"Model id"
},
"name":{
"type":"string",
"description":"Metadata Name"
},
"value":{
"type":"string",
"description":"Metadata value"
}
}
}
Response
parameters
type
description
result
string
A 'result' field stating 'success'
orderId
int
Id of the order that was created
productionOrderIds
array
Set of production order ids
{
"type":"int",
"description":"Production Order Id"
}
nextActionSuggestions
object
Suggestions for next actions
GET - List orders
Retrieves information like number of orders, their statuses, and shipping dates.
Request
GET /orders/v1
parameters
type
required
description
orderIds
string
optional
comma separated list of order ids
Response
parameters
type
description
result
string
A 'result' field stating 'success'
ordersCount
object
Contains a summary of the number of orders classified by status
{
"total":{
"type":"int",
"description":"Total number of orders"
},
"placed":{
"type":"int",
"description":"Number of orders placed"
},
"in_production":{
"type":"int",
"description":"Number of orders in production"
},
"cancelled":{
"type":"int",
"description":"Number of orders cancelled"
},
"unknown":{
"type":"int",
"description":"Number of orders in an unknown status"
},
"shipped":{
"type":"int",
"description":"Number of orders shipped"
}
}
ordersStatus
json_object
Contains a detailed summary of each order and it's status
ordersInfo
array
Contains target ship date, target delivery date and shipments for each order
{
"id":"<orderId>",
"type":"object",
"description":"Contains target ship date, target delivery date and shipments for each order",
"properties":{
"orderId":{
"type":"int",
"description":"Order id"
},
"targetDeliveryDate":{
"type":"string",
"description":"Target delivery date"
},
"targetShipDate":{
"type":"string",
"description":"Target to ship date"
},
"shipments":{
"type":"array",
"description":"Shipments for this order",
"items":{
"id":"<shipmentId>",
"type":"object",
"description":"Shipment Information",
"properties":{
"shipmentId":{
"type":"int",
"description":"Shipment id"
},
"shipDate":{
"type":"string",
"description":"Ship date"
},
"carrier":{
"type":"string",
"description":"Shipment carrier"
},
"trackingNumber":{
"type":"string",
"description":"Tracking number"
}
}
}
},
"orderProducts":{
"type":"array",
"description":"Contains detailed information for the items contained within each purchased product.",
"items":{
"id":"<orderProductId>",
"type":"object",
"description":"Contains a detailed summary of each item and it's status",
"properties":{
"orderProductId":{
"type":"int",
"description":"Unique id for this product in this order"
},
"spin":{
"type":"string",
"description":"Shapeways Product Identification Number"
},
"productTitle":{
"type":"string",
"description":"Product title at the time of purchase"
},
"optionId":{
"type":"int",
"description":"Unique id for this product in its purchased option"
},
"optionDescription":{
"type":"int",
"description":"Name of this item in its ordered material and variant options"
},
"quantity":{
"type":"int",
"description":"Total quantity of this product purchased in this order"
},
"models":{
"type":"array",
"description":"Contains detailed information for each model in the purchased product",
"items":{
"type":"object",
"description":"3D printed models in your ordered product",
"properties":{
"modelId":{
"type":"int",
"description":"Model id"
},
"materialId":{
"type":"int",
"description":"Material id"
},
"title":{
"type":"int",
"description":"The title of the model at time of purchase"
}
}
}
}
}
}
}
}
}
nextActionSuggestions
object
Suggestions for next actions
GET - Order information
Retrieves information for a specific order placed through the API (Specified by the orderId). See Check the status of an order for instructions and code examples.
Request
GET /orders/{orderId}/v1
parameters
type
required
description
orderIds
string
optional
Filter by order ids provided for the api orders
orderId
string
optional
Filter by the order id provided for the api order
firstName
string
optional
Filter by first name on the address that was used to place the order
lastName
string
optional
Filter by lastName name on the address that was used to place the order
country
string
optional
Filter by country on the address that was used to place the order
state
string
optional
Filter by state or region on the address that was used to place the order
city
string
optional
Filter by city on the address that was used to place the order
address1
string
optional
Filter by address1 that was used to place the order
address2
string
optional
Filter by address street (line 1) that was used to place the order
address2
string
optional
Filter by address street (line 2) that was used to place the order
address3
string
optional
Filter by address street (line 3) that was used to place the order
zipCode
string
optional
Filter by zip code on the address that was used to place the order
phoneNumber
string
optional
Filter by phone number used to place the order
email
string
optional
Filter by email used to place the order
limit
int
optional
Limits the number of orders returned. Limit cannot exceed 100
- Default: 20
- Default: 20
Response
parameters
type
description
result
string
A 'result' field stating 'success'
ordersCount
object
Contains a summary of the number of orders classified by status
{
"total":{
"type":"int",
"description":"Total number of orders"
},
"placed":{
"type":"int",
"description":"Number of orders placed"
},
"in_production":{
"type":"int",
"description":"Number of orders in production"
},
"cancelled":{
"type":"int",
"description":"Number of orders cancelled"
},
"unknown":{
"type":"int",
"description":"Number of orders in an unknown status"
},
"shipped":{
"type":"int",
"description":"Number of orders shipped"
}
}
ordersStatus
json_object
Contains a detailed summary of each order and it's status
ordersInfo
array
Contains target ship date, target delivery date and shipments for each order
{
"id":"<orderId>",
"type":"object",
"description":"Contains target ship date, target delivery date and shipments for each order",
"properties":{
"orderId":{
"type":"int",
"description":"Order id"
},
"targetDeliveryDate":{
"type":"string",
"description":"Target delivery date"
},
"targetShipDate":{
"type":"string",
"description":"Target to ship date"
},
"shipments":{
"type":"array",
"description":"Shipments for this order",
"items":{
"id":"<shipmentId>",
"type":"object",
"description":"Shipment Information",
"properties":{
"shipmentId":{
"type":"int",
"description":"Shipment id"
},
"shipDate":{
"type":"string",
"description":"Ship date"
},
"carrier":{
"type":"string",
"description":"Shipment carrier"
},
"trackingNumber":{
"type":"string",
"description":"Tracking number"
},
"trackingLink":{
"type":"string",
"description":"Shipment carrier's tracking URL (returned only if trackingNumber is available)"
}
}
}
},
"orderProducts":{
"type":"array",
"description":"Contains detailed information for the items contained within each purchased product.",
"items":{
"id":"<orderProductId>",
"type":"object",
"description":"Contains a detailed summary of each item and it's status",
"properties":{
"orderProductId":{
"type":"int",
"description":"Unique id for this product in this order"
},
"spin":{
"type":"string",
"description":"Shapeways Product Identification Number"
},
"productTitle":{
"type":"string",
"description":"Product title at the time of purchase"
},
"optionId":{
"type":"int",
"description":"Unique id for this product in its purchased option"
},
"optionDescription":{
"type":"int",
"description":"Name of this item in its ordered material and variant options"
},
"quantity":{
"type":"int",
"description":"Total quantity of this product purchased in this order"
},
"models":{
"type":"array",
"description":"Contains detailed information for each model in the purchased product",
"items":{
"type":"object",
"description":"3D printed models in your ordered product",
"properties":{
"modelId":{
"type":"int",
"description":"Model id"
},
"materialId":{
"type":"int",
"description":"Material id"
},
"title":{
"type":"int",
"description":"The title of the model at time of purchase"
}
}
}
}
}
}
}
}
}
nextActionSuggestions
object
Suggestions for next actions
Shipping Options
Use the /cart/shipping-options/v1 API endpoint to determine what shipping options are available for your order.
GET - Shipping Options
Retrieves information about the shipping options available to the shipping location
Request
GET /cart/shipping-options/v1
parameters
type
required
description
country
string
required
2-letter country code (ISO 3166) of the shipping address
zipCode
string
optional
Shipping address zip code
Response
parameters
type
description
result
string
A 'result' field stating 'success'
shippingOptions
object
Available shipping options
{
"shippingOptionId":{
"type":"int",
"description":"Id of the intended shipping option. Should be included in the request to the order creation endpoint to set the shipping option"
},
"price":{
"type":"float",
"description":"Cost of that shipping option without tax in USD"
},
"name":{
"type":"string",
"description":"Display name of shipping option"
},
"inTransitDaysMin":{
"type":"int",
"description":"Minimum shipping days (Business days)"
},
"inTransitDaysMax":{
"type":"int",
"description":"Maximum shipping days (Business days)"
}
}