Build an AppIntroduction
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.
Getting Started
ServicesRegistration
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
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.
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').
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).
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).
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).
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).
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).
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).
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).
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).
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).