ShipEngine logo
Documentation Powered by ReDoc

ShipEngine API (1.1.202411131511)

Download OpenAPI specification:Download

ShipEngine Sales & Support: sales@shipengine.com URL: https://www.shipengine.com/contact/ Terms of Service

ShipEngine's easy-to-use REST API lets you manage all of your shipping needs without worrying about the complexities of different carrier APIs and protocols. We handle all the heavy lifting so you can focus on providing a first-class shipping experience for your customers at the best possible prices.

Each of ShipEngine's features can be used by itself or in conjunction with each other to build powerful shipping functionality into your application or service.

ShipEngine's documentation is designed to help you start shipping as quickly as possible. With easy-to-follow tutorials, detailed reference docs, and ready-made recipes for common use cases, you'll see real results in no time at all.

Getting Started

If you're new to REST APIs then be sure to read our introduction to REST to understand the basics. Learn how to authenticate yourself to ShipEngine, and then use our sandbox environment to kick the tires and get familiar with our API. If you run into any problems, then be sure to check the error handling guide for tips.

Here are some step-by-step tutorials to get you started:

Shipping Labels for Every Major Carrier

ShipEngine makes it easy to create shipping labels for any carrier and download them in a variety of file formats. You can even customize labels with your own messages and images.

Real-Time Package Tracking

With ShipEngine you can get the current status of a package or subscribe to real-time tracking updates via webhooks. You can also create custimized tracking pages with your own branding so your customers will always know where their package is.

Compare Shipping Costs Across Carriers

Make sure you ship as cost-effectively as possible by comparing rates across carriers using the ShipEngine Rates API. Or if you don't know the full shipment details yet, then you can get rate estimates with limited address info.

Worldwide Address Validation

ShipEngine supports address validation for virtually every country on Earth, including the United States, Canada, Great Britain, Australia, Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160 others.

Authentication

api_key

To authenticate yourself to ShipEngine, you need to include an API-Key header in each API call. If you don't include a key when making an API request, or if you use an incorrect or expired key, then ShipEngine will respond with a 401 Unauthorized error.

Learn more about API keys in our authentication guide.

Security Scheme Type API Key
Header parameter name: API-Key

Account

For additional information about the ShipEngine account.

List Account Settings

List all account settings for the ShipEngine account

Authorizations:
api_key

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/account/settings
https://api.shipengine.com/v1/account/settings

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "default_label_layout": "4x6"
}

List Account Images

List all account images for the ShipEngine account

Authorizations:
api_key

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/account/settings/images
https://api.shipengine.com/v1/account/settings/images

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "images":
    [
    ],
  • "total": 2750,
  • "page": 1,
  • "pages": 4,
  • "links":
    {}
}

Create an Account Image

Create an Account Image

Authorizations:
api_key
Request Body schema: application/json
name
required
string [ 1 .. 50 ] characters

A human readable name for the image.

is_default
boolean

Indicates whether this image is set as default.

image_content_type
required
string
Enum: "image/png" "image/jpeg"

The file type of the image.

image_data
required
string

A base64 encoded string representation of the image.

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/account/settings/images
https://api.shipengine.com/v1/account/settings/images

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "My logo",
  • "is_default": false,
  • "image_content_type": "image/png",
  • "image_data": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg=="
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
  • "name": "My logo",
  • "is_default": false,
  • "image_content_type": "image/png",
  • "image_data": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg==",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "modified_at": "2018-09-23T15:00:00.000Z"
}

Get Account Image By ID

Retrieve information for an account image.

Authorizations:
api_key
path Parameters
label_image_id
required
string (image_id) >= 4 characters
Example: img_DtBXupDBxREpHnwEXhTfgK

Label Image Id

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/account/settings/images/{label_image_id}
https://api.shipengine.com/v1/account/settings/images/{label_image_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
  • "name": "My logo",
  • "is_default": false,
  • "image_content_type": "image/png",
  • "image_data": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg==",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "modified_at": "2018-09-23T15:00:00.000Z"
}

Update Account Image By ID

Update information for an account image.

Authorizations:
api_key
path Parameters
label_image_id
required
string (image_id) >= 4 characters
Example: img_DtBXupDBxREpHnwEXhTfgK

Label Image Id

Request Body schema: application/json
name
string [ 1 .. 50 ] characters

A human readable name for the image.

is_default
required
boolean

Indicates whether this image is set as default.

image_content_type
string
Enum: "image/png" "image/jpeg"

The file type of the image.

image_data
string

A base64 encoded string representation of the image.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/account/settings/images/{label_image_id}
https://api.shipengine.com/v1/account/settings/images/{label_image_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "My logo",
  • "is_default": false,
  • "image_content_type": "image/png",
  • "image_data": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg=="
}

Response samples

Content type
text/plain
No sample

Delete Account Image By Id

Delete Account Image By Id

Authorizations:
api_key
path Parameters
label_image_id
required
string (image_id) >= 4 characters
Example: img_DtBXupDBxREpHnwEXhTfgK

Label Image Id

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

delete/v1/account/settings/images/{label_image_id}
https://api.shipengine.com/v1/account/settings/images/{label_image_id}

Response samples

Content type
text/plain
No sample

Addresses

No matter your shipping volume, failed deliveries and address change surcharges cut into your bottom line and damage perception with customers. Our address validation services ensure your packages make it to the right place the first time. Learn how to leverage our address validation services here.

ShipEngine supports address validation for virtually every country on Earth, including the United States, Canada, Great Britain, Australia, Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160 others.

Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipEngine cross references multiple databases to validate addresses and identify potential deliverability issues.

Parse an address

The address-recognition API makes it easy for you to extract address data from unstructured text, including the recipient name, line 1, line 2, city, postal code, and more.

Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's address-recognition API helps you extract meaningful, structured data from this unstructured text. The parsed address data is returned in the same structure that's used for other ShipEngine APIs, such as address validation, rate quotes, and shipping labels.

Note: Address recognition is currently supported for the United States, Canada, Australia, New Zealand, the United Kingdom, and Ireland.

Authorizations:
api_key
Request Body schema: application/json

The only required field is text, which is the text to be parsed. You can optionally also provide an address containing already-known values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines.

text
required
string non-empty

The unstructured text that contains address-related entities

address
object

You can optionally provide any already-known address values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines.

Responses

200

Returns the parsed address, as well as a confidence score and a list of all the entities that were recognized in the text.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/addresses/recognize
https://api.shipengine.com/v1/addresses/recognize

Request samples

Content type
application/json
Example
Text only

This is the simplest way to call the address-recognition API. Just pass the text to be parsed and nothing else.

Copy
 Expand all Collapse all
{
  • "text": "Margie McMiller at 3800 North Lamar suite 200 in austin, tx. The zip code there is 78652."
}

Response samples

Content type
application/json
Example
text_only

This response shows that the address-recognition API was able to recognize all the address entities in the text. Notice that the country_code is not populated and the address_residential_indicator is "unknown", since neither of these fields was included in the text.

Copy
 Expand all Collapse all
{
  • "score": 0.9122137426845613,
  • "address":
    {
    },
  • "entities":
    [
    ]
}

Validate An Address

Address validation ensures accurate addresses and can lead to reduced shipping costs by preventing address correction surcharges. ShipEngine cross references multiple databases to validate addresses and identify potential deliverability issues.

Authorizations:
api_key
Request Body schema: application/json
Array
name
string non-empty

The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.

phone
string non-empty

The phone number of a contact person at this address. The format of this phone number varies depending on the country.

email
string Nullable

Email for the address owner.

company_name
string non-empty Nullable

If this is a business address, then the company name should be specified here.

address_line1
required
string non-empty

The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.

address_line2
string non-empty Nullable

The second line of the street address. For some addresses, this line may not be needed.

address_line3
string non-empty Nullable

The third line of the street address. For some addresses, this line may not be needed.

city_locality
required
string non-empty

The name of the city or locality

state_province
required
string non-empty

The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.

postal_code
string non-empty

postal code

country_code
required
string 2 characters

The two-letter ISO 3166-1 country code

address_residential_indicator
string
Default: "unknown"
Enum: "unknown" "yes" "no"

Indicates whether this is a residential address.

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/addresses/validate
https://api.shipengine.com/v1/addresses/validate

Request samples

Content type
application/json

A call that returns a status of verified.

Copy
 Expand all Collapse all
[
  • {
    }
]

Response samples

Content type
application/json
Example
All Known Fields

A response for a verified status call.

Copy
 Expand all Collapse all
[
  • {
    }
]

Batches

batches

List Batches

List Batches associated with your Shipengine account

Authorizations:
api_key
query Parameters
status
string (batch_status)
Enum: "open" "queued" "processing" "completed" "completed_with_errors" "archived" "notifying" "invalid"

The possible batch status values

page
integer <int32> >= 1
Default: 1
Example: page=2

Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.

page_size
integer <int32> >= 1
Default: 25
Example: page_size=50

The number of results to return per response.

sort_dir
string
Default: "desc"
Enum: "asc" "desc"

Controls the sort order of the query.

batch_number
string

Batch Number

sort_by
string (batches_sort_by)
Enum: "ship_date" "processed_at" "created_at"

The possible batches sort by values

Responses

200

The request was a success.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/batches
https://api.shipengine.com/v1/batches

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Create A Batch

Create a Batch

Authorizations:
api_key
Request Body schema: application/json
One of
  • create_batch_request_body
  • create_and_process_batch_request_body
external_batch_id
string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

