A variety of APIs are available to you, making it possible to integrate your website with Stuller.
Note: Attempting to utilize our APIs is only recommended if you have development resources helping to build and maintain your website.
Stuller APIs
The Stuller API is a collection of REST endpoints that enable a client to interact with Stuller.
Given the complexity of some of the requests, each HTTP GET endpoint will also support HTTP POST
method.
Request and Response structure can be found at http://api.stuller.com/help
Familiarize yourself with our suite of APIs by reviewing the information below.
NOTE: While our Product and Gem APIs provide real-time product information, we strongly suggest downloading and staging the necessary data to maintain your website's product listings. Our APIs are not built to support the real-time loading of other websites.
Product API
Retrieve all data for any Stuller product(s) including real-time pricing and availability information.
Product Configuration API
The configuration section of the Stuller Product API is a set of REST endpoints used to receive data on Stuller configurations.
Virtual Product API
The Stuller Virtual Product API is a REST endpoint to used to receive data on the Stuller virtual products. Virtual products are semi-set jewelry products created exclusively for the API with the intent to alleviate challenges with pricing and media.
Gem API
Retrieve data for all active certified stones. Stuller carries unique certified stones (that come with a grading report) which are broken out into three different categories: Certified Natural Diamonds, Certified Lab-Grown Diamonds, Certified Gemstones (varying types).
Order API
The Order API allows you to transmit orders to Stuller and check the status of previous orders. This is ideal to use in conjunction with Stuller's Pack and Ship services.
Invoice API
The Invoice API is used to retrieve available invoice and tracking information for previously placed orders.
Stuller API Authentication
Stuller.com users with either the admin or developer role assigned are used to authenticate against the Stuller API. The API uses basic authentication over SSL.
If you will be working with a developer and wish to set up a developer login, you can do so by logging into your account and visiting Create/Manage Logins. You will create a new username and password and select “developer” as the permission.
Developer logins are only granted access to our APIs and will not have the ability to view any authenticated section of Stuller.com.
The example below shows how you should set up your request using the credentials you have created.
POST https://api.stuller.com/v2/products?SKU=IOLITE-GEN:117417:G
Authorization: Basic UN:PWD
Host:api.stuller.com
Request Format
The Stuller API both accepts and transmits JSON and XML. This is controlled by setting the HTTP headers Accept and Content-Type. The examples below show both JSON and XML requests.
POST https://api.stuller.com/v2/products?SKU=IOLITE-GEN:117417:G
Authorization: Basic UN:PWD
Accept: application/xml
Content-Type: application/xml
Host: api.stuller.com
POST https://api.stuller.com/v2/products?SKU=IOLITE-GEN:117417:G
Authorization: Basic UN:PWD
Accept: application/json
Content-Type: application/json
Host: api.stuller.com
Product API
The Stuller Product API is a REST endpoint to used to receive data on the Stuller products.
The SKU, ItemId, Series, or Category can be used as an initial filter to indicate the data that needs to be retrieved.
A detailed description of the product request and response can be found at this URL.
https://www.stuller.com/api/Help/Api/POST-namespace-v2.Products-Rest
A list of includes can be found at this URL.
Note: A basic request made to /v2/products will return general product data. Our includes are offered so that you are able to pull additional item details such as media and configuration options.
https://www.stuller.com/api/Help/ResourceModel?modelName=v2.ProductInclude
A list of filters can be found at the URL below.
Note: Advanced filters can also be used to narrow down the returned amount of items. Additional filtering outside of what is offered will need to be done outside of the request.
https://www.stuller.com/api/Help/ResourceModel?modelName=v2.ProductFilter
| Environment | Endpoint |
|---|---|
| Production | https://api.stuller.com/v2/products |
Category Example
This following example will pull all product in the 3C category.
The initial request will indicate the Category ID for 3C as will as what needs to be filtered and included.
POST https://api.stuller.com/v2/products
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{"CategoryIds":[23618], "Include": ["All"], "Filter":["Orderable","OnPriceList"]}
NextPage Attribute
A limit of 500 products can be downloaded at a time. To obtain the next set of products you will use the NextPage attribute.
The NextPage attribute on the reponse is intended to be used to page subsequent requests.
When the NextPage attribute returns null, there are no more results. An example request can be found below.
When this value is null there are no more results.
Post https://api.stuller.com/v2/products HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{"NextPage":"<string from previous request>"}
Product Configuration API
The configuration section of the Stuller Product API is a set of REST endpoints used to receive data on Stuller configurations.
| Environment | Endpoint |
|---|---|
| Production | https://api.stuller.com/v2/products |
The following REST endpoints make up the configuration section of the api.
Configuration Example ( Bridal )
This following example will walk through configuring a 3C product using the API.
- Get the product by SKU number and specify include information. In this case, we want all the child relationships.
- Get the stone families for location and stone groups.
This information can be found on the ConfigurationModel of the product from the previous request. - Now there are two options, we can either search for stones by location or by stone group.
A stone group is just a group of stones that are similar in size and location on the piece such as accent.
The stone families returned from the previous request are used to narrow search. - The final request uses stones selected from previous request to retrieve all configuration information including pricing and images.
POST https://api.stuller.com/v2/products
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{"SKU":["122052:111:P"],"Include":["All"]}
POST https://api.stuller.com/v2/products/stonefamilies
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{ "ConfigurationModelId": 592868, "LocationNumbers": [1,2,3,4],"StoneGroups": ["Center","Halo","Accent 1","Accent 2"]}
POST https://api.stuller.com/v2/products/searchstones
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{"ConfigurationModelId": 592868,"LocationNumbers": [4],"StoneFamilyName": "Diamond","StoneCategories": ["Genuine","Imitation"]}
POST https://api.stuller.com/v2/products/configureproduct
Content-Type: application/json
Accept: application/json
Authorization: UN:PWD
Host: api.stuller.com
{
"ProductId" : 6079162,
"Quantity" : 1,
"Stones" : [
{
"LocationNumber" : 1,
"StoneProductId" : 2542244
},
{
"LocationNumber" : 2,
"StoneProductId" :3051490
},
{
"LocationNumber" : 3,
"StoneProductId" : 3051490
},
{
"LocationNumber" : 4,
"StoneProductId" :2610440
}
],
"RingSize" : 7.0
}
Configuration Example ( Family Jewelry )
This following example will walk through configuring a Family Jewelery product using the API.
- Get all products in a Series. In this example, the products are filtered by MetalQuality
- Get the product by SKU number and specify include information. In this case, we want all the child relationships so the include value ALL is used.
- Get the stone families for location and stone groups.
This information can be found on the ConfigurationModel of the product from the previous request. - Now there are two options, we can either search for stones by location or by stone group.
A stone group is just a group of stones that are similar in size and location on the piece such as accent.
The stone families returned from the previous request are used to narrow search. - The final request uses stones selected from previous request to retrieve all configuration information including pricing and images.
POST https://api.stuller.com/v2/products
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{
"Series": ["72061"],
"Include": ["ExcludeAll"],
"AdvancedProductFilters": [{
"Type": "MetalQuality",
"Values": [{
"Value": "14KW"
}, {
"Value": "14KY"
},
]
}
]
}
POST https://api.stuller.com/v2/products
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{
"SKU": ["72061:125:P"],
"Include": ["All"]
}
POST https://api.stuller.com/v2/products/stonefamilies
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{
"ConfigurationModelId": 755815,
"LocationNumbers": [1, 2]
}
POST https://api.stuller.com/v2/products/searchstones
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{
"ConfigurationModelId": 755815,
"LocationNumbers": [2],
"StoneFamilyName": "Amethyst",
"StoneCategories": ["Genuine", "Imitation"]
}
POST https://api.stuller.com/v2/products/configureproduct
Content-Type: application/json
Accept: application/json
Authorization: UN:PWD
Host: api.stuller.com
{
"ProductId" : 15131171,
"Quantity" : 1,
"Stones" : [
{
"LocationNumber" : 1,
"StoneProductId" : 201969
},
{
"LocationNumber" : 2,
"StoneProductId" :54664
}
],
"RingSize" : 7.0
}
Virtual Product API
The Stuller Virtual Product API is a REST endpoint to used to receive data on the Stuller virtual
products.
Virtual products are semi-set jewelry products created exclusively for the API with the intent to
alleviate challenges with pricing and media.
Virtual products are preset with the following diamond color and quality combinations for accent and
side stones.
G-H VS
G-H SI1
G-H SI2-SI3
G-H I1
These products can be purchased using the Order API or on Stuller.com. For Stuller.com, the SKU (ex. CONFIG.3755600) to directly navigate to the product.
The SKU, Series, or Category can be used as an initial filter to indicate the data that needs to be retrieved.
A limit of 500 products can be downloaded at a time.
The NextPage attribute on the reponse is intended to be used to page subsequent requests.
When the NextPage attribute returns null when there are no more results.
A detailed description of the virtual product request and response can be found at this URL.
https://www.stuller.com/api/Help/Api/POST-namespace-v2.Products-Virtual
A list of includes can be found at this URL.
https://www.stuller.com/api/Help/ResourceModel?modelName=v2.ProductInclude
A list of filters can be found at this URL.
https://www.stuller.com/api/Help/ResourceModel?modelName=v2.ProductFilter
| Environment | Endpoint |
|---|---|
| Production | https://api.stuller.com/v2/products/virtual |
Virtual Product Example
This following example will pull all virtual product in the 3C series.
The initial request will indicate the series number for the 3C virtual product as will as what needs
to be filtered and included.
POST https://api.stuller.com/v2/products/virtual
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{
"Include": ["All"],
"Filter": ["Orderable"],
"Series": ["122798"],
"AdvancedProductFilters": [{
"Type": "MetalQuality",
"Values": [{
"Value": "14KW"
}
]
}, {
"Type": "SideStoneColorQuality",
"Values": [{
"Value": "G-H SI1"
}
]
}, {
"Type": "CenterStoneShape",
"Values": [{
"Value": "Round"
}
]
}, {
"Type": "CenterStoneSize",
"Values": [{
"Value": "4.10"
}
]
}
]
}
The following example shows usage of the next page attribute in the subsequent request.
This value was returned on the previous response.
When this value is null there are no more results.
POST https://api.stuller.com/v2/products/virtual
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{"NextPage":"<string from previous request>"}
Gem API
The Stuller Gem API is a REST endpoint to be used to receive data on the Stuller gems. The API provides several options to recieve data for diamonds, gemstones, and lab-created diamonds.
All Diamonds, Gemstones, and Lab-Created Diamonds
The base API operation returns all available diamonds, gemstones, and lab-created diamonds in a
single call.
This operation does not support filtering. Filtering will need to be implemented on the client
side.
A detailed description of the diamond request and response can be found at this URL.
https://www.stuller.com/api/Help/Api/GET-namespace-v2.Gem-Rest
| Environment | Endpoint |
|---|---|
| Production | https://api.stuller.com/v2/gem |
All Example
This following example will return all available diamonds, gemstones, and lab-created diamonds.
GET https://api.stuller.com/v2/gem
Authorization: Basic UN:PWD
Accept: application/json
Content-Type: application/json
Host:api.stuller.com
Diamonds
The diamonds operation will return all available diamonds
A limit of 200 gems can be downloaded at a time.
The NextPage attribute on the reponse is intended to be used to page subsequent requests.
When the NextPage attribute returns null when there are no more results.
A detailed description of the diamond request and response can be found at this URL.
https://www.stuller.com/api/Help/Api/POST-namespace-v2.Gem-Diamonds
| Environment | Endpoint |
|---|---|
| Production | https://api.stuller.com/v2/gem/diamonds |
Diamonds Example
This following example will return all diamonds.
GET https://api.stuller.com/v2/gem/diamonds
Authorization: Basic UN:PWD
Accept: application/json
Content-Type: application/json
Host:api.stuller.com
This following example will return all diamonds with G/H color and SI1/SI2 clarity.
POST https://api.stuller.com/v2/gem/diamonds
Authorization: Basic UN:PWD
Accept: application/json
Content-Type: application/json
Host:api.stuller.com
{“Color”:[“G”,“H”],“Clarity”:[“SI1”,“SI2”]}
The following example shows usage of the next page attribute in the subsequent request.
This value was returned on the previous response.
When this value is null there are no more results.
GET https://api.stuller.com/v2/gem/diamonds
Content-Type: application/json
Accept: application/json
Authorization: Basic UN:PWD
Host: api.stuller.com
{"NextPage":"<string from previous request>"}
Gemstones
The gemstones operation will return all available gemstones.
A limit of 200 gems can be downloaded at a time.
The NextPage attribute on the reponse is intended to be used to page subsequent requests.
When the NextPage attribute returns null when there are no more results.
A detailed description of the gemstone request and response can be found at this URL.
https://www.stuller.com/api/Help/Api/POST-namespace-v2.Gem-Gemstones
| Environment | Endpoint |
|---|---|
| Production | https://api.stuller.com/v2/gem/gemstones |
Gemstones Example
This following example will return all gemstones.
GET https://api.stuller.com/v2/gem/gemstones
Authorization: Basic UN:PWD
Accept: application/json
Content-Type: application/json
Host:api.stuller.com
Lab-Created Diamonds
The labgrowndiamonds operation will return all available lab-created diamonds.
A limit of 200 gems can be downloaded at a time.
The NextPage attribute on the reponse is intended to be used to page subsequent requests.
When the NextPage attribute returns null when there are no more results.
A detailed description of the lab-created diamonds request and response can be found at this URL.
https://www.stuller.com/api/Help/Api/POST-namespace-v2.Gem-LabGrownDiamonds
| Environment | Endpoint |
|---|---|
| Production | https://api.stuller.com/v2/gem/labgrowndiamonds |
Lab-Created Diamonds Example
This following example will return all lab-created diamonds.
GET https://api.stuller.com/v2/gem/labgrowndiamonds
Authorization: Basic UN:PWD
Accept: application/json
Content-Type: application/json
Host:api.stuller.com
Order API
The Stuller Order API is a REST endpoint to receive 3PL orders.
| Environment | Endpoint |
|---|---|
| Production | https://api.stuller.com/v2/orders/submitorder |
Note: The TestMode attribute can be used to submit order through the API to production URL and stop the line items from being fullfilled.
Ship Method Codes
A code representing the carrier and ship method needs to be included on each order.
| Ship Method | Code |
|---|---|
| UPS Next Day Air | UPS_NEXT_DAY |
| UPS Next Day Saver | UPS_NEXT_DAY_SAVR |
| UPS 2nd Day Air | UPS_2DAY |
| UPS 3 Day Select | UPS_3DAY_SELECT |
| UPS Ground | UPS_GROUND |
| FedEx Priority | FED_PRIORITY |
| FedEx Standard Overnight | FED_STD_OVERNIGHT |
| FedEx 2nd Business Day PM | FED_2DAY |
| US Postal Service 1st Class Mail | USPS_FIRST_CLASS |
| FedEx International Priority | FED_INT_PRIORITY |
| UPS Worldwide Express | UPS_WW_EXPR |
| UPS Canada Ground | UPS_STD_CANADA |
| FedEx International Economy | FED_INT_ECONOMY |
| FedEx 3 Day Saver | FEDEX_EXPRESS_SAVER |
| US Postal Service Express | USPS_EXPRESS |
| US Postal Service Priority | USPS_PRIORITY |
| FedEx Home Delivery | FEDEX_HOME_DELIVERY |
Payment Information
In the example below the value of Terms is used to indicate the order will be invoiced to the customer and paid at a later agreed upon date by the customer. If Terms is not available to the customer, the value DefaultPayment can be used to specify that the default payment option for the user on the account be used for payment.
"Payment": {
"Type": "Terms"
}
Example Order API Request
The below JSON request
Post https://api.stuller.com/v2/orders/submitorder
Content-Type: application/json
Accept: application/json
Authorization: Basic <UN:PWD>
Host: api.stuller.com
{
"Type": "3pl",
"OrderID": "578663601",
"Account": "<Your ship-to account number>",
"PurchaseOrderNumber": "4938082",
"TestMode": true,
"CustomerData": {
"OrderNumber": "12773270",
"OrderDate": "2017-09-11",
"FreightAmount": "5.99",
"TaxAmount": "2.58",
"Message1": "Happy Engagement",
"Message2": "Love John"
},
"Contact": {
"Name": "John Smith",
"Phone": "5551234321",
"EmailAddress": "[email protected]"
},
"Payment": {
"Type": "Terms"
},
"ShipToAddress": {
"ShipComplete": true,
"ShipMethodType": "UPS_GROUND",
"RemovePricing": true,
"SignatureRequired": true,
"Address": {
"Name": "John Smith",
"AddressLine1": "123 Main Street",
"AddressLine1": "Apt. 2",
"City": "Lafayette",
"State": "LA",
"PostalCode": "70508",
"Country": "US"
}
},
"BillToAddress": {
"SameAsShipTo": "false",
"Address": {
"Name": "John Smith",
"AddressLine1": "457 Main Street",
"City": "Lafayette",
"State": "LA",
"PostalCode": "70508",
"Country": "US"
}
},
"Lines": [{
"Items": [{
"Stones": [{
"Location": 1,
"IsCustomerStone": true,
"CustomerStoneValue": 500
}, {
"Location": 2,
"Number": "DIAMOND-GEN:457966:G",
}, {
"Location": 3,
"Number": "DIAMOND-GEN:922511:G"
}, {
"Location": 4,
"Number": "DIAMOND-GEN:922511:G"
}
],
"Engravings": [{
"EngravingLine": [{
"LineLocation": 1,
"Text": "John"
}
],
"Location": 5,
"EngravingType": "LASER ENGRAVING",
"FontType": "HELVETICA",
"FontSize": "MEDIUM",
"FillOption": "Enamel Color",
"FillColor": "BLACK"
}
],
"Number":"122629:330:P",
"RingSize":"7.5"
}
],
"Quantity": 1,
"ExtendedPrice": 1500.0,
"Item": "LUM1234",
"Description": "14K White 7.4mm Round Engagement Ring Mounting"
}
]
}
Stuller Invoice API
The Stuller Invoice API is a REST endpoint to get information on invoices and shipments.
Invoices
A detailed description of the invoice request and response can be found at this URL.
https://www.stuller.com/api/Help/Api/GET-namespace-v2.Invoice-Rest
| Environment | Endpoint |
|---|---|
| Production | https://api.stuller.com/v2/invoice |
Invoice Example
This following example will return information for the invoice of a purchase order.
GET https://api.stuller.com/v2/invoice?PurchaseOrderNumber=PO12345
Authorization: Basic UN:PWD
Accept: application/json
Content-Type: application/json
Host:api.stuller.com
Shipments
This shipment header id is used to query this shipment. This is found using the bar code of the external label of the shipment.
A detailed description of the invoice request and response can be found at this URL.
https://www.stuller.com/api/Help/Api/GET-namespace-v2.Invoice-Shipment_ShipmentHeaderId
| Environment | Endpoint |
|---|---|
| Production | https://api.stuller.com/v2/invoice/shipment |
Shipment Example
This following example will return information for a particular shipment.
GET https://api.stuller.com/v2/invoice/shipment?shipmentheaderid=12345
Authorization: Basic UN:PWD
Accept: application/json
Content-Type: application/json
Host:api.stuller.com