Registration

back to top

The first step in getting started is to signup for a developer account at http://devportal.3dcart.com. Once you have finished registration, click the 'Add New' button to add an application to your account. Enter your application's name and click the 'Create App' button. This will generate a public/private key pair. The private key is required within your application to connect to the 3dcart API, and will be passed in each request header with the 'PrivateKey' header key (see chapter on 'Authentication' for more details and code examples).

The public key is required by 3dcart merchants to subscribe to your application, which authorizes your application to access the 3dcart merchant's store data. So, the public key will be used by 3dcart merchants to authorize your application. The 3dcart merchant will complete this process in Modules -> REST API

Once the merchant has subscribed to your application, their domain name will be listed in your application's information screen under the section 'Stores that are using this APP'. Also listed on this page is the token that was generated when the merchant subscribed to your application:

The token is required within your application to connect to the 3dcart merchant's store, and will be passed in each request header with the 'token' header key (see chapter on 'Authentication' for more details and code examples).

CallBackURL

An important feature of your application within the developer portal is the CallBackURL. If the CallBackURL field is populated, when a merchant subscribes or unsubscribes to your application, 3dcart will POST to this URL. The 3dcart POST request will contain the following JSON content:

{
"PublicKey":"12121212121212121212121212121212",
"TimeStamp":"MM-DD-YYYY HH:MM:SS",
"TokenKey":"34343434343434343434343434343434",
"Action":"AUTHORIZE",
"SecureURL":"https://merchant-store.3dcartstores.com",
}

In the above JSON, the TimeStamp is Eastern Standard Time (EST) and the Action has two possible values: AUTHORIZE and REMOVE. An HTTP response code of 200 is expected to be received, and this will complete the merchant's subscription/removal process. Optionally, you can include JSON content in this response, as below:

{
"PostBackURL:" "http://www.software-dev.com/path/to/some/page.html?query_string"
}

If this response is received by 3dcart, we will open this URL in a popup for the merchant and complete the registration. Some example use cases for this feature might be to present a registration window to an unregistered merchant attempting to subscribe to your application, a "thank you for subscribing" confirmation message, or a survey questionnaire when unsubscribing.

If the response code is anything other than 200, a "Server not Responding" message will be presented to the 3dcart merchant, and they will not be able to subscribe to your application.

back to top

Authentication

back to top

Once the registration and subscription process has been completed (see chapter on 'Registration' for more information), you will have the information necessary for authentication with your API client. You will need the following from your application's information within your Dashboard at http://devportal.3dcart.com:

The Secure URL, Private Key, and Token will then need to be included in the HTTP Header of every request (see 'Sample Authentication' below):


  • SecureUrl: 3dcart merchant's Secure URL.
  • PrivateKey: Your application's private key.
  • Token: The 3dcart merchant's token.

The endpoint URL for all requests will be (please note that you MUST connect securely via HTTPS): https://apirest.3dcart.com/3dCartWebAPI/{version}/{service} Please see 'Sample Authentication' below for example.

Sample Authentication


Please click here to download the C# Rest API Client project from GitHub.
not yet available
not yet available


Versioning

back to top

In order to better support backwards compatibility, and to make sure that future updates to the API do not cause service interruptions to your application, the 3dcart API requires the version to be included as one of the URL parameters (e.g. '/3dCartWebAPI/v1/Customers').


Sample Versioning

Please click here to download the C# Rest API Client project from GitHub.
not yet available
not yet available


Response Messages:

back to top
HTTP Method HTTP Response Code Message/Response Content
POST 201

A JSON array will be returned. See below.

PUT 200

A JSON array will be returned. See below.

PUT 206

Partial update. Some items within the request failed to process. A JSON array will be returned for each item that was sent in the update request (See below for array details). An individual resopnse code will be returned for each item.

PUT 404

No response content will be received, however, this means the item being updated in the request was not found in the database.

DELETE 200

A JSON array will be returned. See below.

DELETE 404

No response content will be received, however, this means the item being updated in the request was not found in the database.