A string that uniquely identifies the external batch

batch_notes
string non-empty

Add custom messages for a particular batch

shipment_ids
Array of strings

Array of shipment IDs used in the batch

rate_ids
Array of strings

Array of rate IDs used in the batch

Responses

200

The requested object creation was a success.

207

The request was a partial success. It contains results, as well as processing errors.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/batches
https://api.shipengine.com/v1/batches

Request samples

Content type
application/json
Example
create_batch_request_body
Copy
 Expand all Collapse all
{
  • "external_batch_id": "se-28529731",
  • "batch_notes": "This is my batch",
  • "shipment_ids":
    [
    ],
  • "rate_ids":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Get Batch By External ID

Get Batch By External ID

Authorizations:
api_key
path Parameters
external_batch_id
required
string
Example: 13553d7f-3c87-4771-bae1-c49bacef11cb

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/batches/external_batch_id/{external_batch_id}
https://api.shipengine.com/v1/batches/external_batch_id/{external_batch_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Delete Batch By Id

Delete Batch By Id

Authorizations:
api_key
path Parameters
batch_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Batch ID

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

delete/v1/batches/{batch_id}
https://api.shipengine.com/v1/batches/{batch_id}

Response samples

Content type
text/plain
No sample

Get Batch By ID

Get Batch By ID

Authorizations:
api_key
path Parameters
batch_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Batch ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/batches/{batch_id}
https://api.shipengine.com/v1/batches/{batch_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Update Batch By Id

Update Batch By Id

Authorizations:
api_key
path Parameters
batch_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Batch ID

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/batches/{batch_id}
https://api.shipengine.com/v1/batches/{batch_id}

Response samples

Content type
text/plain
No sample

Add to a Batch

Add a Shipment or Rate to a Batch

Authorizations:
api_key
path Parameters
batch_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Batch ID

Request Body schema: application/json
shipment_ids
Array of strings

The Shipment Ids to be modified on the batch

rate_ids
Array of strings

Array of Rate IDs to be modifed on the batch

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/batches/{batch_id}/add
https://api.shipengine.com/v1/batches/{batch_id}/add

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "shipment_ids":
    [
    ],
  • "rate_ids":
    [
    ]
}

Response samples

Content type
text/plain
No sample

Get Batch Errors

Error handling in batches are handled differently than in a single synchronous request. You must retrieve the status of your batch by getting a batch and getting an overview of the statuses or you can list errors directly here below to get detailed information about the errors.

Authorizations:
api_key
path Parameters
batch_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Batch ID

query Parameters
page
integer <int32> >= 1
Default: 1
Example: page=2

Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.

pagesize
integer <int32> >= 1

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/batches/{batch_id}/errors
https://api.shipengine.com/v1/batches/{batch_id}/errors

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Process Batch ID Labels

Process Batch ID Labels

Authorizations:
api_key
path Parameters
batch_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Batch ID

Request Body schema: application/json
ship_date
string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2})$

The Ship date the batch is being processed for

label_layout
string
Default: "4x6"
Enum: "4x6" "letter" "A4" "A6"

The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.

label_format
string
Default: "pdf"
Enum: "pdf" "png" "zpl"

The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.

Label Format Supported Carriers
pdf All carriers
png fedex
stamps_com
ups
usps
zpl access_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
display_scheme
string
Default: "label"
Enum: "label" "qr_code" "label_and_qr_code" "paperless" "label_and_paperless"

The display format that the label should be shown in.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/batches/{batch_id}/process/labels
https://api.shipengine.com/v1/batches/{batch_id}/process/labels

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ship_date": "2018-09-23T15:00:00.000Z",
  • "label_layout": "4x6",
  • "label_format": "pdf",
  • "display_scheme": "label"
}

Response samples

Content type
text/plain
No sample

Remove From Batch

Remove a shipment or rate from a batch

Authorizations:
api_key
path Parameters
batch_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Batch ID

Request Body schema: application/json
shipment_ids
Array of strings

The Shipment Ids to be modified on the batch

rate_ids
Array of strings

Array of Rate IDs to be modifed on the batch

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/batches/{batch_id}/remove
https://api.shipengine.com/v1/batches/{batch_id}/remove

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "shipment_ids":
    [
    ],
  • "rate_ids":
    [
    ]
}

Response samples

Content type
text/plain
No sample

Carrier Accounts

A carrier account is a connection to a shipping carrier that allows you to create labels, track packages, and more. You can connect your own carrier accounts to ShipEngine, or use one of our built-in carrier accounts. Learn more about carrier accounts here.

Connect a carrier account

Connect a carrier account

Authorizations:
api_key
path Parameters
carrier_name
required
string (carrier_name)
Enum: "access_worldwide" "amazon_buy_shipping" "amazon_shipping_uk" "apc" "asendia" "australia_post" "canada_post" "dhl_ecommerce" "dhl_express" "dhl_express_au" "dhl_express_ca" "dhl_express_uk" "dpd" "endicia" "fedex" "fedex_uk" "firstmile" "imex" "newgistics" "ontrac" "purolator_canada" "royal_mail" "rr_donnelley" "seko" "sendle" "stamps_com" "ups" "lasership"
Example: dhl_express

The carrier name, such as stamps_com, ups, fedex, or dhl_express.

Request Body schema: application/json
One of
  • connect_access_worldwide_request_body
  • connect_amazon_buy_shipping_request_body
  • connect_amazon_shipping_uk
  • connect_apc_request_body
  • connect_asendia_request_body
  • connect_australia_post_request_body
  • connect_canada_post_request_body
  • connect_dhl_ecommerce_request_body
  • connect_dhl_express_request_body
  • connect_dhl_express_au_request_body
  • connect_dhl_express_ca_request_body
  • connect_dhl_express_uk_request_body
  • connect_dpd_request_body
  • connect_endicia_request_body
  • connect_fedex_request_body
  • connect_fedex_uk_request_body
  • connect_firstmile_request_body
  • connect_imex_request_body
  • connect_lasership_request_body
  • connect_newgistics_request_body
  • connect_ontrac_request_body
  • connect_purolator_request_body
  • connect_royal_mail_request_body
  • connect_rr_donnelley_request_body
  • connect_seko_request_body
  • connect_sendle_request_body
  • connect_stamps_request_body
  • connect_ups_request_body
nickname
required
string non-empty

The nickname associated with the carrier connection

username
required
string non-empty

Access Worldwide Username

password
required
string non-empty

Access Worldwide Password

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/connections/carriers/{carrier_name}
https://api.shipengine.com/v1/connections/carriers/{carrier_name}

Request samples

Content type
application/json
Example
connect_access_worldwide_request_body
Copy
 Expand all Collapse all
{
  • "nickname": "Stamps.com",
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "carrier_id": "se-28529731"
}

Disconnect a carrier

Disconnect a carrier

Authorizations:
api_key
path Parameters
carrier_name
required
string (carrier_name)
Enum: "access_worldwide" "amazon_buy_shipping" "amazon_shipping_uk" "apc" "asendia" "australia_post" "canada_post" "dhl_ecommerce" "dhl_express" "dhl_express_au" "dhl_express_ca" "dhl_express_uk" "dpd" "endicia" "fedex" "fedex_uk" "firstmile" "imex" "newgistics" "ontrac" "purolator_canada" "royal_mail" "rr_donnelley" "seko" "sendle" "stamps_com" "ups" "lasership"
Example: dhl_express

The carrier name, such as stamps_com, ups, fedex, or dhl_express.

carrier_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Carrier ID

Responses

204

The request was successful.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

delete/v1/connections/carriers/{carrier_name}/{carrier_id}
https://api.shipengine.com/v1/connections/carriers/{carrier_name}/{carrier_id}

Response samples

Content type
text/plain
No sample

Get carrier settings

Get carrier settings

Authorizations:
api_key
path Parameters
carrier_name
required
string (carrier_name_with_settings)
Enum: "dhl_express" "fedex" "newgistics" "ups"
Example: dhl_express

The carrier name, such as ups, fedex, or dhl_express.

carrier_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Carrier ID

Responses

200

The request was a success.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/connections/carriers/{carrier_name}/{carrier_id}/settings
https://api.shipengine.com/v1/connections/carriers/{carrier_name}/{carrier_id}/settings

Response samples

Content type
application/json
Example
dhl_express_settings_response_body
Copy
 Expand all Collapse all
{
  • "nickname": "string",
  • "should_hide_account_number_on_archive_doc": true,
  • "is_primary_account": true
}

Update carrier settings

Update carrier settings

Authorizations:
api_key
path Parameters
carrier_name
required
string (carrier_name_with_settings)
Enum: "dhl_express" "fedex" "newgistics" "ups"
Example: dhl_express

The carrier name, such as ups, fedex, or dhl_express.

carrier_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Carrier ID

Request Body schema: application/json
One of
  • update_dhl_express_settings_request_body
  • update_fedex_settings_request_body
  • update_newgistics_settings_request_body
  • update_ups_settings_request_body
  • update_amazon_buy_shipping_request_body
nickname
string non-empty

Account nickname

should_hide_account_number_on_archive_doc
boolean

Indicates if the account number should be hidden on the archive documentation

is_primary_account
boolean

Indicates if this is primary account

Responses

204

The request was successful.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/connections/carriers/{carrier_name}/{carrier_id}/settings
https://api.shipengine.com/v1/connections/carriers/{carrier_name}/{carrier_id}/settings

Request samples

