Stuller Web API Help Page

Introduction

The following REST APIs can be used to access Stuller product, order, and invoice information.

The Product API allows you to retrieve all data for any Stuller product(s). This includes real-time pricing and availability information. The Product API has endpoints that allow you to customize a product in the same ways you may customize an item on Stuller.com. This includes setting stones, exact ring sizing, and adding engravings.

The Gem API allows you to 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).

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.

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.

How to Authenticate

Access to Stuller APIs are dependent on being a Stuller account owner. Stuller.com users with either the Administrator or Developer roles assigned are able to authenticate requests to Stuller APIs. Our APIs use basic authentication over SSL. Stuller.com logins can be created and managed here. Please note that Developer logins will not be able to login into Stuller.com. This type of login is intended only for development use, done outside of Stuller.com. Documentation and examples requests for the available APIs can be found here.

Gem

The Gem API returns data on certified stones of a given type.

URI	Description
GET api/v2/gem	Returns the full list of Stuller certified stones. These are unique stones that come with a grading report.
GET api/v2/gem/diamonds	Returns only natural certified diamonds
POST api/v2/gem/diamonds	Returns only natural certified diamonds
GET api/v2/gem/gemstones	Returns only certified gemstones
POST api/v2/gem/gemstones	Returns only certified gemstones
GET api/v2/gem/labgrowndiamonds	Returns only lab-grown certified diamonds
POST api/v2/gem/labgrowndiamonds	Returns only lab-grown certified diamonds

Invoice

The Invoice API is used to retrieve available invoice and tracking infromation for previously placed orders.

URI	Description
GET api/v2/invoice	Returns invoice and tracking information for orders
POST api/v2/invoice	Returns invoice and tracking information for orders
GET api/v2/invoice/shipment?shipmentheaderid={shipmentheaderid}	Returns a list of invoices and their associated details from a given shipment
POST api/v2/invoice/shipment	Returns a list of invoices and their associated details from a given shipment

Orders

The Orders API can be used to retrieve order details for previous orders, and transmit new orders.

URI	Description
GET api/v2/orders	Returns the Order details and status information
POST api/v2/orders	Returns the Order details and status information
POST api/v2/orders/submitorder	Transmit order data to Stuller. Response will indicate a success or failure

Products

The Product API returns all requested data for the requested items. The Product API can also be used to generate a customized item.

URI	Description
GET api/v2/products	Returns specified product data based on specified items. All products and associated data are available if requested.
POST api/v2/products	Returns specified product data based on specified items. All products and associated data are available if requested.
GET api/v2/products/stonefamilies	Used to retrieve available stone families in a mounting's stone location(s).
POST api/v2/products/stonefamilies	Used to retrieve available stone families in a mounting's stone location(s).
GET api/v2/products/searchstones	Allows for the searching of stones by their location(s).
POST api/v2/products/searchstones	Allows for the searching of stones by their location(s).
GET api/v2/products/searchstonesbystonegroup	Allows for the search of available stones by their stone group. A stone group is a group of stones that are similar in size and location on the piece.
POST api/v2/products/searchstonesbystonegroup	Allows for the search of available stones by their stone group. A stone group is a group of stones that are similar in size and location on the piece.
POST api/v2/products/configureproduct	Transmit data indicating how you wish to customize a given item. The response will include updated pricing, imagery, and an estimated ship date based on your customization selections.
GET api/v2/products/advancedproductfilters	Returns available Advanced Product Filter types and values.
POST api/v2/products/advancedproductfilters	Returns available Advanced Product Filter types and values.
GET api/v2/products/relatedadvancedproductfilters	Returns related Advanced Product Filters based on the supplied type.
POST api/v2/products/relatedadvancedproductfilters	Returns related Advanced Product Filters based on the supplied type.
POST api/v2/products/bestfitstonesbydimensions	Returns best fit stones available to set by the requested mounting location dimensions.v
GET api/v2/products/configuredproduct	Returns full details of a customized item by the requested configuration ID.
POST api/v2/products/configuredproduct	Returns full details of a customized item by the requested configuration ID.
GET api/v2/products/virtual	Returns data on "virtual" semi-set inventory for items within the Stuller.com 3C Collection. These items cannot be found directly on Stuller.com and only serve as a different starting point.
POST api/v2/products/virtual	Returns data on "virtual" semi-set inventory for items within the Stuller.com 3C Collection. These items cannot be found directly on Stuller.com and only serve as a different starting point.