ALL 400

No response content will be received, however, this means the JSON object sent was invalid for the service requested.

ALL 415

Unsupported media type. Please check the Content-type header value to make sure it is a valid XML or JSON content type.

ALL 500

No response content will be received, however, this means an internal server error occured. If the problem continues, contact Technical Support.

Response Array:

KEY VALUE
Key The primary key of the table being updated. For example, if adding a product, this value will be 'CatalogID'.
Value The unique value that was inserted into the table being updated. Using the previous example of a product being added, this would be the unique, auto-incremented integer inserted into the 'products' table.
Status The HTTP status code (e.g. 200 or 201, depending on the HTTP Method)
Message A confirmation message.

OData

back to top

The 3dcart RestAPI supports some functionality of the OData standard when retrieving information via an HTTP GET method. The OData queries currently supported are:


  • SELECT
  • ORDERBY

It is important to note that the SELECT and ORDERBY queries will be executed on the result set already returned in the API response. So, it acts as an additional filter - post execution - of your API request. The 3dcart sample client(s) were developed with this in mind, and can be used to demonstrate usage of OData queries with the 3dcart RestAPI.

Please see www.odata.org for more information on OData.



Rate Limits (throttling)

back to top

Requests to the 3dcart Rest API have the following rules:

Batch size
This is the maximum number of records that can be retrieved in a single request.

  • GET Orders: 300
  • GET Products: 200
  • All Others: 500

  • POST - ALL
  • PUT - (see the throttling limits below)

Maximum requests
Using the "Leaky Bucket" algorithm for throttling, the maximum number of requests (bucket size) is 50 with a "leak" rate of 2/second. This allows you to send small "bursts" of up to 50 requests when needed, as long as the rate you send requests remains under 2 per second after this burst.

These limits help to manage load on our servers, ensuring that high API request volumes don’t impact on overall store performance. They also help to protect stores from deliberate or accidental denial of service as a result of the API being flooded with requests.




RMA

back to top

A request to the RMA web service accepts one parameter - rmaid - when requesting a specific RMA, and allows several optional parameters to be included as a URL query string to further filter the results returned. The HTTP method/verb is also used to determine if the request will retrieve, update, add , or delete a RMA record(s).

APIDescription
GET 3dCartWebAPI/v1/RMA/{rmaid}

Get a specific RMA

GET 3dCartWebAPI/v1/RMA

Get all RMAs

GET 3dCartWebAPI/v1/RMA/{rmaid}/Items

Gets the items from a specific RMA



CustomerGroups

back to top

A request to the CustomerGroups web service accepts one parameter - groupid - when requesting a specific customer group, and allows several optional parameters to be included as a URL query string to further filter the results returned. The HTTP method/verb is also used to determine if the request will retrieve, update, add , or delete a customer group record(s).

APIDescription
GET 3dCartWebAPI/v1/CustomerGroups

Get all CustomerGroups

GET 3dCartWebAPI/v1/CustomerGroups/{id}

Get a CustomerGroup

POST 3dCartWebAPI/v1/CustomerGroups

Adds a new customer group to the system

PUT 3dCartWebAPI/v1/CustomerGroups/{customergroupid}

This method is used to update a single customer group in the database. The {id} parameter specifies which customer group to update.

PUT 3dCartWebAPI/v1/CustomerGroups

This method updates a collection of customer groups in the database. No URL parameters should be included.

DELETE 3dCartWebAPI/v1/CustomerGroups/{id}

Deletes a customer group in the system



GiftRegistries

back to top

A request to the GiftRegistries web service accepts one parameter - giftregistryid - when requesting a specific Gift Registry, and allows several optional parameters to be included as a URL query string to further filter the results returned. The HTTP method/verb is also used to determine if the request will retrieve, update, add , or delete a Gift Registry record(s).

APIDescription
GET 3dCartWebAPI/v1/GiftRegistries/{giftregistryid}

Get a specific GiftRegistry