Content type
application/json
Example
update_dhl_express_settings_request_body
Copy
 Expand all Collapse all
{
  • "nickname": "string",
  • "should_hide_account_number_on_archive_doc": true,
  • "is_primary_account": true
}

Response samples

Content type
text/plain
No sample

Carriers

carriers

List Carriers

List all carriers that have been added to this account

Authorizations:
api_key

Responses

200

The request was a success.

207

The request was a partial success. It contains results, as well as errors.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/carriers
https://api.shipengine.com/v1/carriers

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "carriers":
    [
    ],
  • "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
  • "errors":
    [
    ]
}

Get Carrier By ID

Retrive carrier info by ID

Authorizations:
api_key
path Parameters
carrier_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Carrier ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/carriers/{carrier_id}
https://api.shipengine.com/v1/carriers/{carrier_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "carrier_id": "se-28529731",
  • "carrier_code": "dhl_express",
  • "account_number": "account_570827",
  • "requires_funded_amount": true,
  • "balance": 3799.52,
  • "nickname": "ShipEngine Account - Stamps.com",
  • "friendly_name": "Stamps.com",
  • "funding_source_id": "se-28529731",
  • "primary": true,
  • "has_multi_package_supporting_services": true,
  • "supports_label_messages": true,
  • "disabled_by_billing_plan": true,
  • "services":
    [
    ],
  • "packages":
    [
    ],
  • "options":
    [
    ]
}

Disconnect Carrier by ID

Disconnect a Carrier of the given ID from the account

Authorizations:
api_key
path Parameters
carrier_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Carrier ID

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

delete/v1/carriers/{carrier_id}
https://api.shipengine.com/v1/carriers/{carrier_id}

Response samples

Content type
text/plain
No sample

Add Funds To Carrier

Add Funds To A Carrier

Authorizations:
api_key
path Parameters
carrier_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Carrier ID

Request Body schema: application/json
currency
required
string

The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html

amount
required
number >= 0

The monetary amount, in the specified currency.

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/carriers/{carrier_id}/add_funds
https://api.shipengine.com/v1/carriers/{carrier_id}/add_funds

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "currency": "string",
  • "amount": 0
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "balance":
    {
    }
}

Get Carrier Options

Get a list of the options available for the carrier

Authorizations:
api_key
path Parameters
carrier_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Carrier ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/carriers/{carrier_id}/options
https://api.shipengine.com/v1/carriers/{carrier_id}/options

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "options":
    [
    ]
}

List Carrier Package Types

List the package types associated with the carrier

Authorizations:
api_key
path Parameters
carrier_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Carrier ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/carriers/{carrier_id}/packages
https://api.shipengine.com/v1/carriers/{carrier_id}/packages

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "packages":
    [
    ]
}

List Carrier Services

List the services associated with the carrier ID

Authorizations:
api_key
path Parameters
carrier_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Carrier ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/carriers/{carrier_id}/services
https://api.shipengine.com/v1/carriers/{carrier_id}/services

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "services":
    [
    ]
}

Downloads

downloads

Download File

Get File

Authorizations:
api_key
path Parameters
subdir
required
string
filename
required
string
dir
required
string
query Parameters
download
string
rotation
integer <int32>

Responses

200

The request was a success

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/downloads/{dir}/{subdir}/{filename}
https://api.shipengine.com/v1/downloads/{dir}/{subdir}/{filename}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
  • "errors":
    [
    ]
}

Insurance

insurance

Disconnect a Shipsurance Account

Disconnect a Shipsurance Account

Authorizations:
api_key

Responses

200

The request was a success

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

delete/v1/connections/insurance/shipsurance
https://api.shipengine.com/v1/connections/insurance/shipsurance

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{ }

Connect a Shipsurance Account

Connect a Shipsurance Account

Authorizations:
api_key
Request Body schema: application/json
email
required
string <email> non-empty

An email address.

policy_id
required
string non-empty

Responses

200

The request was a success

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/connections/insurance/shipsurance
https://api.shipengine.com/v1/connections/insurance/shipsurance

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "email": "john.doe@example.com",
  • "policy_id": "string"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{ }

Add Funds To Insurance

You may need to auto fund your account from time to time. For example, if you don't normally ship items over $100, and may want to add funds to insurance rather than keeping the account funded.

Authorizations:
api_key
Request Body schema: application/json
currency
required
string

The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html

amount
required
number >= 0

The monetary amount, in the specified currency.

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

patch/v1/insurance/shipsurance/add_funds
https://api.shipengine.com/v1/insurance/shipsurance/add_funds

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "currency": "string",
  • "amount": 0
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "currency": "string",
  • "amount": 0
}

Get Insurance Funds Balance

Retrieve the balance of your Shipsurance account.

Authorizations:
api_key

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/insurance/shipsurance/balance
https://api.shipengine.com/v1/insurance/shipsurance/balance

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "currency": "string",
  • "amount": 0
}

Labels

Print shipping labels for any of the top global carriers in minutes—instead of weeks. Simply connect your existing carrier accounts in the API dashboard, and then begin creating labels.

Follow this quick start guide to create your first shipping label with ShipEngine

List labels

This endpoint returns a list of labels that you've created. You can optionally filter the results as well as control their sort order and the number of results returned at a time.

By default, all labels are returned, 25 at a time, starting with the most recently created ones. You can combine multiple filter options to narrow-down the results. For example, if you only want to get your UPS labels for your east coast warehouse you could query by both warehouse_id and carrier_id

Authorizations:
api_key
query Parameters
label_status
string (label_status)
Enum: "processing" "completed" "error" "voided"

Only return labels that are currently in the specified status

service_code
string (service_code) ^[a-z0-9]+(_[a-z0-9-]+)* ?$
Example: service_code=usps_first_class_mail

Only return labels for a specific carrier service

carrier_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: carrier_id=se-28529731

Only return labels for a specific carrier account

tracking_number
string non-empty
Example: tracking_number=9405511899223197428490

Only return labels with a specific tracking number

batch_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: batch_id=se-28529731

Only return labels that were created in a specific batch

rate_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: rate_id=se-28529731

Rate ID

shipment_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: shipment_id=se-28529731

Shipment ID

warehouse_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: warehouse_id=se-28529731

Only return labels that originate from a specific warehouse

created_at_start
string <date-time>
Example: created_at_start=2019-03-12T19:24:13.657Z

Only return labels that were created on or after a specific date/time

created_at_end
string <date-time>
Example: created_at_end=2019-03-12T19:24:13.657Z

Only return labels that were created on or before a specific date/time

page
integer <int32> >= 1
Default: 1
Example: page=2

Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.

page_size
integer <int32> >= 1
Default: 25
Example: page_size=50

The number of results to return per response.

sort_dir
string
Default: "desc"
Enum: "asc" "desc"

Controls the sort order of the query.

sort_by
string
Default: "created_at"
Enum: "modified_at" "created_at"

Controls which field the query is sorted by.

Responses

200

The response includes a labels array containing a page of results (as determined by the page_size query parameter). It also includes other useful information, such as the total number of labels that match the query criteria, the number of pages of results, and the URLs of the first, last, next, and previous pages of results.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/labels
https://api.shipengine.com/v1/labels

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Purchase Label

Purchase and print a label for shipment

Authorizations:
api_key
Request Body schema: application/json
ship_to_service_point_id
string Nullable

A unique identifier for a carrier service point where the shipment will be delivered by the carrier. This will take precedence over a shipment's ship to address.

ship_from_service_point_id
string Nullable

A unique identifier for a carrier drop off point where a merchant plans to deliver packages. This will take precedence over a shipment's ship from address.

shipment
required
object

The shipment information used to generate the label

is_return_label
boolean

Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.

rma_number
string Nullable

An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.

charge_event
string
Enum: "carrier_default" "on_creation" "on_carrier_acceptance"

The label charge event.

outbound_label_id
string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

The label_id of the original (outgoing) label that the return label is for. This associates the two labels together, which is required by some carriers.

test_label
boolean
Deprecated
Default: false

Indicate if this label is being used only for testing purposes. If true, then no charge will be added to your account.

validate_address
string
Default: "validate_and_clean"
Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

label_download_type
string
Default: "url"
Enum: "url" "inline"

There are two different ways to download a label:

Label Download Type Description
url You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if label_download_type is unspecified.
inline You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
label_format
string
Default: "pdf"
Enum: "pdf" "png" "zpl"

The file format that you want the label to be in. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.

display_scheme
string
Default: "label"
Enum: "label" "qr_code" "label_and_qr_code" "paperless" "label_and_paperless"

The display format that the label should be shown in.

label_layout
string
Default: "4x6"
Enum: "4x6" "letter" "A4" "A6"

The layout (size) that you want the label to be in. The label_format determines which sizes are allowed. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.

label_image_id
string >= 4 characters Nullable

The label image resource that was used to create a custom label image.

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/labels
https://api.shipengine.com/v1/labels

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "ship_to_service_point_id": "614940",
  • "ship_from_service_point_id": "614940",
  • "shipment":
    {
    },
  • "is_return_label": true,
  • "rma_number": "string",
  • "charge_event": "carrier_default",
  • "outbound_label_id": "se-28529731",
  • "test_label": false,
  • "validate_address": "no_validation",
  • "label_download_type": "url",
  • "label_format": "pdf",
  • "display_scheme": "label",
  • "label_layout": "4x6",
  • "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Get Label By External Shipment ID

Find a label by using the external shipment id that was used during label creation

