ShipStation API V1 Requirements

Info Please note that an integration with ShipStation API V1 will not allow you to use your own MarketplaceID that could eventually be branded with your company's logo.

Endpoints

To view specific V1 endpoint information, find the topic you are working with in the left side navigation (for example, Carriers > List Packages), then look within the topic for the example endpoint, request, and response. 

Use https://ssapi.shipstation.com/ as the Host URL for your ShipStation API V1 Server and Base URL that you will put in Postman or your preferred platform.

Authentication

ShipStation API V1 uses Basic HTTP authentication. Use your ShipStation API Key as the username and API Secret as the password. You can find your API Key as the username and API Secret under Settings at https://ss.shipstation.com/#/settings/api.

The Authorization header is constructed as follows:

  • Username (API KEY) and password (API Secret) are combined into a string "username:password"
  • The resulting string is then encoded using the RFC2045-MIME variant of Base64, except not limited to 76 char/line
  • The authorization method and a space i.e. "Basic " is then put before the encoded string.

For example, if the API KEY given is 'ShipStation' and the API Secret is 'Rocks' then the header is formed as follows:

  • Authorization: Basic U2hpcFN0YXRpb246Um9ja3M=

API Rate Limits

In an effort to ensure consistent application performance and increased scalability, we have implemented rate limiting on ShipStation API V1. Your integration will need to be able to handle HTTP rate limiting status messages as defined below:

Response Headers

All responses will include headers with status information about rate limiting.

  1. X-Rate-Limit-Limit: the maximum number of requests per minute to the endpoint
  2. X-Rate-Limit-Remaining: the available requests remaining in the current window
  3. X-Rate-Limit-Reset: the number of seconds remaining until the next window begins

Hitting the Limit

If your application hits the rate limit, an HTTP 429 will be returned with this body:

{
    "message": "Too Many Requests"
}

And these headers, assuming it is 40 seconds into the current window:

{
    "X-Rate-Limit-Limit": 40,
    "X-Rate-Limit-Remaining": 0,
    "X-Rate-Limit-Reset": 20
}

When the limit is reached, your application should stop making requests until X-Rate-Limit-Reset seconds have elapsed. The current Rate limit for each set of the API Key and Secret is 40 requests per minute.

If you have any issues with the API, please email us at [email protected]

Server Responses

Status Code Description
200 OK - The request was successful (some API calls may return 201 instead).
201 Created - The request was successful and a resource was created.
204 No Content - The request was successful but there is no representation to return (that is, the response is empty).
400 Bad Request - The request could not be understood or was missing required parameters.
401 Unauthorized - Authentication failed or user does not have permissions for the requested operation.
403 Forbidden - Access denied.
404 Not Found - Resource was not found.
405 Method Not Allowed - Requested method is not supported for the specified resource.
429 Too Many Requests - Exceeded ShipStation API limits. When the limit is reached, your application should stop making requests until X-Rate-Limit-Reset seconds have elapsed.
500 Internal Server Error - ShipStation has encountered an error.

DateTime Format and Time Zone

ShipStation API V1 uses the ISO 8601 combined format for DateTime stamps being submitted to and returned from the API. Please be sure to submit all DateTime values as follows:

yyyy-mm-dd hh:mm:ss (24 hour notation). Example - 2016-11-29 23:59:59

The time zone represented in all responses is PST/PDT. Similarly, ShipStation asks that you make all time zone conversions and submit any DateTime requests in PST/PDT.