GET 3dCartWebAPI/v1/GiftRegistries

Get all GiftRegistries

GET 3dCartWebAPI/v1/GiftRegistries/{giftregistryid}/Items

Gets the items from a specific Gift Registry



Customers

back to top

A request to the Customers web service accepts one parameter - customerid - when requesting a specific customer, and allows several optional parameters to be included as a URL query string to further filter the results returned. The HTTP method/verb is also used to determine if the request will retrieve, update, add , or delete a customer record(s).

APIDescription
GET 3dCartWebAPI/v1/Customers

Get all Customers

GET 3dCartWebAPI/v1/Customers/{id}

Get a Customer

GET 3dCartWebAPI/v1/CustomerGroups/{id}/Customers

Get Customers from a Customer Group

POST 3dCartWebAPI/v1/Customers

Adds a new customer to the system

PUT 3dCartWebAPI/v1/Customers/{customerid}

This method is used to update a single customer record in the database. The {id} parameter specifies which customer record to update.

PUT 3dCartWebAPI/v1/Customers

This method is used to update multiple customers in the system. No URL parameters should be included.

DELETE 3dCartWebAPI/v1/Customers/{id}

Deletes a Customer in the system



Distributors

back to top

A request to the Distributors web service accepts one URL parameter - distributorid - when requesting a specific distributor, and allows several optional parameters to be included as a URL query string to further filter the results returned when requesting a list of distributors. The HTTP method/verb (GET, PUT, POST, and DELETE) is also used to determine if the request will retrieve, update, add, or delete a distributor record(s).

APIDescription
GET 3dCartWebAPI/v1/Distributors

Get all Distributors

GET 3dCartWebAPI/v1/Distributors/{id}

Get a Distributor

POST 3dCartWebAPI/v1/Distributors

Adds a new distributor to the system

PUT 3dCartWebAPI/v1/Distributors/{distributorid}

This method is used to update a single distributor record in the database. The {distributorid} parameter specifies which distributor to update.

PUT 3dCartWebAPI/v1/Distributors

This method is used to update multiple distributor records in the database. No {distributorid} parameters should be included.

DELETE 3dCartWebAPI/v1/Distributors/{id}

Deletes a Distributor in the system



Category

back to top

A request to the Category web service accepts one URL parameter - categoryid - when requesting a specific category, and allows several optional parameters to be included as a URL query string to further filter the results returned when requesting a list of categories. The HTTP method/verb (GET, PUT, POST, and DELETE) is also used to determine if the request will retrieve, update, add, or delete a category record(s).

APIDescription
GET 3dCartWebAPI/v1/Categories

Get all Categories

GET 3dCartWebAPI/v1/Categories/{id}

Get a Category

GET 3dCartWebAPI/v1/Categories/{categoryid}/Options

Get the options from a specific Category

POST 3dCartWebAPI/v1/Categories

Adds a new category to the system

POST 3dCartWebAPI/v1/Categories/{categoryid}/Options

Adds a new OptionSet to the system

PUT 3dCartWebAPI/v1/Categories/{categoryid}

This method is used to update a single category record in the database. The {categoryid} parameter specifies which category to update.

PUT 3dCartWebAPI/v1/Categories

This method is used to update multiple category records in the database. No {categoryid} parameters should be included.

PUT 3dCartWebAPI/v1/Categories/{categoryid}/Options

Updates a collection of options from a specific Category

PUT 3dCartWebAPI/v1/Categories/{categoryid}/Options/{optionsetid}

Updates specific options from a specific Category

DELETE 3dCartWebAPI/v1/Categories/{id}

Deletes a Category in the system



Products

back to top

A request to the Products web service accepts one URL parameter - catalogid - when requesting a specific product, and allows several optional parameters to be included as a URL query string to further filter the results returned when request a list of products. The HTTP method/verb is also used to determine if the request will retrieve, update, add , or delete a product record(s).

APIDescription
GET 3dCartWebAPI/v1/Products

Get all products

GET 3dCartWebAPI/v1/Products/{catalogid}