Authorizations:
api_key
path Parameters
external_shipment_id
required
string
Example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae
query Parameters
label_download_type
string (label_download_type)
Enum: "url" "inline"
Example: label_download_type=url

There are two different ways to download a label:

Label Download Type Description
url You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if label_download_type is unspecified.
inline You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/labels/external_shipment_id/{external_shipment_id}
https://api.shipengine.com/v1/labels/external_shipment_id/{external_shipment_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Purchase Label with Rate ID

When retrieving rates for shipments using the /rates endpoint, the returned information contains a rate_id property that can be used to generate a label without having to refill in the shipment information repeatedly.

Authorizations:
api_key
path Parameters
rate_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Rate ID

Request Body schema: application/json
custom_field1
string

Optional - Value will be saved in the shipment's advanced_options > custom_field1

custom_field2
string

Optional - Value will be saved in the shipment's advanced_options > custom_field2

custom_field3
string

Optional - Value will be saved in the shipment's advanced_options > custom_field3

validate_address
string
Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

label_layout
string
Default: "4x6"
Enum: "4x6" "letter" "A4" "A6"

The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.

label_format
string
Default: "pdf"
Enum: "pdf" "png" "zpl"

The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.

Label Format Supported Carriers
pdf All carriers
png fedex
stamps_com
ups
usps
zpl access_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
label_download_type
string
Enum: "url" "inline"

There are two different ways to download a label:

Label Download Type Description
url You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if label_download_type is unspecified.
inline You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
display_scheme
string
Default: "label"
Enum: "label" "qr_code" "label_and_qr_code" "paperless" "label_and_paperless"

The display format that the label should be shown in.

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/labels/rates/{rate_id}
https://api.shipengine.com/v1/labels/rates/{rate_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "custom_field1": "string",
  • "custom_field2": "string",
  • "custom_field3": "string",
  • "validate_address": "no_validation",
  • "label_layout": "4x6",
  • "label_format": "pdf",
  • "label_download_type": "url",
  • "display_scheme": "label"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Purchase Label with Shipment ID

Purchase a label using a shipment ID that has already been created with the desired address and package info.

Authorizations:
api_key
path Parameters
shipment_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Shipment ID

Request Body schema: application/json
validate_address
string
Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

label_layout
string
Default: "4x6"
Enum: "4x6" "letter" "A4" "A6"

The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.

label_format
string
Default: "pdf"
Enum: "pdf" "png" "zpl"

The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.

Label Format Supported Carriers
pdf All carriers
png fedex
stamps_com
ups
usps
zpl access_worldwide
apc
asendia
dhl_global_mail
dhl_express
dhl_express_australia
dhl_express_canada
dhl_express_worldwide
dhl_express_uk
dpd
endicia
fedex
fedex_uk
firstmile
imex
newgistics
ontrac
rr_donnelley
stamps_com
ups
usps
label_download_type
string
Enum: "url" "inline"

There are two different ways to download a label:

Label Download Type Description
url You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if label_download_type is unspecified.
inline You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
display_scheme
string
Default: "label"
Enum: "label" "qr_code" "label_and_qr_code" "paperless" "label_and_paperless"

The display format that the label should be shown in.

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/labels/shipment/{shipment_id}
https://api.shipengine.com/v1/labels/shipment/{shipment_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "validate_address": "no_validation",
  • "label_layout": "4x6",
  • "label_format": "pdf",
  • "label_download_type": "url",
  • "display_scheme": "label"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Get Label By ID

Retrieve information for individual labels.

Authorizations:
api_key
path Parameters
label_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Label ID

query Parameters
label_download_type
string (label_download_type)
Enum: "url" "inline"
Example: label_download_type=url

There are two different ways to download a label:

Label Download Type Description
url You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if label_download_type is unspecified.
inline You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/labels/{label_id}
https://api.shipengine.com/v1/labels/{label_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Create a return label

Create a return label

Authorizations:
api_key
path Parameters
label_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Label ID

Request Body schema: application/json
charge_event
string
Enum: "carrier_default" "on_creation" "on_carrier_acceptance"

The label charge event.

label_layout
string
Default: "4x6"
Enum: "4x6" "letter" "A4" "A6"

The layout (size) that you want the label to be in. The label_format determines which sizes are allowed. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.

label_format
string
Default: "pdf"
Enum: "pdf" "png" "zpl"

The file format that you want the label to be in. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.

label_download_type
string
Default: "url"
Enum: "url" "inline"

There are two different ways to download a label:

Label Download Type Description
url You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.

This is the default if label_download_type is unspecified.
inline You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
display_scheme
string
Default: "label"
Enum: "label" "qr_code" "label_and_qr_code" "paperless" "label_and_paperless"

The display format that the label should be shown in.

label_image_id
string >= 4 characters Nullable

The label image resource that was used to create a custom label image.

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/labels/{label_id}/return
https://api.shipengine.com/v1/labels/{label_id}/return

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "charge_event": "carrier_default",
  • "label_layout": "4x6",
  • "label_format": "pdf",
  • "label_download_type": "url",
  • "display_scheme": "label",
  • "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Get Label Tracking Information

Retrieve the label's tracking information

Authorizations:
api_key
path Parameters
label_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Label ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/labels/{label_id}/track
https://api.shipengine.com/v1/labels/{label_id}/track

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "tracking_number": "1Z932R800392060079",
  • "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
  • "status_code": "DE",
  • "status_detail_code": "DELIVERED",
  • "carrier_code": "dhl_express",
  • "carrier_id": 0,
  • "status_description": "Delivered",
  • "status_detail_description": "Your shipment has been delivered.",
  • "carrier_status_code": 1,
  • "carrier_detail_code": "OT",
  • "carrier_status_description": "Your item was delivered in or at the mailbox at 9:10 am on March",
  • "ship_date": "2018-09-23T15:00:00.000Z",
  • "estimated_delivery_date": "2018-09-23T15:00:00.000Z",
  • "actual_delivery_date": "2018-09-23T15:00:00.000Z",
  • "exception_description": "string",
  • "events":
    [
    ]
}

Void a Label By ID

Void a label by ID to get a refund.

Authorizations:
api_key
path Parameters
label_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Label ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/labels/{label_id}/void
https://api.shipengine.com/v1/labels/{label_id}/void

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "approved": false,
  • "message": "Unable to delete FedEx shipment. Unable to retrieve record from database.",
  • "reason_code": "label_not_found_within_void_period"
}

Manifests

manifests

List Manifests

Similar to querying shipments, we allow you to query manifests since there will likely be a large number over a long period of time.

Authorizations:
api_key
query Parameters
warehouse_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: warehouse_id=se-28529731

Warehouse ID

ship_date_start
string <date-time>
Example: ship_date_start=2018-09-23T15:00:00.000Z

ship date start range

ship_date_end
string <date-time>
Example: ship_date_end=2018-09-23T15:00:00.000Z

ship date end range

created_at_start
string <date-time>
Example: created_at_start=2019-03-12T19:24:13.657Z

Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time)

created_at_end
string <date-time>
Example: created_at_end=2019-03-12T19:24:13.657Z

Used to create a filter for when a resource was created, (ex. A shipment that was created before a certain time)

carrier_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: carrier_id=se-28529731

Carrier ID

page
integer <int32> >= 1
Default: 1
Example: page=2

Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.

page_size
integer <int32> >= 1
Default: 25
Example: page_size=50

The number of results to return per response.

label_ids
Array of strings (se_id)
Example: label_ids=se-28529731

Array of label ids

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/manifests
https://api.shipengine.com/v1/manifests

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{}

Create Manifest

Each ShipEngine manifest is created for a specific warehouse, so you'll need to provide the warehouse_id rather than the ship_from address. You can create a warehouse for each location that you want to create manifests for.

Authorizations:
api_key
Request Body schema: application/json
One of
  • create_manifest_by_object_request_body
  • create_manifest_label_ids_request_body
carrier_id
required
string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

A string that uniquely identifies the carrier

excluded_label_ids
Array of strings

The list of label ids to exclude from the manifest

label_ids
Array of strings

The list of label ids to include for the manifest

warehouse_id
required
string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

A string that uniquely identifies the warehouse

ship_date
required
string <date-time> non-empty

The ship date that the shipment will be sent out on

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/manifests
https://api.shipengine.com/v1/manifests

Request samples

Content type
application/json
Example
create_manifest_by_object_request_body
Copy
 Expand all Collapse all
{
  • "carrier_id": "se-28529731",
  • "excluded_label_ids":
    [
    ],
  • "label_ids":
    [
    ],
  • "warehouse_id": "se-28529731",
  • "ship_date": "2018-09-23T15:00:00.000Z"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "manifests":
    [
    ],
  • "manifest_requests":
    [
    ],
  • "manifest_id": "se-28529731",
  • "form_id": "se-28529731",
  • "created_at": "2019-07-12T13:37:39.050Z",
  • "ship_date": "2019-07-12T13:37:39.050Z",
  • "shipments": 100,
  • "warehouse_id": "se-28529731",
  • "submission_id": "9475711899564878915476",
  • "carrier_id": "se-28529731",
  • "manifest_download":
    {},
  • "label_ids":
    [
    ],
  • "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
  • "errors":
    [
    ]
}

Get Manifest By Id

Get Manifest By Id

Authorizations:
api_key
path Parameters
manifest_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

