Build an App

Introduction

The Shift4Shop API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON or XML will be returned in all responses from the API, including errors.

Registration

The first step in getting started is to signup for a developer account at http://devportal.Shift4Shop.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 Shift4Shop 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 Shift4Shop merchants to subscribe to your application, which authorizes your application to access the Shift4Shop merchant's store data. So, the public key will be used by Shift4Shop merchants to authorize your application. The Shift4Shop merchant will complete this process in Modules -> REST API

Modules

Click link for settings page

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 Shift4Shop 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, Shift4Shop will POST to this URL. The Shift4Shop 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 Shift4Shop, 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 Shift4Shop merchant, and they will not be able to subscribe to your application.

Authentication

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: Shift4Shop merchant's Secure URL.
  • PrivateKey: Your application's private key.
  • Token: The Shift4Shop 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.
<?php
$host = 'https://apirest.3dcart.com';
$version = 1;
$service = 'Customers';
$secureUrl = 'merchant-store.3dcartstsores.com';   // Secure URL is set in Settings->General->StoreSettings
$privateKey = '12121212121212121212121212121212'; // Private key is obtained when registering your app at http://devportal.3dcart.com
$token = '34343434343434343434343434343434';      // The token is generated when a customer authorizes your app
// initialize cURL session
$ch = curl_init($host . '/3dCartWebAPI/v' . $version . '/' . $service);
// set headers
$httpHeader = array(
		'Content-Type: application/json;charset=UTF-8',
		'Accept: application/json',
		'SecureUrl: ' . $secureUrl,
		'PrivateKey: ' . $privateKey,
		'Token: ' . $token,
);
curl_setopt($ch, CURLOPT_HTTPHEADER, $httpHeader);
// [ ... addtional cURL options as needed ... ]
$response = curl_exec($ch);
if ($response === false) {
	$response = curl_error($ch);
}
curl_close($ch);
not yet available
not yet available

OAuth

To use the OAuth authorization protocol, your application would need to use an OAuth client you develop.

Step 1: Go to this URL with the necessary parameters in order to get the authorization code needed for the first step:

https://apirest.3dcart.com/oauth/authorize?client_id={publicKey}&redirect_uri={redirectUri}&state={text}&response_type=code&store_url=[optional]

When Store URL is not specified, a page will be shown to enter the Shift4Shop Store URL. If a Store URL is specified, you would be redirected straight to that store to authorize the application.

You should receive an authorization code and the same state value you sent previously. Validate it in order to be sure the request you are receiving is a response for your initial request.

Once that is done, you will then need to do a POST with that authorization code to retrieve the token.

Step 2: Need to do a post to this URL and pass these parameters:
POST https://apirest.3dcart.com/oauth/token
Content type -> "application/x-www-form-urlencoded”

Parameters:
Code={authorization code you receive in the first request }
client_id={public key}
client_secret={secret key}
grant_type=authorization_code

The response will be a Json object with the access token you need for the API calls.

Versioning

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 Shift4Shop API requires the version to be included as one of the URL parameters (e.g. '/3dCartWebAPI/v1/Customers').

Sample Authentication
Please click here to download the C# Rest API Client project from GitHub.
<?php
$host = 'https://apirest.3dcart.com';
$version = 1;                             // API version
$service = 'Customers';                       // API service
$secureUrl = 'your-store.3dcartstsores.com';   // Secure URL is set in Settings->General->StoreSettings
$appKey = '12121212121212121212121212121212'; // Private key is obtained when registering your app at http://devportal.3dcart.com
$token = '34343434343434343434343434343434';  // The token is generated when a customer authorizes your app
// initialize cURL session
$url = $host . '/3dCartWebAPI/v' . $version '/' . $service; // Output: https://apirest.3dcart.com/3dCartWebAPI/v1/Customers
$ch = curl_init($url);
not yet available
not yet available

Response Messages:

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 response 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 occurred. 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

The Shift4Shop 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 Shift4Shop sample client(s) were developed with this in mind, and can be used to demonstrate usage of OData queries with the Shift4Shop RestAPI.


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

Rate Limits (throttling)

Requests to the Shift4Shop 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

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).


