🎉 ShipEngine is becoming ShipStation API 🎉 This documentation has moved. Please visit the new ShipStation API documentation portal for the latest updates and features.
ShipEngine logo
API docs by Redocly

ShipEngine API (1.1.202604070904)

Download OpenAPI specification:

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.

Account

For additional information about the ShipEngine account.

List Account Settings

List all account settings for the ShipEngine account

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "default_label_layout": "4x6"
}

List Account Images

List all account images for the ShipEngine account

Authorizations:
api_key

Responses

Response samples

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

Create an Account Image

Create an Account Image

Authorizations:
api_key
Request Body schema: application/json
required
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

Request samples

Content type
application/json
{
  • "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
{
  • "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

Response samples

Content type
application/json
{
  • "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
required
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

Request samples

Content type
application/json
{
  • "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
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

Response samples

Content type
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
required

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

object (partial_address)

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

Request samples

Content type
application/json
Example

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

{
  • "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

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.

{
  • "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
required
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 or null

Email for the address owner.

company_name
string or null non-empty

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 or null non-empty

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

address_line3
string or null non-empty

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 (postal_code) non-empty

postal code

country_code
required
string (country_code) = 2 characters

The two-letter ISO 3166-1 country code

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

Indicates whether this is a residential address.

Responses

Request samples

Content type
application/json

A call that returns a status of verified.

[
  • {
    }
]

Response samples

Content type
application/json
Example

A response for a verified status call.

[
  • {
    }
]

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 (sort_dir)
Default: "desc"
Enum: "asc" "desc"

Controls the sort order of the query.

batch_number
string

Batch Number

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

Only return batches 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 batches that were created on or before a specific date/time

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

Only return batches that were processed on or after a specific date/time

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

Only return batches that were processed on or before a specific date/time

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

The possible batches sort by values

Responses

Response samples

Content type
application/json
{}

Create A Batch

Create a Batch

Authorizations:
api_key
Request Body schema: application/json
required
One of
external_batch_id
string (se_id) [ 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 (se_id) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]

Array of shipment IDs used in the batch

rate_ids
Array of strings (se_id) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]

Array of rate IDs used in the batch

Responses

Request samples

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

Response samples

Content type
application/json
{}

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

Response samples

Content type
application/json
{}

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

Response samples

Content type
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

Response samples

Content type
application/json
{}

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

Response samples

Content type
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
required
shipment_ids
Array of strings (se_id) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]

The Shipment Ids to be modified on the batch

rate_ids
Array of strings (se_id) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]

Array of Rate IDs to be modifed on the batch

Responses

Request samples

Content type
application/json
{
  • "shipment_ids": [
    ],
  • "rate_ids": [
    ]
}

Response samples

Content type
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

Response samples

Content type
application/json
{}

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
required
ship_date
string <date-time> (date_time) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...

The Ship date the batch is being processed for

label_layout
string (label_layout)
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 (label_format)
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 (display_scheme)
Default: "label"
Enum: "label" "paperless" "label_and_paperless"

The display format that the label should be shown in.

Responses

Request samples

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

Response samples

Content type
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
required
shipment_ids
Array of strings (se_id) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]

The Shipment Ids to be modified on the batch

rate_ids
Array of strings (se_id) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]

Array of Rate IDs to be modifed on the batch

Responses

Request samples

Content type
application/json
{
  • "shipment_ids": [
    ],
  • "rate_ids": [
    ]
}

Response samples

Content type
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
required
One of
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

Request samples

Content type
application/json
Example
{
  • "nickname": "Stamps.com",
  • "username": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
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

Response samples

Content type
application/json
Example
{
  • "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
required
One of
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

Request samples

Content type
application/json
Example
{
  • "nickname": "string",
  • "should_hide_account_number_on_archive_doc": true,
  • "is_primary_account": true
}

Response samples

Content type
No sample

Carriers

carriers

List Carriers

List all carriers that have been added to this account

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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,
  • "allows_returns": true,
  • "supports_label_messages": true,
  • "disabled_by_billing_plan": true,
  • "services": [
    ],
  • "packages": [
    ],
  • "options": [
    ],
  • "send_rates": true,
  • "supports_user_managed_rates": true,
  • "connection_status": "pending_approval"
}

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

Response samples

Content type
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
required
currency
required
string (currency)

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

Request samples

Content type
application/json
{
  • "currency": "string",
  • "amount": 0
}

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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

Response samples

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

Insurance

insurance

Disconnect a Shipsurance Account

Disconnect a Shipsurance Account

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{ }

Connect a Shipsurance Account

Connect a Shipsurance Account

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

An email address.

policy_id
required
string non-empty

Responses

Request samples

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

Response samples

Content type
application/json
{ }

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
required
currency
required
string (currency)

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

Request samples

Content type
application/json
{
  • "currency": "string",
  • "amount": 0
}

Response samples

Content type
application/json
{
  • "currency": "string",
  • "amount": 0
}

Get Insurance Funds Balance

Retrieve the balance of your Shipsurance account.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "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

Created Combined Label Document

Download a combined label file

Authorizations:
api_key
Request Body schema: application/json
required
label_ids
Array of strings (se_id) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]

The list of up to 30 label ids to include in the combined label document. Note that to avoid response size limits, you should only expect to be able to combine 30 single page labels similar in size to that of USPS labels.

label_format
string
Value: "pdf"

The file format for the combined label document; note that currently only "pdf" is supported.

label_download_type
string (label_download_type)
Default: "inline"
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.
inline You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.

Responses

Request samples

Content type
application/json
{
  • "label_ids": [
    ],
  • "label_format": "pdf",
  • "label_download_type": "inline"
}

Response samples

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

refund_status
Array of strings (refund_status)
Items Enum: "request_scheduled" "pending" "approved" "rejected" "excluded"
Example: refund_status=pending,approved

Only return labels with specific refund status/es.

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 (sort_dir)
Default: "desc"
Enum: "asc" "desc"

Controls the sort order of the query.

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

Controls which field the query is sorted by.

Responses

Response samples

Content type
application/json
{}

Purchase Label

Purchase and print a label for shipment

Authorizations:
api_key
Request Body schema: application/json
required
ship_to_service_point_id
string or null

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 or null

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.

required
object (shipment_request)

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 or null

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

charge_event
string (label_charge_event)
Enum: "carrier_default" "on_creation" "on_carrier_acceptance"

The label charge event.

outbound_label_id
string (se_id) [ 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 (validate_address)
Default: "no_validation"
Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

label_download_type
string (label_download_type)
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.
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 (label_format)
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 (display_scheme)
Default: "label"
Enum: "label" "paperless" "label_and_paperless"

The display format that the label should be shown in.

label_layout
string (label_layout)
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 or null (image_id) >= 4 characters

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

Responses

Request samples

Content type
application/json
{
  • "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
{
  • "label_id": "se-28529731",
  • "status": "processing",
  • "shipment_id": "se-28529731",
  • "external_shipment_id": "string",
  • "external_order_id": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "shipment_cost": {
    },
  • "insurance_cost": {
    },
  • "requested_comparison_amount": {
    },
  • "rate_details": [
    ],
  • "tracking_number": "782758401696",
  • "is_return_label": true,
  • "rma_number": "string",
  • "is_international": true,
  • "batch_id": "se-28529731",
  • "carrier_id": "se-28529731",
  • "charge_event": "carrier_default",
  • "service_code": "usps_first_class_mail",
  • "package_code": "small_flat_rate_box",
  • "voided": true,
  • "voided_at": "2018-09-23T15:00:00.000Z",
  • "label_format": "pdf",
  • "display_scheme": "label",
  • "label_layout": "4x6",
  • "trackable": true,
  • "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
  • "carrier_code": "dhl_express",
  • "tracking_status": "unknown",
  • "confirmation": "none",
  • "label_download": {},
  • "form_download": {},
  • "qr_code_download": {},
  • "paperless_download": {},
  • "insurance_claim": {},
  • "packages": [],
  • "alternative_identifiers": [
    ],
  • "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
  • "ship_to": {
    },
  • "void_type": "manual",
  • "refund_details": {
    }
}

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.
inline You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.

Responses

Response samples

Content type
application/json
{
  • "label_id": "se-28529731",
  • "status": "processing",
  • "shipment_id": "se-28529731",
  • "external_shipment_id": "string",
  • "external_order_id": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "shipment_cost": {
    },
  • "insurance_cost": {
    },
  • "requested_comparison_amount": {
    },
  • "rate_details": [
    ],
  • "tracking_number": "782758401696",
  • "is_return_label": true,
  • "rma_number": "string",
  • "is_international": true,
  • "batch_id": "se-28529731",
  • "carrier_id": "se-28529731",
  • "charge_event": "carrier_default",
  • "service_code": "usps_first_class_mail",
  • "package_code": "small_flat_rate_box",
  • "voided": true,
  • "voided_at": "2018-09-23T15:00:00.000Z",
  • "label_format": "pdf",
  • "display_scheme": "label",
  • "label_layout": "4x6",
  • "trackable": true,
  • "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
  • "carrier_code": "dhl_express",
  • "tracking_status": "unknown",
  • "confirmation": "none",
  • "label_download": {},
  • "form_download": {},
  • "qr_code_download": {},
  • "paperless_download": {},
  • "insurance_claim": {},
  • "packages": [],
  • "alternative_identifiers": [
    ],
  • "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
  • "ship_to": {
    },
  • "void_type": "manual",
  • "refund_details": {
    }
}

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
required
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 (validate_address)
Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

label_layout
string (label_layout)
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 (label_format)
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 (label_download_type)
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.
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 (display_scheme)
Default: "label"
Enum: "label" "paperless" "label_and_paperless"

The display format that the label should be shown in.

Responses

Request samples

Content type
application/json
{
  • "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
{
  • "label_id": "se-28529731",
  • "status": "processing",
  • "shipment_id": "se-28529731",
  • "external_shipment_id": "string",
  • "external_order_id": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "shipment_cost": {
    },
  • "insurance_cost": {
    },
  • "requested_comparison_amount": {
    },
  • "rate_details": [
    ],
  • "tracking_number": "782758401696",
  • "is_return_label": true,
  • "rma_number": "string",
  • "is_international": true,
  • "batch_id": "se-28529731",
  • "carrier_id": "se-28529731",
  • "charge_event": "carrier_default",
  • "service_code": "usps_first_class_mail",
  • "package_code": "small_flat_rate_box",
  • "voided": true,
  • "voided_at": "2018-09-23T15:00:00.000Z",
  • "label_format": "pdf",
  • "display_scheme": "label",
  • "label_layout": "4x6",
  • "trackable": true,
  • "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
  • "carrier_code": "dhl_express",
  • "tracking_status": "unknown",
  • "confirmation": "none",
  • "label_download": {},
  • "form_download": {},
  • "qr_code_download": {},
  • "paperless_download": {},
  • "insurance_claim": {},
  • "packages": [],
  • "alternative_identifiers": [
    ],
  • "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
  • "ship_to": {
    },
  • "void_type": "manual",
  • "refund_details": {
    }
}

Purchase Label from Rate Shopper

Purchase and print a shipping label using the Rate Shopper. The Rate Shopper automatically selects the optimal carrier and service from your wallet carriers based on your specified rate selection strategy (cheapest, fastest, or best_value). For more information about this in the rates documentation.

Authorizations:
api_key
path Parameters
rate_shopper_id
required
string (rate_attributes)
Enum: "best_value" "cheapest" "fastest"

The rate selection strategy for the Rate Shopper. This determines which carrier and service will be automatically selected from your wallet carriers based on the rates returned for the shipment.

Request Body schema: application/json
required

Label creation details with inline shipment

required
object (partial_shipment_for_rate_shopper)

The shipment details for which to create a label. Must be provided inline. The carrier_id, service_code, and shipping_rule_id are not included as these will be automatically determined by the Rate Shopper based on your strategy.

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 or null

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

charge_event
string (label_charge_event)
Enum: "carrier_default" "on_creation" "on_carrier_acceptance"

The label charge event.

outbound_label_id
string (se_id) [ 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 (validate_address)
Default: "no_validation"
Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

label_download_type
string (label_download_type)
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.
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 (label_format)
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 (display_scheme)
Default: "label"
Enum: "label" "paperless" "label_and_paperless"

The display format that the label should be shown in.

label_layout
string (label_layout)
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 or null (image_id) >= 4 characters

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

Responses

Request samples

Content type
application/json
{
  • "shipment": {
    },
  • "label_format": "pdf",
  • "label_layout": "4x6"
}

Response samples

Content type
application/json
{}

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
required
validate_address
string (validate_address)
Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

label_layout
string (label_layout)
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 (label_format)
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 (label_download_type)
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.
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 (display_scheme)
Default: "label"
Enum: "label" "paperless" "label_and_paperless"

The display format that the label should be shown in.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "label_id": "se-28529731",
  • "status": "processing",
  • "shipment_id": "se-28529731",
  • "external_shipment_id": "string",
  • "external_order_id": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "shipment_cost": {
    },
  • "insurance_cost": {
    },
  • "requested_comparison_amount": {
    },
  • "rate_details": [
    ],
  • "tracking_number": "782758401696",
  • "is_return_label": true,
  • "rma_number": "string",
  • "is_international": true,
  • "batch_id": "se-28529731",
  • "carrier_id": "se-28529731",
  • "charge_event": "carrier_default",
  • "service_code": "usps_first_class_mail",
  • "package_code": "small_flat_rate_box",
  • "voided": true,
  • "voided_at": "2018-09-23T15:00:00.000Z",
  • "label_format": "pdf",
  • "display_scheme": "label",
  • "label_layout": "4x6",
  • "trackable": true,
  • "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
  • "carrier_code": "dhl_express",
  • "tracking_status": "unknown",
  • "confirmation": "none",
  • "label_download": {},
  • "form_download": {},
  • "qr_code_download": {},
  • "paperless_download": {},
  • "insurance_claim": {},
  • "packages": [],
  • "alternative_identifiers": [
    ],
  • "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
  • "ship_to": {
    },
  • "void_type": "manual",
  • "refund_details": {
    }
}

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.
inline You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.

Responses

Response samples

Content type
application/json
{
  • "label_id": "se-28529731",
  • "status": "processing",
  • "shipment_id": "se-28529731",
  • "external_shipment_id": "string",
  • "external_order_id": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "shipment_cost": {
    },
  • "insurance_cost": {
    },
  • "requested_comparison_amount": {
    },
  • "rate_details": [
    ],
  • "tracking_number": "782758401696",
  • "is_return_label": true,
  • "rma_number": "string",
  • "is_international": true,
  • "batch_id": "se-28529731",
  • "carrier_id": "se-28529731",
  • "charge_event": "carrier_default",
  • "service_code": "usps_first_class_mail",
  • "package_code": "small_flat_rate_box",
  • "voided": true,
  • "voided_at": "2018-09-23T15:00:00.000Z",
  • "label_format": "pdf",
  • "display_scheme": "label",
  • "label_layout": "4x6",
  • "trackable": true,
  • "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
  • "carrier_code": "dhl_express",
  • "tracking_status": "unknown",
  • "confirmation": "none",
  • "label_download": {},
  • "form_download": {},
  • "qr_code_download": {},
  • "paperless_download": {},
  • "insurance_claim": {},
  • "packages": [],
  • "alternative_identifiers": [
    ],
  • "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
  • "ship_to": {
    },
  • "void_type": "manual",
  • "refund_details": {
    }
}

Create a return label

Create a return label for an existing outbound label. You can optionally specify a custom RMA (Return Merchandise Authorization) number. If no RMA number is provided, the system will auto-generate one.

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
required
charge_event
string (label_charge_event)
Enum: "carrier_default" "on_creation" "on_carrier_acceptance"

The label charge event.

label_layout
string (label_layout)
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 (label_format)
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 (label_download_type)
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.
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 (display_scheme)
Default: "label"
Enum: "label" "paperless" "label_and_paperless"

The display format that the label should be shown in.

label_image_id
string or null (image_id) >= 4 characters

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

rma_number
string or null

An optional Return Merchandise Authorization number. If provided, this value will be used as the return label's RMA number. If omitted, the system will auto-generate an RMA number (current default behavior). You can set it to any string value.

Responses

Request samples

Content type
application/json
Example

Create a return label with a specific RMA number

{
  • "label_format": "pdf",
  • "label_layout": "4x6",
  • "charge_event": "carrier_default",
  • "rma_number": "RMA-2024-001234"
}

Response samples

Content type
application/json
{
  • "label_id": "se-28529731",
  • "status": "processing",
  • "shipment_id": "se-28529731",
  • "external_shipment_id": "string",
  • "external_order_id": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "shipment_cost": {
    },
  • "insurance_cost": {
    },
  • "requested_comparison_amount": {
    },
  • "rate_details": [
    ],
  • "tracking_number": "782758401696",
  • "is_return_label": true,
  • "rma_number": "string",
  • "is_international": true,
  • "batch_id": "se-28529731",
  • "carrier_id": "se-28529731",
  • "charge_event": "carrier_default",
  • "service_code": "usps_first_class_mail",
  • "package_code": "small_flat_rate_box",
  • "voided": true,
  • "voided_at": "2018-09-23T15:00:00.000Z",
  • "label_format": "pdf",
  • "display_scheme": "label",
  • "label_layout": "4x6",
  • "trackable": true,
  • "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
  • "carrier_code": "dhl_express",
  • "tracking_status": "unknown",
  • "confirmation": "none",
  • "label_download": {},
  • "form_download": {},
  • "qr_code_download": {},
  • "paperless_download": {},
  • "insurance_claim": {},
  • "packages": [],
  • "alternative_identifiers": [
    ],
  • "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
  • "ship_to": {
    },
  • "void_type": "manual",
  • "refund_details": {
    }
}

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

Response samples

Content type
application/json
{
  • "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 parcel has been successfully 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

Response samples

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

Cancel a label refund request

Cancel a scheduled refund request for a label. Only labels with refund status "request_scheduled" can be excluded from an upcoming refund request.

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

Label ID

Responses

Response samples

Content type
application/json
{
  • "label_id": "se-28529731",
  • "status": "processing",
  • "shipment_id": "se-28529731",
  • "external_shipment_id": "string",
  • "external_order_id": "string",
  • "ship_date": "2018-09-23T00:00:00.000Z",
  • "created_at": "2018-09-23T15:00:00.000Z",
  • "shipment_cost": {
    },
  • "insurance_cost": {
    },
  • "requested_comparison_amount": {
    },
  • "rate_details": [
    ],
  • "tracking_number": "782758401696",
  • "is_return_label": true,
  • "rma_number": "string",
  • "is_international": true,
  • "batch_id": "se-28529731",
  • "carrier_id": "se-28529731",
  • "charge_event": "carrier_default",
  • "service_code": "usps_first_class_mail",
  • "package_code": "small_flat_rate_box",
  • "voided": true,
  • "voided_at": "2018-09-23T15:00:00.000Z",
  • "label_format": "pdf",
  • "display_scheme": "label",
  • "label_layout": "4x6",
  • "trackable": true,
  • "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
  • "carrier_code": "dhl_express",
  • "tracking_status": "unknown",
  • "confirmation": "none",
  • "label_download": {},
  • "form_download": {},
  • "qr_code_download": {},
  • "paperless_download": {},
  • "insurance_claim": {},
  • "packages": [],
  • "alternative_identifiers": [
    ],
  • "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
  • "ship_to": {
    },
  • "void_type": "manual",
  • "refund_details": {
    }
}

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) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]
Example: label_ids=se-28529731

Array of label ids

Responses

Response samples

Content type
application/json
{}

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
required
One of
carrier_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

A string that uniquely identifies the carrier

excluded_label_ids
Array of strings (se_id) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]

The list of label ids to exclude from the manifest

label_ids
Array of strings (se_id) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]

The list of label ids to include for the manifest

warehouse_id
required
string (se_id) [ 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

Request samples

Content type
application/json
Example
{
  • "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
{
  • "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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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
required
label_ids
required
Array of strings (se_id) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]

Label IDs that will be included in the pickup request

required
object (contact_details)
pickup_notes
string >= 0 characters

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

required
object (pickup_window)

The desired time range for the package pickup.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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
required
package_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

A string that uniquely identifies the package.

package_code
required
string (package_code) [ 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
object (dimensions)

The custom dimensions for the package.

description
string or null <= 500 characters

Provides a helpful description for the custom package.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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
required
package_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

A string that uniquely identifies the package.

package_code
required
string (package_code) [ 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
object (dimensions)

The custom dimensions for the package.

description
string or null <= 500 characters

Provides a helpful description for the custom package.

Responses

Request samples

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

Response samples

Content type
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

Response samples

Content type
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
required
One of
shipment_id
required
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

A string that uniquely identifies the shipment

ship_to_service_point_id
string or null

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 or null

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.

object (rate_request_body)

The rate options

Responses

Request samples

Content type
application/json
Example
{
  • "shipment_id": "se-28529731",
  • "ship_to_service_point_id": "614940",
  • "ship_from_service_point_id": "614940",
  • "rate_options": {
    }
}

Response samples

Content type
application/json
{
  • "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": null,
  • "return_to": {
    },
  • "is_return": false,
  • "confirmation": "none",
  • "customs": null,
  • "advanced_options": {
    },
  • "insurance_provider": "none",
  • "tags": [ ],
  • "order_source_code": "amazon_ca",
  • "packages": [
    ],
  • "total_weight": {
    },
  • "comparison_rate_type": "retail",
  • "zone": 6,
  • "rate_response": {
    }
}

Get Bulk Rates

Get Bulk Shipment Rates

Authorizations:
api_key
Request Body schema: application/json
required
One of
shipment_ids
required
Array of strings (se_id) [ items [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ]

The array of shipment IDs

ship_to_service_point_id
string or null

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 or null

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.

required
object (rate_request_body)

The rate options

Responses

Request samples

Content type
application/json
Example
{
  • "shipment_ids": [
    ],
  • "ship_to_service_point_id": "614940",
  • "ship_from_service_point_id": "614940",
  • "rate_options": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Estimate Rates

Get Rate Estimates

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

A string that uniquely identifies the carrier

from_country_code
required
string (country_code) = 2 characters
from_postal_code
required
string (postal_code) 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 (country_code) = 2 characters
to_postal_code
required
string (postal_code) 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

required
object (weight)

The weight of the package

object (dimensions)

The dimensions of the package

confirmation
string (delivery_confirmation)
Enum: "none" "delivery" "signature" "adult_signature" "direct_signature" "delivery_mailed" "verbal_confirmation" "delivery_code" "age_verification_16_plus"

The possible delivery confirmation values

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

Indicates whether an address is residential.

ship_date
required
string <date-time> (date_time) ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...

ship date

Responses

Request samples

Content type
application/json
Example
{
  • "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
[
  • {
    }
]

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

Response samples

Content type
application/json
{
  • "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": "2019-08-24T14:15:22Z",
  • "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
required
One of
address_query
string

Unstructured text to search for service points by.

object

Structured address to search by.

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

object

Shipment information to be used for service point selection

Responses

Request samples

Content type
application/json
{
  • "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
{
  • "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

Response samples

Content type
application/json
{
  • "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 (sort_dir)
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

Response samples

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

Create Shipments

Create one or multiple shipments.

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

An array of shipments to be created.

Responses

Request samples

Content type
application/json
{
  • "shipments": [
    ]
}

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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": null,
  • "return_to": {
    },
  • "is_return": false,
  • "confirmation": "none",
  • "customs": null,
  • "advanced_options": {
    },
  • "insurance_provider": "none",
  • "tags": [ ],
  • "order_source_code": "amazon_ca",
  • "packages": [
    ],
  • "total_weight": {
    },
  • "comparison_rate_type": "retail",
  • "zone": 6
}

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
required

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

object (partial_shipment)

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

Request samples

Content type
application/json
Example

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

{
  • "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

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.

{
  • "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

Response samples

Content type
application/json
{
  • "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": null,
  • "return_to": {
    },
  • "is_return": false,
  • "confirmation": "none",
  • "customs": null,
  • "advanced_options": {
    },
  • "insurance_provider": "none",
  • "tags": [ ],
  • "order_source_code": "amazon_ca",
  • "packages": [
    ],
  • "total_weight": {
    },
  • "comparison_rate_type": "retail",
  • "zone": 6
}

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
required
carrier_id
string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$

The carrier account that is billed for the shipping charges

service_code
string (service_code) ^[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 (se_id) [ 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 or null

ID that the Order Source assigned

Array of objects (shipment_item)
Default: []

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

Array of objects or null (tax_identifier)
external_shipment_id
string or null <= 50 characters

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 or null <= 50 characters

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> (date) ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?...

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.

required
object (shipping_address_to)

The recipient's mailing address

required
object (shipping_address)

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 or null (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$
Default: null

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

object (shipping_address)

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

is_return
boolean or null
Default: false

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

confirmation
string (delivery_confirmation)
Default: "none"
Enum: "none" "delivery" "signature" "adult_signature" "direct_signature" "delivery_mailed" "verbal_confirmation" "delivery_code" "age_verification_16_plus"

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

object or null (international_shipment_options)
Default: null

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

object (advanced_shipment_options)

Advanced shipment options. These are entirely optional.

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

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

order_source_code
string (order_source_name)
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

Array of objects (package) 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 or null

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 (validate_address)
Default: "no_validation"
Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

Responses

Request samples

Content type
application/json
{
  • "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": null,
  • "return_to": {
    },
  • "is_return": false,
  • "confirmation": "none",
  • "customs": null,
  • "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
{
  • "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": null,
  • "return_to": {
    },
  • "is_return": false,
  • "confirmation": "none",
  • "customs": null,
  • "advanced_options": {
    },
  • "insurance_provider": "none",
  • "tags": [ ],
  • "order_source_code": "amazon_ca",
  • "packages": [
    ],
  • "total_weight": {
    },
  • "comparison_rate_type": "retail",
  • "zone": 6,
  • "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

Response samples

Content type
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

Response samples

Content type
application/json
{
  • "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
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "shipments_tags": [
    ]
}

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
No sample

Tags

tags

Get Tags

Get a list of all tags associated with an account.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Create a New Tag

Create a new tag for customizing how you track your shipments.

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

The tag name.

color
string non-empty

A hex-coded string identifying the color of the tag.

Responses

Request samples

Content type
application/json
{
  • "name": "Fragile",
  • "color": "#FF0000"
}

Response samples

Content type
application/json
{
  • "tag_id": 8712,
  • "name": "Fragile",
  • "color": "#FF0000"
}

Create a New Tag

Create a new tag for customizing how you track your shipments (deprecated - use POST /v1/tags instead)

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

Response samples

Content type
application/json
{
  • "tag_id": 8712,
  • "name": "Fragile",
  • "color": "#FF0000"
}

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

Response samples

Content type
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

Response samples

Content type
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

Response samples

Content type
application/json
{
  • "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

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

Carrier ID

Responses

Response samples

Content type
application/json
{
  • "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 parcel has been successfully 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

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

Carrier ID

Responses

Response samples

Content type
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

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

Carrier ID

Responses

Response samples

Content type
No sample

Warehouses

warehouses

List Warehouses

Retrieve a list of warehouses associated with this account.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "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
required
is_default
boolean or null
Default: false

Designates which single warehouse is the default on the account

name
required
string non-empty

Name of the warehouse

required
object (address)

The origin address of the warehouse

object (address)

The return address associated with the warehouse

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "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

Response samples

Content type
application/json
{
  • "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
required
is_default
boolean or null
Default: false

Designates which single warehouse is the default on the account

name
required
string non-empty

Name of the warehouse

required
object (address)

The origin address of the warehouse

object (address)

The return address associated with the warehouse

Responses

Request samples

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

Response samples

Content type
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

Response samples

Content type
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
required
is_default
boolean or null

The default property on the warehouse.

Responses

Request samples

Content type
application/json
{
  • "is_default": true
}

Response samples

Content type
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

Response samples

Content type
application/json
[
  • {
    }
]

Create a Webhook

Create a webhook for specific events in the environment.

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

The possible webhook event values

url
required
string <url> (url) non-empty

The url that the webhook sends the request to

Array of objects (webhook_header)

Array of custom webhook headers

name
string

The name of the webhook

store_id
integer <int32>

Store ID

Responses

Request samples

Content type
application/json
{
  • "event": "batch",
  • "url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
  • "headers": [
    ],
  • "name": "My New Webhook",
  • "store_id": 123456
}

Response samples

Content type
application/json
{
  • "webhook_id": "se-28529731",
  • "url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
  • "event": "batch",
  • "headers": [
    ],
  • "name": "My Webhook",
  • "store_id": 123456
}

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

Response samples

Content type
application/json
{
  • "webhook_id": "se-28529731",
  • "url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
  • "event": "batch",
  • "headers": [
    ],
  • "name": "My Webhook",
  • "store_id": 123456
}

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
required
url
string <url> (url) non-empty

The url that the wehbook sends the request

Array of objects (webhook_header)

Array of custom webhook headers

name
string

The name of the webhook

store_id
integer <int32>

Store ID

Responses

Request samples

Content type
application/json
{
  • "url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
  • "headers": [
    ],
  • "name": "My Updated Webhook",
  • "store_id": 123456
}

Response samples

Content type
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

Response samples

Content type
No sample