The Manifest Id

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/manifests/{manifest_id}
https://api.shipengine.com/v1/manifests/{manifest_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "manifest_id": "se-28529731",
  • "form_id": "se-28529731",
  • "created_at": "2019-07-12T13:37:39.050Z",
  • "ship_date": "2019-07-12T13:37:39.050Z",
  • "shipments": 100,
  • "label_ids":
    [
    ],
  • "warehouse_id": "se-28529731",
  • "submission_id": "9475711899564878915476",
  • "carrier_id": "se-28529731",
  • "manifest_download":
    {}
}

Get Manifest Request By Id

Get Manifest Request By Id

Authorizations:
api_key
path Parameters
manifest_request_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

The Manifest Request Id

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/manifests/requests/{manifest_request_id}
https://api.shipengine.com/v1/manifests/requests/{manifest_request_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "manifests":
    [
    ],
  • "manifest_requests":
    [
    ],
  • "manifest_id": "se-28529731",
  • "form_id": "se-28529731",
  • "created_at": "2019-07-12T13:37:39.050Z",
  • "ship_date": "2019-07-12T13:37:39.050Z",
  • "shipments": 100,
  • "warehouse_id": "se-28529731",
  • "submission_id": "9475711899564878915476",
  • "carrier_id": "se-28529731",
  • "manifest_download":
    {},
  • "label_ids":
    [
    ],
  • "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
  • "errors":
    [
    ]
}

Package Pickups

Scheduled package pickups

List Scheduled Pickups

List all pickups that have been scheduled for this carrier

Authorizations:
api_key
query Parameters
carrier_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: carrier_id=se-28529731

Carrier ID

warehouse_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: warehouse_id=se-28529731

Warehouse ID

created_at_start
string <date-time>
Example: created_at_start=2019-03-12T19:24:13.657Z

Only return scheduled pickups that were created on or after a specific date/time

created_at_end
string <date-time>
Example: created_at_end=2019-03-12T19:24:13.657Z

Only return scheduled pickups that were created on or before a specific date/time

page
integer <int32> >= 1
Default: 1
Example: page=2

Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.

page_size
integer <int32> >= 1
Default: 25
Example: page_size=50

The number of results to return per response.

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/pickups
https://api.shipengine.com/v1/pickups

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "pickups":
    [
    ],
  • "total": 3,
  • "page": 3,
  • "pages": 4,
  • "links":
    {},
  • "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
  • "errors":
    [
    ]
}

Schedule a Pickup

Schedule a package pickup with a carrier

Authorizations:
api_key
Request Body schema: application/json
label_ids
required
Array of strings

Label IDs that will be included in the pickup request

contact_details
required
object (contact_details)
pickup_notes
string >= 0 characters

Used by some carriers to give special instructions for a package pickup

pickup_window
required
object (pickup_window)

The desired time range for the package pickup.

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/pickups
https://api.shipengine.com/v1/pickups

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "label_ids":
    [
    ],
  • "contact_details":
    {
    },
  • "pickup_notes": "string",
  • "pickup_window":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW",
  • "label_ids":
    [
    ],
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "cancelled_at": "2018-09-23T15:00:00.000Z",
  • "carrier_id": "se-28529731",
  • "confirmation_number": "292513CL4A3",
  • "warehouse_id": "se-28529731",
  • "pickup_address":
    {
    },
  • "contact_details":
    {
    },
  • "pickup_notes": "string",
  • "pickup_windows":
    [
    ],
  • "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
  • "errors":
    [
    ]
}

Get Pickup By ID

Get Pickup By ID

Authorizations:
api_key
path Parameters
pickup_id
required
string (pickup_resource_id) >= 4 characters
Example: pik_3YcKU5zdtJuCqoeNwyqqbW

Pickup Resource ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/pickups/{pickup_id}
https://api.shipengine.com/v1/pickups/{pickup_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW",
  • "label_ids":
    [
    ],
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "cancelled_at": "2018-09-23T15:00:00.000Z",
  • "carrier_id": "se-28529731",
  • "confirmation_number": "292513CL4A3",
  • "warehouse_id": "se-28529731",
  • "pickup_address":
    {
    },
  • "contact_details":
    {
    },
  • "pickup_notes": "string",
  • "pickup_windows":
    [
    ],
  • "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
  • "errors":
    [
    ]
}

Delete a Scheduled Pickup

Delete a previously-scheduled pickup by ID

Authorizations:
api_key
path Parameters
pickup_id
required
string (pickup_resource_id) >= 4 characters
Example: pik_3YcKU5zdtJuCqoeNwyqqbW

Pickup Resource ID

Responses

200

Return the pickup_id of the scheduled pickup that was successfully deleted

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

delete/v1/pickups/{pickup_id}
https://api.shipengine.com/v1/pickups/{pickup_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
  • "errors":
    [
    ],
  • "pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW"
}

Package Types

custom package types

List Custom Package Types

List the custom package types associated with the account

Authorizations:
api_key

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/packages
https://api.shipengine.com/v1/packages

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "packages":
    [
    ]
}

Create Custom Package Type

Create a custom package type to better assist in getting accurate rate estimates

Authorizations:
api_key
Request Body schema: application/json
package_id
string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

A string that uniquely identifies the package.

package_code
required
string [ 1 .. 50 ] characters ^[a-z0-9]+(_[a-z0-9]+)*$

A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.

name
required
string [ 1 .. 50 ] characters
dimensions
object

The custom dimensions for the package.

description
string <= 500 characters Nullable

Provides a helpful description for the custom package.

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/packages
https://api.shipengine.com/v1/packages

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "package_id": "se-28529731",
  • "package_code": "small_flat_rate_box",
  • "name": "laptop_box",
  • "dimensions":
    {
    },
  • "description": "Packaging for laptops"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "package_id": "se-28529731",
  • "package_code": "small_flat_rate_box",
  • "name": "laptop_box",
  • "dimensions":
    {
    },
  • "description": "Packaging for laptops"
}

Get Custom Package Type By ID

Get Custom Package Type by ID

Authorizations:
api_key
path Parameters
package_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Package ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/packages/{package_id}
https://api.shipengine.com/v1/packages/{package_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "package_id": "se-28529731",
  • "package_code": "small_flat_rate_box",
  • "name": "laptop_box",
  • "dimensions":
    {
    },
  • "description": "Packaging for laptops"
}

Update Custom Package Type By ID

Update the custom package type object by ID

Authorizations:
api_key
path Parameters
package_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Package ID

Request Body schema: application/json
package_id
string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

A string that uniquely identifies the package.

package_code
required
string [ 1 .. 50 ] characters ^[a-z0-9]+(_[a-z0-9]+)*$

A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.

name
required
string [ 1 .. 50 ] characters
dimensions
object

The custom dimensions for the package.

description
string <= 500 characters Nullable

Provides a helpful description for the custom package.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/packages/{package_id}
https://api.shipengine.com/v1/packages/{package_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "package_id": "se-28529731",
  • "package_code": "small_flat_rate_box",
  • "name": "laptop_box",
  • "dimensions":
    {
    },
  • "description": "Packaging for laptops"
}

Response samples

Content type
text/plain
No sample

Delete A Custom Package By ID

Delete a custom package using the ID

Authorizations:
api_key
path Parameters
package_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Package ID

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

delete/v1/packages/{package_id}
https://api.shipengine.com/v1/packages/{package_id}

Response samples

Content type
text/plain
No sample

Rates

Make sure you ship as cost-effectively as possible by quickly comparing rates using the ShipEngine Rates API. As long as you have the carrier connected to your account, you'll be able to see and compare different rates and services.

This quick start guide shows you how to get shipping rates for multiple carriers so you can choose the fastest, cheapest, or most reliable option.

Get Shipping Rates

It's not uncommon that you want to give your customer the choice between whether they want to ship the fastest, cheapest, or the most trusted route. Most companies don't solely ship things using a single shipping option; so we provide functionality to show you all your options!

Authorizations:
api_key
Request Body schema: application/json
One of
  • shipment_id_request
  • rate_shipment_request
shipment_id
required
string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

A string that uniquely identifies the shipment

rate_options
object

The rate options

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/rates
https://api.shipengine.com/v1/rates

Request samples

Content type
application/json
Example
shipment_id_request
Copy
 Expand all Collapse all
{
  • "shipment_id": "se-28529731",
  • "rate_options":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "shipment_id": "se-28529731",
  • "carrier_id": "se-28529731",
  • "service_code": "usps_first_class_mail",
  • "shipping_rule_id": "se-28529731",
  • "external_order_id": "string",
  • "items": [ ],
  • "tax_identifiers":
    [
    ],
  • "external_shipment_id": "string",
  • "shipment_number": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "modified_at": "2018-09-23T15:00:00.000Z",
  • "shipment_status": "pending",
  • "ship_to":
    {
    },
  • "ship_from":
    {
    },
  • "warehouse_id": "se-28529731",
  • "return_to":
    {
    },
  • "is_return": false,
  • "confirmation": "none",
  • "customs":
    {
    },
  • "advanced_options":
    {
    },
  • "insurance_provider": "none",
  • "tags": [ ],
  • "order_source_code": "amazon_ca",
  • "packages":
    [
    ],
  • "total_weight":
    {
    },
  • "comparison_rate_type": "retail",
  • "rate_response":
    {
    }
}

Get Bulk Rates

Get Bulk Shipment Rates

Authorizations:
api_key
Request Body schema: application/json
One of
  • rate_request_by_shipment_ids
  • rate_request_by_shipments
shipment_ids
required
Array of strings

The array of shipment IDs

rate_options
required
object

