ShipStation API Requirements

Info Please note that an API integration will not allow you to use your own MarketplaceID that could eventually be branded with your company's logo (see the Custom Store Integration above for that functionality).

Endpoints

To view specific API endpoint information, use the side navigation within our API documentation. Find the topic you are working with (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 Server and Base URL that you will put in Postman or your preferred API platform.

Authentication

The ShipStation API 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 the ShipStation API. 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 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 API responses is PST/PDT. Similarly, ShipStation asks that you make all time zone conversions and submit any DateTime requests in PST/PDT.