Getting Started with ShipEngine

API Resources

All ShipEngine URLs listed in this documentation are relative to https://api.shipengine.com/. For example, the /v1/addresses/validate resource is reachable at https://api.shipengine.com/v1/addresses/validate.

HTTPS Requirements

ShipEngine requires HTTPS (as opposed to plain HTTP) for all requests. We support TLS 1.1 or higher.

info

Deprecated security protocols

ShipEngine does not support older security protocols such as TLS 1.0 or any version of SSL. These protocols have been deprecated by the IETF due to security vulnerabilities.

Authentication

All requests to ShipEngine must include an API key in order to be authenticated. Any number of API keys can be generated within the ShipEngine admin interface and are unique to your account. Your API keys give full access to ShipEngine's functionality and therefore should be guarded in the same way you would guard a password or other application credentials. Once you have generated an API key you simply add it to your request as an HTTP header named the API-Key.

tip

Find your ShipEngine API keys in the Dashboard

https://app.shipengine.com/#/portal/apimanagement

Requests

The ShipEngine API is based on REST principles. All requests to ShipEngine are required to be secure and transmitted over HTTPS. Additionally, ShipEngine uses appropriate HTTP verbs for each action:

HTTP Verb Description
GET Used for retrieving resources.
POST Used for creating resources.
PUT Used for changing/replacing resources or collections.
DELETE Used for deleting resources.
PATCH Used for posting partial resources, such as adding funds to insurance.

Rate Limiting

By default, your account is limited to 100 requests per minute to ShipEngine. Please contact [email protected] if you need higher throughput. After 100 requests in a given minute, all responses will return with an HTTP 429 status code. When a request fails due to rate limit restrictions the response will contain a 'Retry-After' header with the number of seconds to wait until your next request can be made.

Pagination

Some requests such as Query Shipments, Query Labels, and Query Batches, as well as List Batch Errors are paginated. We paginate to not overwhelm any single endpoint's response to the consumer.

In a paginated requestion, additional properties are added to the response; including pagination totals, current state of the response, and URLs for first, last, previous and next.

{
  "total": 100,
  "page": 1,
  "pages":4,
  "links": {
    "first": {
      "href": "https://api.shipengine.com/v1/shipments?tag=Disney_Letters&page=1&page_size=25"
    },
    "last": {
      "href": "https://api.shipengine.com/v1/shipments?tag=Disney_Letters&page=4&page_size=25"
    },
    "prev": {},
    "next": {
      "href": "https://api.shipengine.com/v1/shipments?tag=Disney_Letters&page=2&page_size=25"
    }
  }
}

Response Status Codes

ShipEngine will always respond with a 200 HTTP response for a successful request. This varies from the REST standard which will respond with 201 for created, 202 for accepted, etc.

Error Details

When using ShipEngine we try to be concise with our errors. We validate every request to make sure it complies with our rules for models.

There are some requests we are less strict with (Creating a Shipment for example). You may not receive a validation warning here, but when you try to create a label with UPS you might receive an error explaining that you need to have a valid ship_to.phone. The reasoning behind being looser with some validations is to not restrict how you can use ShipEngine.

Additionally, some carriers (like UPS) have specific requirements for phone number format that USPS doesn't have at all.

HTTP Status Code Explanation
400 Bad Request There's an error with your request, read through the messages to see what's wrong.
404 Not Found The resource at the endpoint you requested is not found. For example, v1/shipments/se-123 is valid, but se-123 may not exist or doesn't belong to you.
405 Not Allowed The resource being requested does not accept the HTTP verb requested.
500 Internal Server Error We obviously strive to never have this error occur, please check the detail of the error and see if there's an appropriate action. Otherwise, the error is logged and will be evaluated. Don't hesitate to contact support if this arises.