The rate options

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/rates/bulk
https://api.shipengine.com/v1/rates/bulk

Request samples

Content type
application/json
Example
rate_request_by_shipment_ids
Copy
 Expand all Collapse all
{
  • "shipment_ids":
    [
    ],
  • "rate_options":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Estimate Rates

Get Rate Estimates

Authorizations:
api_key
Request Body schema: application/json
One of
  • rate_estimate_by_carrier_id
  • rate_estimate_by_carrier_ids
carrier_id
string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Deprecated

A string that uniquely identifies the carrier

from_country_code
required
string 2 characters
from_postal_code
required
string non-empty

postal code

from_city_locality
required
string non-empty

from postal code

from_state_province
required
string non-empty

From state province

to_country_code
required
string 2 characters
to_postal_code
required
string non-empty

postal code

to_city_locality
required
string non-empty

The city locality the package is being shipped to

to_state_province
required
string non-empty

To state province

weight
required
object

The weight of the package

dimensions
object

The dimensions of the package

confirmation
string
Enum: "none" "delivery" "signature" "adult_signature" "direct_signature" "delivery_mailed" "verbal_confirmation"

The possible delivery confirmation values

address_residential_indicator
string
Enum: "unknown" "yes" "no"

Indicates whether an address is residential.

ship_date
required
string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2})$

ship date

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/rates/estimate
https://api.shipengine.com/v1/rates/estimate

Request samples

Content type
application/json
Example
rate_estimate_by_carrier_id
Copy
 Expand all Collapse all
{
  • "carrier_id": "se-28529731",
  • "from_country_code": "CA",
  • "from_postal_code": "78756-3717",
  • "from_city_locality": "Austin",
  • "from_state_province": "Austin",
  • "to_country_code": "CA",
  • "to_postal_code": "78756-3717",
  • "to_city_locality": "Austin",
  • "to_state_province": "Houston",
  • "weight":
    {
    },
  • "dimensions":
    {
    },
  • "confirmation": "none",
  • "address_residential_indicator": "unknown",
  • "ship_date": "2018-09-23T15:00:00.000Z"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get Rate By ID

Retrieve a previously queried rate by its ID

Authorizations:
api_key
path Parameters
rate_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Rate ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/rates/{rate_id}
https://api.shipengine.com/v1/rates/{rate_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "rate_id": "se-28529731",
  • "rate_type": "check",
  • "carrier_id": "se-28529731",
  • "shipping_amount":
    {
    },
  • "insurance_amount":
    {
    },
  • "confirmation_amount":
    {
    },
  • "other_amount":
    {
    },
  • "requested_comparison_amount":
    {
    },
  • "tax_amount":
    {
    },
  • "rate_details":
    [
    ],
  • "zone": 6,
  • "package_type": "package",
  • "delivery_days": 5,
  • "guaranteed_service": true,
  • "estimated_delivery_date": "2018-09-23T00:00:00.000Z",
  • "carrier_delivery_days": "string",
  • "ship_date": "2024-11-13T16:05:35Z",
  • "negotiated_rate": true,
  • "service_type": "string",
  • "service_code": "string",
  • "trackable": true,
  • "carrier_code": "string",
  • "carrier_nickname": "string",
  • "carrier_friendly_name": "string",
  • "validation_status": "valid",
  • "warning_messages":
    [
    ],
  • "error_messages":
    [
    ]
}

Service Points

List Service Points

List carrier service points by location

Authorizations:
api_key
Request Body schema: application/json
One of
  • get_service_points_request_body
address_query
string

Unstructured text to search for service points by.

address
object

Structured address to search by.

providers
required
Array of objects

An array of shipping service providers and service codes

lat
number <double>

The latitude of the point. Represented as signed degrees. Required if long is provided. http://www.geomidpoint.com/latlon.html

long
number <double>

The longitude of the point. Represented as signed degrees. Required if lat is provided. http://www.geomidpoint.com/latlon.html

radius
integer <int32>

Search radius in kilometers

max_results
integer <int32>

The maximum number of service points to return

shipment
object

Shipment information to be used for service point selection

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/service_points/list
https://api.shipengine.com/v1/service_points/list

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "address_query": "177A Bleecker Street New York",
  • "address":
    {
    },
  • "providers":
    [
    ],
  • "lat": 48.874518928233094,
  • "long": 2.3591775711639404,
  • "radius": 500,
  • "max_results": 25,
  • "shipment":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "lat": 48.842608,
  • "long": 0.032875,
  • "service_points":
    [
    ],
  • "errors":
    [
    ]
}

Get Service Point By ID

Returns a carrier service point by using the service_point_id

Authorizations:
api_key
path Parameters
carrier_code
required
string non-empty
Example: stamps_com

Carrier code

country_code
required
string 2 characters
Example: CA
service_point_id
required
string
Example: 614940

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/service_points/{carrier_code}/{country_code}/{service_point_id}
https://api.shipengine.com/v1/service_points/{carrier_code}/{country_code}/{service_point_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "service_point":
    {
    }
}

Shipments

Shipments are at the center of the ShipEngine API. A shipment is the first step in creating a shipping label, or creating a manifest. It's also essential for getting shipping rates.

Learn about the shipment object model concept, and how to persist and re-use shipment data inside ShipEngine.

List Shipments

Get list of Shipments

Authorizations:
api_key
query Parameters
shipment_status
string (shipment_status)
Enum: "pending" "processing" "label_purchased" "cancelled"

The possible shipment status values

batch_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: batch_id=se-28529731

Batch ID

tag
string non-empty
Example: tag=Letters_to_santa

Search for shipments based on the custom tag added to the shipment object

created_at_start
string <date-time>
Example: created_at_start=2019-03-12T19:24:13.657Z

Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time)

created_at_end
string <date-time>
Example: created_at_end=2019-03-12T19:24:13.657Z

Used to create a filter for when a resource was created, (ex. A shipment that was created before a certain time)

modified_at_start
string <date-time>
Example: modified_at_start=2019-03-12T19:24:13.657Z

Used to create a filter for when a resource was modified (ex. A shipment that was modified after a certain time)

modified_at_end
string <date-time>
Example: modified_at_end=2019-03-12T19:24:13.657Z

Used to create a filter for when a resource was modified (ex. A shipment that was modified before a certain time)

page
integer <int32> >= 1
Default: 1
Example: page=2

Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.

page_size
integer <int32> >= 1
Default: 25
Example: page_size=50

The number of results to return per response.

sales_order_id
string

Sales Order ID

sort_dir
string
Default: "desc"
Enum: "asc" "desc"

Controls the sort order of the query.

sort_by
string (shipments_sort_by)
Enum: "modified_at" "created_at"
Example: sort_by=modified_at

The possible shipments sort by values

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/shipments
https://api.shipengine.com/v1/shipments

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "shipments":
    [
    ],
  • "total": 1990,
  • "page": "????",
  • "pages": 1,
  • "links":
    {}
}

Create Shipments

Create one or multiple shipments.

Authorizations:
api_key
Request Body schema: application/json
shipments
required
Array of objects non-empty

An array of shipments to be created.

Responses

200

The requested object creation was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/shipments
https://api.shipengine.com/v1/shipments

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "shipments":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "has_errors": false,
  • "shipments":
    [
    ]
}

Get Shipment By External ID

Query Shipments created using your own custom ID convention using this endpint

Authorizations:
api_key
path Parameters
external_shipment_id
required
string
Example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/shipments/external_shipment_id/{external_shipment_id}
https://api.shipengine.com/v1/shipments/external_shipment_id/{external_shipment_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "shipment_id": "se-28529731",
  • "carrier_id": "se-28529731",
  • "service_code": "usps_first_class_mail",
  • "shipping_rule_id": "se-28529731",
  • "external_order_id": "string",
  • "items": [ ],
  • "tax_identifiers":
    [
    ],
  • "external_shipment_id": "string",
  • "shipment_number": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "modified_at": "2018-09-23T15:00:00.000Z",
  • "shipment_status": "pending",
  • "ship_to":
    {
    },
  • "ship_from":
    {
    },
  • "warehouse_id": "se-28529731",
  • "return_to":
    {
    },
  • "is_return": false,
  • "confirmation": "none",
  • "customs":
    {
    },
  • "advanced_options":
    {
    },
  • "insurance_provider": "none",
  • "tags": [ ],
  • "order_source_code": "amazon_ca",
  • "packages":
    [
    ],
  • "total_weight":
    {
    },
  • "comparison_rate_type": "retail"
}

Parse shipping info

The shipment-recognition API makes it easy for you to extract shipping data from unstructured text, including people's names, addresses, package weights and dimensions, insurance and delivery requirements, and more.

Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's shipment-recognition API helps you extract meaningful, structured data from this unstructured text. The parsed shipment data is returned in the same structure that's used for other ShipEngine APIs, so you can easily use the parsed data to create a shipping label.

Note: Shipment recognition is currently supported for the United States, Canada, Australia, New Zealand, the United Kingdom, and Ireland.

Authorizations:
api_key
Request Body schema: application/json

The only required field is text, which is the text to be parsed. You can optionally also provide a shipment containing any already-known values. For example, you probably already know the ship_from address, and you may also already know what carrier and service you want to use.

text
required
string non-empty

The unstructured text that contains shipping-related entities

shipment
object

You can optionally provide a shipment object containing any already-known values. For example, you probably already know the ship_from address, and you may also already know what carrier and service you want to use.

Responses

200