API
Description
Get a specific RMA
Gets the items from a specific RMA

Customer Groups

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).


API
Description
Get all CustomerGroups
Adds a new customer group to the system
This method is used to update a single customer group in the database. The {id} parameter specifies which customer group to update.
This method updates a collection of customer groups in the database. No URL parameters should be included.
Deletes a customer group in the system

Gift Registries

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).


API
Description
Get all GiftRegistries
Gets the items from a specific Gift Registry

Customers

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).


API
Description
Get all Customers
Get Customers from a Customer Group
Adds a new customer to the system
This method is used to update a single customer record in the database. The {id} parameter specifies which customer record to update.
This method is used to update multiple customers in the system. No URL parameters should be included
Deletes a Customer in the system

Distributors

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).


API
Description
Get all Distributors
Adds a new distributor to the system
This method is used to update a single distributor record in the database. The {distributorid} parameter specifies which distributor to update.
This method is used to update multiple distributor records in the database. No {distributorid} parameters should be included.
Deletes a Distributor in the system

Category

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).


API
Description
Get all Categories
Get the options from a specific Category
Adds a new category to the system
Adds a new OptionSet to the system
This method is used to update a single category record in the database. The {categoryid} parameter specifies which category to update.
This method is used to update multiple category records in the database. No {categoryid} parameters should be included.
Updates a collection of options from a specific Category
Updates specific options from a specific Category
Deletes a Category in the system

Products

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).


API
Description
Get all products
Get all products from a specific distributor
Get all products from a specific manufacturer
Get all products from a specific category
Get all products (SKUInfo section only)
Get all products (SKUInfo section only)
Get the options from a specific Product
Get the categories from a specific Product
Get the distributors from a specific Product
Get the images from a specific Product
Get the features from a specific Product
Get the related products from a specific Product
Get the upselling products from a specific Product
Get the discounts from a specific Product
Get the serials from a specific Product
Get the advanced options from a specific Product
Get the EProducts from a specific Product
Adds a new product to the system
Adds a new image to the system
Adds a new feature to the system
Adds a new related product to the system
Adds a new upselling item to the system
Adds a new discount to the system
Adds a new serial to the system
Adds a new eproduct to the system
Adds a new OptionSet to the system
This method is used to update a single product record in the database. The {catalogid} parameter specifies which product record to update.
This method is used to update multiple products in the database. No URL parameters should be included.
Updates a collection of images from a specific Product
Updates a specific image from a specific Product
Updates a collection of features from a specific Product
Updates a specific feature from a specific Product
Updates a collection of related products from a specific Product
Updates a specific related product from a specific Product
Updates a collection of upselling items from a specific Product
Updates a specific Upselling Item from a specific Product
Updates a collection of discounts from a specific Product
Updates a specific discount from a specific Product
Updates a collection of serials from a specific Product
Updates a specific serial from a specific Product
Updates a collection of eproducts from a specific Product
Updates a specific eproduct from a specific Product
Updates a collection of options from a specific Product
Updates specific options from a specific Product
Updates a collection of advanced options from a specific Product
Updates specific advanced options from a specific Product
Deletes a product in the system

Manufacturer

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).


API
Description
Get all Manufacturers
Adds a new manufacturer to the system
This method is used to update a single manufacturer record in the database. The {manufacturerid} parameter specifies which manufacturer record to update.
This method is used to update multiple manufacturers in the database. No URL parameters should be included.
Deletes a Manufacturer in the system

Orders

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).


API
Description
Gets the shipments from a specific Order
Gets the items from a specific Order
Gets the transactions from a specific Order
Gets the questions from a specific Order
Adds a new order to the system
Adds a new shipment on the order
Adds a new item on the order
Adds a new transaction on the order
Adds a new question on the order
This method is used to update a single order record in the database. The {orderid} parameter specifies which order record to update.
This method is used to update multiple orders in the database. No URL parameters should be included.
Updates a collection of shipments from a specific Order
Updates a specific shipment from a specific Order
Updates a collection of items from a specific Order
Updates a specific item from a specific Product
Updates a collection of transactions from a specific Order
Updates a specific transaction from a specific Product
Updates a collection of questions from a specific Order
Updates a specific question from a specific Product