Get a product

GET 3dCartWebAPI/v1/Distributors/{distributorid}/Products

Get all products from a specific distributor

GET 3dCartWebAPI/v1/Manufacturers/{manufacturerid}/Products

Get all products from a specific manufacturer

GET 3dCartWebAPI/v1/Categories/{categoryid}/Products

Get all products from a specific category

GET 3dCartWebAPI/v1/Products/{catalogid}/skuinfo

Get all products (SKUInfo section only)

GET 3dCartWebAPI/v1/Products/skuinfo

Get all products (SKUInfo section only)

GET 3dCartWebAPI/v1/Products/{catalogid}/Options

Get the options from a specific Product

GET 3dCartWebAPI/v1/Products/{catalogid}/Categories

Get the categories from a specific Product

GET 3dCartWebAPI/v1/Products/{catalogid}/Distributors

Get the distributors from a specific Product

GET 3dCartWebAPI/v1/Products/{catalogid}/Images

Get the images from a specific Product

GET 3dCartWebAPI/v1/Products/{catalogid}/Features

Get the features from a specific Product

GET 3dCartWebAPI/v1/Products/{catalogid}/Related

Get the related products from a specific Product

GET 3dCartWebAPI/v1/Products/{catalogid}/UpSelling

Get the upselling products from a specific Product

GET 3dCartWebAPI/v1/Products/{catalogid}/Discount

Get the discounts from a specific Product

GET 3dCartWebAPI/v1/Products/{catalogid}/Serials

Get the serials from a specific Product

GET 3dCartWebAPI/v1/Products/{catalogid}/AdvancedOptions

Get the advanced options from a specific Product

GET 3dCartWebAPI/v1/Products/{catalogid}/EProducts

Get the EProducts from a specific Product

POST 3dCartWebAPI/v1/Products

Adds a new product to the system

POST 3dCartWebAPI/v1/Products/{catalogid}/Images

Adds a new image to the system

POST 3dCartWebAPI/v1/Products/{catalogid}/Features

Adds a new feature to the system

POST 3dCartWebAPI/v1/Products/{catalogid}/Related

Adds a new related product to the system

POST 3dCartWebAPI/v1/Products/{catalogid}/UpSelling

Adds a new upselling item to the system

POST 3dCartWebAPI/v1/Products/{catalogid}/Discount

Adds a new discount to the system

POST 3dCartWebAPI/v1/Products/{catalogid}/Serials

Adds a new serial to the system

POST 3dCartWebAPI/v1/Products/{catalogid}/EProducts

Adds a new eproduct to the system

POST 3dCartWebAPI/v1/Products/{catalogid}/Options

Adds a new OptionSet to the system

PUT 3dCartWebAPI/v1/Products/{catalogid}

This method is used to update a single product record in the database. The {catalogid} parameter specifies which product record to update.

PUT 3dCartWebAPI/v1/Products

This method is used to update multiple products in the database. No URL parameters should be included.

PUT 3dCartWebAPI/v1/Products/{catalogid}/Images

Updates a collection of images from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/Images/{imagegalleryid}

Updates a specific image from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/Features

Updates a collection of features from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/Features/{featureid}

Updates a specific feature from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/Related

Updates a collection of related products from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/Related/{relatedindexid}

Updates a specific related product from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/UpSelling

Updates a collection of upselling items from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/UpSelling/{upsellingindexid}

Updates a specific Upselling Item from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/Discount

Updates a collection of discounts from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/Discount/{discountid}

Updates a specific discount from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/Serials

Updates a collection of serials from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/Serials/{serialid}

Updates a specific serial from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/EProducts

Updates a collection of eproducts from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/EProducts/{filenumber}

Updates a specific eproduct from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/Options

Updates a collection of options from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/Options/{optionsetid}

Updates specific options from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/AdvancedOptions

Updates a collection of advanced options from a specific Product

PUT 3dCartWebAPI/v1/Products/{catalogid}/AdvancedOptions/{advancedoptioncode}