Returns the parsed shipment, as well as a confidence score and a list of all the shipping entities that were recognized in the text.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/shipments/recognize
https://api.shipengine.com/v1/shipments/recognize

Request samples

Content type
application/json
Example
Text only

This is the simplest way to call the shipment-recognition API. Just pass the text to be parsed and nothing else.

Copy
 Expand all Collapse all
{
  • "text": "I have a 4oz package that's 5x10x14in, and I need to ship it to Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652. Please send it via USPS first class and require an adult signature. It also needs to be insured for $400.\n"
}

Response samples

Content type
application/json
Example
text_only

This response shows that the shipment-recognition API was able to recognize all the shipping entities in the text. Notice that the ship_from field is not populated, since it wasn't included in the request or in the parsed text.

Copy
 Expand all Collapse all
{
  • "score": 0.9031369611169101,
  • "shipment":
    {
    },
  • "entities":
    [
    ]
}

Get Shipment By ID

Get an individual shipment based on its ID

Authorizations:
api_key
path Parameters
shipment_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Shipment ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/shipments/{shipment_id}
https://api.shipengine.com/v1/shipments/{shipment_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "shipment_id": "se-28529731",
  • "carrier_id": "se-28529731",
  • "service_code": "usps_first_class_mail",
  • "shipping_rule_id": "se-28529731",
  • "external_order_id": "string",
  • "items": [ ],
  • "tax_identifiers":
    [
    ],
  • "external_shipment_id": "string",
  • "shipment_number": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "modified_at": "2018-09-23T15:00:00.000Z",
  • "shipment_status": "pending",
  • "ship_to":
    {
    },
  • "ship_from":
    {
    },
  • "warehouse_id": "se-28529731",
  • "return_to":
    {
    },
  • "is_return": false,
  • "confirmation": "none",
  • "customs":
    {
    },
  • "advanced_options":
    {
    },
  • "insurance_provider": "none",
  • "tags": [ ],
  • "order_source_code": "amazon_ca",
  • "packages":
    [
    ],
  • "total_weight":
    {
    },
  • "comparison_rate_type": "retail"
}

Update Shipment By ID

Update a shipment object based on its ID

Authorizations:
api_key
path Parameters
shipment_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Shipment ID

Request Body schema: application/json
carrier_id
string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

The carrier account that is billed for the shipping charges

service_code
string ^[a-z0-9]+(_[a-z0-9-]+)* ?$

The carrier service used to ship the package, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.

shipping_rule_id
string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment

external_order_id
string Nullable

ID that the Order Source assigned

items
Array of objects
Default: []

Describe the packages included in this shipment as related to potential metadata that was imported from external order sources

tax_identifiers
Array of objects Nullable
external_shipment_id
string <= 50 characters Nullable

A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.

Warning: The external_shipment_id is limited to 50 characters. Any additional characters will be truncated.

shipment_number
string <= 50 characters Nullable

A non-unique user-defined number used to identify a shipment. If undefined, this will match the external_shipment_id of the shipment.

Warning: The shipment_number is limited to 50 characters. Any additional characters will be truncated.

ship_date
string <date-time> ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2}))?$

The date that the shipment was (or will be) shipped. ShipEngine will take the day of week into consideration. For example, if the carrier does not operate on Sundays, then a package that would have shipped on Sunday will ship on Monday instead.

ship_to
required
object

The recipient's mailing address

ship_from
required
object

The shipment's origin address. If you frequently ship from the same location, consider creating a warehouse. Then you can simply specify the warehouse_id rather than the complete address each time.

warehouse_id
string [ 1 .. 25 ] characters Nullable ^se(-[a-z0-9]+)+$
Default: null

The warehouse that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.

return_to
object

The return address for this shipment. Defaults to the ship_from address.

is_return
boolean Nullable
Default: false

An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.

confirmation
string
Default: "none"
Enum: "none" "delivery" "signature" "adult_signature" "direct_signature" "delivery_mailed" "verbal_confirmation"

The type of delivery confirmation that is required for this shipment.

customs
object Nullable
Default: null

Customs information. This is usually only needed for international shipments.

advanced_options
object

Advanced shipment options. These are entirely optional.

insurance_provider
string
Default: "none"
Enum: "none" "shipsurance" "carrier" "third_party"

The insurance provider to use for any insured packages in the shipment.

order_source_code
string
Enum: "amazon_ca" "amazon_us" "brightpearl" "channel_advisor" "cratejoy" "ebay" "etsy" "jane" "groupon_goods" "magento" "paypal" "seller_active" "shopify" "stitch_labs" "squarespace" "three_dcart" "tophatter" "walmart" "woo_commerce" "volusion"

The order sources that are supported by ShipEngine

packages
Array of objects non-empty

The packages in the shipment.

Note: Some carriers only allow one package per shipment. If you attempt to create a multi-package shipment for a carrier that doesn't allow it, an error will be returned.

comparison_rate_type
string Nullable

Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.

validate_address
string
Default: "no_validation"
Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/shipments/{shipment_id}
https://api.shipengine.com/v1/shipments/{shipment_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "carrier_id": "se-28529731",
  • "service_code": "usps_first_class_mail",
  • "shipping_rule_id": "se-28529731",
  • "external_order_id": "string",
  • "items": [ ],
  • "tax_identifiers":
    [
    ],
  • "external_shipment_id": "string",
  • "shipment_number": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "ship_to":
    {
    },
  • "ship_from":
    {
    },
  • "warehouse_id": "se-28529731",
  • "return_to":
    {
    },
  • "is_return": false,
  • "confirmation": "none",
  • "customs":
    {
    },
  • "advanced_options":
    {
    },
  • "insurance_provider": "none",
  • "order_source_code": "amazon_ca",
  • "packages":
    [
    ],
  • "comparison_rate_type": "retail",
  • "validate_address": "no_validation"
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "shipment_id": "se-28529731",
  • "carrier_id": "se-28529731",
  • "service_code": "usps_first_class_mail",
  • "shipping_rule_id": "se-28529731",
  • "external_order_id": "string",
  • "items": [ ],
  • "tax_identifiers":
    [
    ],
  • "external_shipment_id": "string",
  • "shipment_number": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "modified_at": "2018-09-23T15:00:00.000Z",
  • "shipment_status": "pending",
  • "ship_to":
    {
    },
  • "ship_from":
    {
    },
  • "warehouse_id": "se-28529731",
  • "return_to":
    {
    },
  • "is_return": false,
  • "confirmation": "none",
  • "customs":
    {
    },
  • "advanced_options":
    {
    },
  • "insurance_provider": "none",
  • "tags": [ ],
  • "order_source_code": "amazon_ca",
  • "packages":
    [
    ],
  • "total_weight":
    {
    },
  • "comparison_rate_type": "retail",
  • "errors":
    [
    ],
  • "address_validation":
    {
    }
}

Cancel a Shipment

Mark a shipment cancelled, if it is no longer needed or being used by your organized. Any label associated with the shipment needs to be voided first An example use case would be if a batch label creation job is going to run at a set time and only queries pending shipments. Marking a shipment as cancelled would remove it from this process

Authorizations:
api_key
path Parameters
shipment_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Shipment ID

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/shipments/{shipment_id}/cancel
https://api.shipengine.com/v1/shipments/{shipment_id}/cancel

Response samples

Content type
text/plain
No sample

Get Shipment Rates

Get Rates for the shipment information associated with the shipment ID

Authorizations:
api_key
path Parameters
shipment_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Shipment ID

query Parameters
created_at_start
string <date-time>
Example: created_at_start=2019-03-12T19:24:13.657Z

Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time)

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/shipments/{shipment_id}/rates
https://api.shipengine.com/v1/shipments/{shipment_id}/rates

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "rates":
    [
    ],
  • "invalid_rates": [ ],
  • "rate_request_id": "se-28529731",
  • "shipment_id": "se-28529731",
  • "created_at": "se-28529731",
  • "status": "working",
  • "errors":
    [
    ]
}

Update Shipments Tags

Update Shipments Tags

Authorizations:
api_key
Request Body schema: application/json
shipments_tags
Array of objects

Responses

204

NoContent

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/shipments/tags
https://api.shipengine.com/v1/shipments/tags

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "shipments_tags":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
  • "errors":
    [
    ]
}

Get Shipment Tags

Get Shipment tags based on its ID

Authorizations:
api_key
path Parameters
shipment_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Shipment ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/shipments/{shipment_id}/tags
https://api.shipengine.com/v1/shipments/{shipment_id}/tags

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "tags":
    [
    ]
}

Add Tag to Shipment

Add a tag to the shipment object

Authorizations:
api_key
path Parameters
shipment_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Shipment ID

tag_name
required
string (tag_name) non-empty
Example: Fragile

Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/shipments/{shipment_id}/tags/{tag_name}
https://api.shipengine.com/v1/shipments/{shipment_id}/tags/{tag_name}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "tags":
    [
    ]
}

Remove Tag from Shipment

Remove an existing tag from the Shipment object

Authorizations:
api_key
path Parameters
shipment_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Shipment ID

tag_name
required
string (tag_name) non-empty
Example: Fragile

Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

delete/v1/shipments/{shipment_id}/tags/{tag_name}
https://api.shipengine.com/v1/shipments/{shipment_id}/tags/{tag_name}

Response samples

Content type
text/plain
No sample

Tags

tags

Get Tags

Get a list of all tags associated with an account.

Authorizations:
api_key

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/tags
https://api.shipengine.com/v1/tags

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "tags":
    [
    ]
}

