Sunrise Wholesale Merchandise - REST API Reference

Using the API

The Sunrise Wholesale Merchandise application programming interface (API) consists of required and optional fields that are submitted via standard HTTP REST requests. The API requires an API-Key and User ID to access the endpoints. You must have an active Sunrise Wholesale account to obtain an API-Key.

Implementing and interfacing with the API requires knowledge of REST API protocols and development experience. This documentation assumes you have knowledge with API and REST integration.

Obtaining an API Key

The API requires an API-Key and User ID to access the endpoints. You can obtain an API-Key from within your active Sunrise Wholesale account. To fetch your API Key:

  1. Log into your Sunrise Wholesale account
  2. Click on the Account icon in the main menu
  3. Click on "Request an API Key Now" on the Account page
  4. You must save a payment method with your account to use the API
  5. The API Key is now visible on your Account page.
A unique key will be assigned to your customer account.

Authorizing Your API Calls

After obtaining an API Key, you can make authenticated requests to the REST API by passing your API Key and User ID within the HTTP header request of your calls. The HTTP header of every REST request must contain the following fields:

Replace the values with the Key and User ID from your account (NOTE: the braces are not required) and include them in your header request.

Transaction Endpoint

The base URL for all API transactions:

All API transactions will build upon this base URL. You MUST use HTTPS for all calls. Non secure calls will return a failure. A complete transaction URL will contain additional parameters to create the final request. The additional parameters will define the API version and object method. For example a properly formatted URL will have the following parameters:

The {version} and {object method} are described below.

Rate Limiting

To prevent abuse, it's standard practice to add rate limiting to the API access. The Sunrise Wholesale API will allow for one (1) call every 2 seconds before returning a 429 error. As long as your calls are at least 2 seconds apart you will not encounter any interruption. Always check the response code to make sure your requests are getting fulfilled properly. A rate limit error will return the following JSON response:

  "error": {
    "status": "Rate Limit Reached",
    "X-Rate-Limit-Reset": 1

The "X-Rate-Limit-Reset" parameter returns the number of seconds left before a new request can occur.

API Versions

The API version enables us to evolve the API features while maintaining backward compatibility. New API versions will add functionality without affecting previous versions. All features and objects available to a specific API version is outlined in the documentation below. If you are creating a new application, you should use the latest version available.

Version URL Parameter Release Date
1 /v1/ Jan 1, 2016

API Objects

The API objects direct the transactions to the appropriate systems details. The object is added to the URL (object method) and features the methods available to each respective version. Use the table below to see the available calls for each object. Click on the version to see the calls available for each object.

Object Name Details URL Parameter Version (Click on a version to get details)
Products Product information on individual items in the SWM inventory. /products/ v1
Tracking Tracking and carrier details on any order in your account. /tracking/ v1
Orders Details on individual orders from your account. /orders/ v1
Click on a version for any Object above to obtain details on that endpoint

Transaction Responses

The API system will return a status code and status text for each transaction. The response will provide a status on accepted or declined transactions. The response fields are formatted using standard REST API response values:

2xx Success

Status codes indicate successfully received, understood, and accepted calls.

4xx Error

Status codes indicate an error has occurred with the request. A status message with further details is returned.

5xx Success

Status codes indicate a server error and the system is incapable of performing the request.

Terms and Conditions

In order to use the SWM API, you will be prompted to "agree" with the terms and conditions. You will be prompted with a checkbox upon signing-up for an API Key. You will be bound by the following conditions if you choose to implement and use the SWM API system:

You cannot obtain an API Key without agreeing to these terms. Your API information is in the "Account" section of your Sunrise member account.

© Sunrise Wholesale Merchandise