Updates specific advanced options from a specific Product

DELETE 3dCartWebAPI/v1/Products/{catalogid}

Deletes a product in the system



Manufacturer

back to top

A request to the Manufacturers web service accepts one URL parameter - manufacturerid - when requesting a specific manufacturer, and allows several optional parameters to be included as a URL query string to further filter the results returned when requesting a list of manufacturers. The HTTP method/verb (GET, PUT, POST, and DELETE) is also used to determine if the request will retrieve, update, add, or delete a manufacturer record(s).

APIDescription
GET 3dCartWebAPI/v1/Manufacturers/{id}

Get a Manufacturer

GET 3dCartWebAPI/v1/Manufacturers

Get all Manufacturers

POST 3dCartWebAPI/v1/Manufacturers

Adds a new manufacturer to the system

PUT 3dCartWebAPI/v1/Manufacturers/{manufacturerid}

This method is used to update a single manufacturer record in the database. The {manufacturerid} parameter specifies which manufacturer record to update.

PUT 3dCartWebAPI/v1/Manufacturers

This method is used to update multiple manufacturers in the database. No URL parameters should be included.

DELETE 3dCartWebAPI/v1/Manufacturers/{id}

Deletes a Manufacturer in the system



Orders

back to top

A request to the Orders web service can include one URL parameter - orderid - when requesting a specific order, and allows several optional parameters to be included as a URL query string to further filter the results returned when requesting a list of orders. The HTTP method/verb (GET and PUT) is also used to determine if the request will retrieve or update (POST and DELETE are not possible with orders) an order record(s).

APIDescription
GET 3dCartWebAPI/v1/Orders/{orderid}

Get a specific order

GET 3dCartWebAPI/v1/Orders

Get all orders

GET 3dCartWebAPI/v1/Orders/{orderid}/Shipments

Gets the shipments from a specific Order

GET 3dCartWebAPI/v1/Orders/{orderid}/Items

Gets the items from a specific Order

GET 3dCartWebAPI/v1/Orders/{orderid}/Transactions

Gets the transactions from a specific Order

GET 3dCartWebAPI/v1/Orders/{orderid}/Questions

Gets the questions from a specific Order

POST 3dCartWebAPI/v1/Orders

Adds a new order to the system

POST 3dCartWebAPI/v1/Orders/{orderid}/Shipments

Adds a new shipment on the order

POST 3dCartWebAPI/v1/Orders/{orderid}/Items

Adds a new item on the order

POST 3dCartWebAPI/v1/Orders/{orderid}/Transactions

Adds a new transaction on the order

POST 3dCartWebAPI/v1/Orders/{orderid}/Questions

Adds a new question on the order

PUT 3dCartWebAPI/v1/Orders/{orderid}

This method is used to update a single order record in the database. The {orderid} parameter specifies which order record to update.

PUT 3dCartWebAPI/v1/Orders

This method is used to update multiple orders in the database. No URL parameters should be included.

PUT 3dCartWebAPI/v1/Orders/{orderid}/Shipments

Updates a collection of shipments from a specific Order

PUT 3dCartWebAPI/v1/Orders/{orderid}/Shipments/{shipmentid}

Updates a specific shipment from a specific Order

PUT 3dCartWebAPI/v1/Orders/{orderid}/Items

Updates a collection of items from a specific Order

PUT 3dCartWebAPI/v1/Orders/{orderid}/Items/{itemindexid}

Updates a specific item from a specific Product

PUT 3dCartWebAPI/v1/Orders/{orderid}/Transactions

Updates a collection of transactions from a specific Order

PUT 3dCartWebAPI/v1/Orders/{orderid}/Transactions/{transactionindexid}

Updates a specific transaction from a specific Product

PUT 3dCartWebAPI/v1/Orders/{orderid}/Questions

Updates a collection of questions from a specific Order

PUT 3dCartWebAPI/v1/Orders/{orderid}/Questions/{questionanswerindexid}

Updates a specific question from a specific Product