Create a New Tag

Create a new Tag for customizing how you track your shipments

Authorizations:
api_key
path Parameters
tag_name
required
string (tag_name) non-empty
Example: Fragile

Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/tags/{tag_name}
https://api.shipengine.com/v1/tags/{tag_name}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "Fragile"
}

Delete Tag

Delete a tag that is no longer needed

Authorizations:
api_key
path Parameters
tag_name
required
string (tag_name) non-empty
Example: Fragile

Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

delete/v1/tags/{tag_name}
https://api.shipengine.com/v1/tags/{tag_name}

Response samples

Content type
text/plain
No sample

Update Tag Name

Change a tag name while still keeping the relevant shipments attached to it

Authorizations:
api_key
path Parameters
tag_name
required
string (tag_name) non-empty
Example: Fragile

Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.

new_tag_name
required
string (tag_name) non-empty
Example: Fragile

Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/tags/{tag_name}/{new_tag_name}
https://api.shipengine.com/v1/tags/{tag_name}/{new_tag_name}

Response samples

Content type
text/plain
No sample

Tokens

Get Ephemeral Token

This endpoint returns a token that can be passed to an application for authorized access. The lifetime of this token is 10 seconds.

Authorizations:
api_key
query Parameters
redirect
string (redirect)
Value: "shipengine-dashboard"

Include a redirect url to the application formatted with the ephemeral token.

Responses

200

OK

post/v1/tokens/ephemeral
https://api.shipengine.com/v1/tokens/ephemeral

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "string",
  • "redirect_url": "string"
}

Tracking

Track packages across any of our 20+ supported carrier accounts and create tracking events to keep your customers up-to-date. Easily integrate real-time tracking information for shipments into your app, email, or SMS.

Learn how to use ShipEngine to track any package with a carrier and a tracking number

Get Tracking Information

Retrieve package tracking information

Authorizations:
api_key
query Parameters
carrier_code
string non-empty
Example: carrier_code=stamps_com

A shipping carrier, such as fedex, dhl_express, stamps_com, etc.

tracking_number
string non-empty
Example: tracking_number=9405511899223197428490

The tracking number associated with a shipment

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/tracking
https://api.shipengine.com/v1/tracking

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "tracking_number": "1Z932R800392060079",
  • "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
  • "status_code": "DE",
  • "status_detail_code": "DELIVERED",
  • "carrier_code": "dhl_express",
  • "carrier_id": 0,
  • "status_description": "Delivered",
  • "status_detail_description": "Your shipment has been delivered.",
  • "carrier_status_code": 1,
  • "carrier_detail_code": "OT",
  • "carrier_status_description": "Your item was delivered in or at the mailbox at 9:10 am on March",
  • "ship_date": "2018-09-23T15:00:00.000Z",
  • "estimated_delivery_date": "2018-09-23T15:00:00.000Z",
  • "actual_delivery_date": "2018-09-23T15:00:00.000Z",
  • "exception_description": "string",
  • "events":
    [
    ]
}

Start Tracking a Package

Allows you to subscribe to tracking updates for a package. You specify the carrier_code and tracking_number of the package, and receive notifications via webhooks whenever the shipping status changes.

Authorizations:
api_key
query Parameters
carrier_code
string non-empty
Example: carrier_code=stamps_com

A shipping carrier, such as fedex, dhl_express, stamps_com, etc.

tracking_number
string non-empty
Example: tracking_number=9405511899223197428490

The tracking number associated with a shipment

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/tracking/start
https://api.shipengine.com/v1/tracking/start

Response samples

Content type
text/plain
No sample

Stop Tracking a Package

Unsubscribe from tracking updates for a package.

Authorizations:
api_key
query Parameters
carrier_code
string non-empty
Example: carrier_code=stamps_com

A shipping carrier, such as fedex, dhl_express, stamps_com, etc.

tracking_number
string non-empty
Example: tracking_number=9405511899223197428490

The tracking number associated with a shipment

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/tracking/stop
https://api.shipengine.com/v1/tracking/stop

Response samples

Content type
text/plain
No sample

Warehouses

warehouses

List Warehouses

Retrieve a list of warehouses associated with this account.

Authorizations:
api_key

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/warehouses
https://api.shipengine.com/v1/warehouses

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "warehouses":
    [
    ]
}

Create Warehouse

Create a warehouse location that you can use to create shipping items by simply passing in the generated warehouse id. If the return address is not supplied in the request body then it is assumed that the origin address is the return address as well

Authorizations:
api_key
Request Body schema: application/json
is_default
boolean Nullable
Default: false

Designates which single warehouse is the default on the account

name
required
string non-empty

Name of the warehouse

origin_address
required
object

The origin address of the warehouse

return_address
object

The return address associated with the warehouse

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/warehouses
https://api.shipengine.com/v1/warehouses

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "is_default": false,
  • "name": "Zero Cool HQ",
  • "origin_address":
    {
    },
  • "return_address":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "warehouse_id": "se-28529731",
  • "is_default": false,
  • "name": "Zero Cool HQ",
  • "created_at": "2019-06-25T18:12:35.583Z",
  • "origin_address":
    {
    },
  • "return_address":
    {
    }
}

Get Warehouse By Id

Retrieve warehouse data based on the warehouse ID

Authorizations:
api_key
path Parameters
warehouse_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Warehouse ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/warehouses/{warehouse_id}
https://api.shipengine.com/v1/warehouses/{warehouse_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "warehouse_id": "se-28529731",
  • "is_default": false,
  • "name": "Zero Cool HQ",
  • "created_at": "2019-06-25T18:12:35.583Z",
  • "origin_address":
    {
    },
  • "return_address":
    {
    }
}

Update Warehouse By Id

Update Warehouse object information

Authorizations:
api_key
path Parameters
warehouse_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Warehouse ID

Request Body schema: application/json
is_default
boolean Nullable
Default: false

Designates which single warehouse is the default on the account

name
required
string non-empty

Name of the warehouse

origin_address
required
object

The origin address of the warehouse

return_address
object

The return address associated with the warehouse

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/warehouses/{warehouse_id}
https://api.shipengine.com/v1/warehouses/{warehouse_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "is_default": false,
  • "name": "Zero Cool HQ",
  • "origin_address":
    {
    },
  • "return_address":
    {
    }
}

Response samples

Content type
text/plain
No sample

Delete Warehouse By ID

Delete a warehouse by ID

Authorizations:
api_key
path Parameters
warehouse_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Warehouse ID

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

delete/v1/warehouses/{warehouse_id}
https://api.shipengine.com/v1/warehouses/{warehouse_id}

Response samples

Content type
text/plain
No sample

Update Warehouse Settings

Update Warehouse settings object information

Authorizations:
api_key
path Parameters
warehouse_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Warehouse ID

Request Body schema: application/json
is_default
boolean Nullable

The default property on the warehouse.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/warehouses/{warehouse_id}/settings
https://api.shipengine.com/v1/warehouses/{warehouse_id}/settings

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "is_default": true
}

Response samples

Content type
text/plain
No sample

Webhooks

Webhooks are a powerful feature of ShipEngine that can save you from sending repeated polling requests to check on the state of something. With webhooks, ShipEngine will automatically contact your servers when the stage changes. This can include parcel tracking events, notification of the completion of a batch operation, or new salses orders.

Learn how to setup webhooks and start listening to ShipEngine events.

List Webhooks

List all webhooks currently enabled for the account.

Authorizations:
api_key

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/environment/webhooks
https://api.shipengine.com/v1/environment/webhooks

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Create a Webhook

Create a webook for specific events in the environment.

Authorizations:
api_key
Request Body schema: application/json
event
required
string
Enum: "batch" "carrier_connected" "order_source_refresh_complete" "rate" "report_complete" "sales_orders_imported" "track"

The possible webook event values

url
required
string <url> non-empty

The url that the webhook sends the request to

headers
Array of objects

Array of custom webhook headers

Responses

200

The request was a success.

400

The request contained errors.

409

The request conflicts with an existing resource.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

post/v1/environment/webhooks
https://api.shipengine.com/v1/environment/webhooks

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "event": "batch",
  • "url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
  • "headers":
    [
    ]
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "webhook_id": "se-28529731",
  • "url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
  • "event": "batch",
  • "headers":
    [
    ]
}

Get Webhook By ID

Retrieve individual webhook by an ID

Authorizations:
api_key
path Parameters
webhook_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Webhook ID

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

get/v1/environment/webhooks/{webhook_id}
https://api.shipengine.com/v1/environment/webhooks/{webhook_id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "webhook_id": "se-28529731",
  • "url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
  • "event": "batch",
  • "headers":
    [
    ]
}

Update a Webhook

Update the webhook url property

Authorizations:
api_key
path Parameters
webhook_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Webhook ID

Request Body schema: application/json
url
string <url> non-empty

The url that the wehbook sends the request

headers
Array of objects

Array of custom webhook headers

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

put/v1/environment/webhooks/{webhook_id}
https://api.shipengine.com/v1/environment/webhooks/{webhook_id}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
  • "headers":
    [
    ]
}

Response samples

Content type
text/plain
No sample

Delete Webhook By ID

Delete a webhook

Authorizations:
api_key
path Parameters
webhook_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Example: se-28529731

Webhook ID

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

This error will automatically be reported to our engineers.

delete/v1/environment/webhooks/{webhook_id}
https://api.shipengine.com/v1/environment/webhooks/{webhook_id}

Response samples

Content type
text/plain
No sample