ShipEngine API

ShipEngine API (1.1.202603171403)

Download OpenAPI specification:Download

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.

Getting Started

Shipping Labels for Every Major Carrier

Real-Time Package Tracking

Compare Shipping Costs Across Carriers

Worldwide Address Validation

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

Authentication

api_key

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

Learn more about API keys in our authentication guide.

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

Account

For additional information about the ShipEngine account.

List Account Settings

List all account settings for the ShipEngine account

Authorizations:

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"default_label_layout": "4x6"

}

List Account Images

List all account images for the ShipEngine account

Authorizations:

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/account/settings/images

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"images":
[
- {
  - "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"
  }
],
"total": 2750,
"page": 1,
"pages": 4,
"links":
{
- "first":
  {
  - "type": "string"
  },
- "last":
  {
  - "type": "string"
  },
- "prev":
  {
  - "type": "string"
  },
- "next":
  {
  - "type": "string"
  }
}

}

Create an Account Image

Authorizations:

Request Body schema: application/json

name required	string [ 1 .. 50 ] characters A human readable name for the image.
is_default	boolean Indicates whether this image is set as default.
image_content_type required	string Enum: "image/png" "image/jpeg" The file type of the image.
image_data required	string A base64 encoded string representation of the image.

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/account/settings/images

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"name": "My logo",
"is_default": false,
"image_content_type": "image/png",
"image_data": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg=="

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

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

}

Get Account Image By ID

Retrieve information for an account image.

Authorizations:

path Parameters

label_image_id

required

string (image_id) >= 4 characters

Example: img_DtBXupDBxREpHnwEXhTfgK

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/account/settings/images/{label_image_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

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

}

Update Account Image By ID

Update information for an account image.

Authorizations:

path Parameters

label_image_id

required

string (image_id) >= 4 characters

Example: img_DtBXupDBxREpHnwEXhTfgK

Request Body schema: application/json

name	string [ 1 .. 50 ] characters A human readable name for the image.
is_default required	boolean Indicates whether this image is set as default.
image_content_type	string Enum: "image/png" "image/jpeg" The file type of the image.
image_data	string A base64 encoded string representation of the image.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/account/settings/images/{label_image_id}

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"name": "My logo",
"is_default": false,
"image_content_type": "image/png",
"image_data": "iVBORw0KGgoAAAANSUhEUgAAABkAAAAZCAYAAADE6YVjAAAAAXNSR0IArs4c6QAAAiVJREFUSEu91j3IeVEcB/CvSTIoBrFSikEZMdjsjExeUspgUEp5SUpeshrIgEFJJmWwMZHJQGHDhJSXTPfpnH/8ebzd56HnN93u7ZzP/f1+55x7Ob1ejxEKheByufh0HI9HrFYrcKbTKUMu5HI5BALBx5zNZoPxeAySAGc2mzF8Pp/e+BR0Ash8u93uHyKVSnH54J2Mvs8zn8//I6RO70L3xt8g70CPXvAu8hvoWQUeIj+BXpX4KcIGegWQOV4izyA2AGvkHsQW+BFyCUkkEiwWC9Ybl1W5Ls8ZMoAABCIbmE3cINFoFMFgEEajEeVyGSKRCJ1OB3q9ns5nMpmQTCaxXq9/l8loNEKj0YDX66UACYvFQq9brRYcDgdUKhU9RD/SEwLm83lEIhGUSiX0+33E4/GrU5otRMs1mUyYbDYLu90OhUJBMzhlZbPZ4Pf7odFo4HQ6b1rABqJIvV5nttstLc0pSIn2+z0tTy6XQ6FQoI/a7TZ0Ot0V9gqiiMFgYKrVKm0yieVyCZ/PB6vVSpF0Ok2zJHEqIY/HYw1RxOfzMYlE4jwoEAhAJpPBbDZf9eBwOCCVSsHtdp9f6FJ6egorlUqmVqvRfjSbTXS7XXg8nptP8Svk0RF01ROtVguSUTgchlgsPpeOZBaLxTAcDlEsFpHJZPC9XM8yoshgMGBCoRBdQWTCU7hcLjohWb5kM6rValQqlfMKfLbbb77xf/K38hf/XV9ilOpnLqvnogAAAABJRU5ErkJggg=="

}

Response samples

Delete Account Image By Id

Authorizations:

path Parameters

label_image_id

required

string (image_id) >= 4 characters

Example: img_DtBXupDBxREpHnwEXhTfgK

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

delete/v1/account/settings/images/{label_image_id}

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

Response samples

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.

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.

Authorizations:

Request Body schema: application/json

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

text required	string non-empty The unstructured text that contains address-related entities
address	object You can optionally provide any already-known address values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines.

Responses

200

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

400

The request contained errors.

500

An error occurred on ShipEngine's side.

put/v1/addresses/recognize

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

Request samples

Payload

Content type

application/json

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

Copy

Expand all Collapse all

{

"text": "Margie McMiller at 3800 North Lamar suite 200 in austin, tx. The zip code there is 78652."

}

Response samples

Content type

application/json

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

Copy

Expand all Collapse all

{

"score": 0.9122137426845613,
"address":
{
- "name": "Margie McMiller",
- "address_line1": "3800 North Lamar",
- "address_line2": "Suite 200",
- "city_locality": "Austin",
- "state_province": "TX",
- "postal_code": 78652,
- "address_residential_indicator": "unknown"
},
"entities":
[
- {
  - "type": "person",
  - "score": 0.9519646137063122,
  - "text": "Margie McMiller",
  - "start_index": 0,
  - "end_index": 14,
  - "result":
    {
    "value": "Margie McMiller"
    }
  },
- {
  - "type": "address_line",
  - "score": 0.9805313966503588,
  - "text": "3800 North Lamar",
  - "start_index": 19,
  - "end_index": 34,
  - "result":
    {
    "line": 1,
    "value": "3800 North Lamar"
    }
  },
- {
  - "type": "number",
  - "score": 0.9805313966503588,
  - "text": 3800,
  - "start_index": 19,
  - "end_index": 22,
  - "result":
    {
    "type": "cardinal",
    "value": 3800
    }
  },
- {
  - "type": "address_line",
  - "score": 1,
  - "text": "suite 200",
  - "start_index": 36,
  - "end_index": 44,
  - "result":
    {
    "line": 2,
    "value": "Suite 200"
    }
  },
- {
  - "type": "number",
  - "score": 0.9805313966503588,
  - "text": 200,
  - "start_index": 42,
  - "end_index": 44,
  - "result":
    {
    "type": "cardinal",
    "value": 200
    }
  },
- {
  - "type": "city_locality",
  - "score": 0.9805313966503588,
  - "text": "austin",
  - "start_index": 49,
  - "end_index": 54,
  - "result":
    {
    "value": "Austin"
    }
  },
- {
  - "type": "state_province",
  - "score": 0.6082904353940255,
  - "text": "tx",
  - "start_index": 57,
  - "end_index": 58,
  - "result":
    {
    "name": "Texas",
    "value": "TX"
    }
  },
- {
  - "type": "postal_code",
  - "score": 0.9519646137063122,
  - "text": 78652,
  - "start_index": 84,
  - "end_index": 88,
  - "result":
    {
    "value": 78652
    }
  }
]

}

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:

Request Body schema: application/json

Array

name	string non-empty The name of a contact person at this address. This field may be set instead of - or in addition to - the `company_name` field.
phone	string non-empty The phone number of a contact person at this address. The format of this phone number varies depending on the country.
email	string Nullable Email for the address owner.
company_name	string non-empty Nullable If this is a business address, then the company name should be specified here.
address_line1 required	string non-empty The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
address_line2	string non-empty Nullable The second line of the street address. For some addresses, this line may not be needed.
address_line3	string non-empty Nullable The third line of the street address. For some addresses, this line may not be needed.
city_locality required	string non-empty The name of the city or locality
state_province required	string non-empty The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
postal_code	string non-empty postal code
country_code required	string 2 characters The two-letter ISO 3166-1 country code
address_residential_indicator	string Default: "unknown" Enum: "unknown" "yes" "no" Indicates whether this is a residential address.

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

post/v1/addresses/validate

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

Request samples

Payload

Content type

application/json

A call that returns a status of verified.

Copy

Expand all Collapse all

[

{
- "name": "Mickey and Minnie Mouse",
- "phone": "714-781-4565",
- "company_name": "The Walt Disney Company",
- "address_line1": "500 South Buena Vista Street",
- "city_locality": "Burbank",
- "state_province": "CA",
- "postal_code": 91521,
- "country_code": "US"
}

]

Response samples

Content type

application/json

A response for a verified status call.

Copy

Expand all Collapse all

[

{
- "status": "verified",
- "original_address":
  {
  - "name": "Mickey and Minnie Mouse",
  - "phone": "714-781-4565",
  - "company_name": "The Walt Disney Company",
  - "address_line1": "500 South Buena Vista Street",
  - "address_line2": null,
  - "address_line3": null,
  - "city_locality": "Burbank",
  - "state_province": "CA",
  - "postal_code": 91521,
  - "country_code": "US",
  - "address_residential_indicator": "unknown"
  },
- "matched_address":
  {
  - "name": "MICKEY AND MINNIE MOUSE",
  - "phone": "714-781-4565",
  - "company_name": "THE WALT DISNEY COMPANY",
  - "address_line1": "500 S BUENA VISTA ST",
  - "address_line2": null,
  - "address_line3": null,
  - "city_locality": "BURBANK",
  - "state_province": "CA",
  - "postal_code": "91521-0007",
  - "country_code": "US",
  - "address_residential_indicator": "no"
  },
- "messages": [ ]
}

]

Batches

List Batches

List Batches associated with your Shipengine account

Authorizations:

query Parameters

status	string (batch_status) Enum: "open" "queued" "processing" "completed" "completed_with_errors" "archived" "notifying" "invalid" The possible batch status values
page	integer <int32> >= 1 Default: 1 Example: page=2 Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.
page_size	integer <int32> >= 1 Default: 25 Example: page_size=50 The number of results to return per response.
sort_dir	string Default: "desc" Enum: "asc" "desc" Controls the sort order of the query.
batch_number	string Batch Number
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

200

The request was a success.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"batches":
[
- {
  - "label_layout": "4x6",
  - "label_format": "pdf",
  - "batch_id": "se-28529731",
  - "batch_number": "string",
  - "external_batch_id": "string",
  - "batch_notes": "Batch for morning shipment",
  - "created_at": "2018-09-23T15:00:00.000Z",
  - "processed_at": "2018-09-23T15:00:00.000Z",
  - "errors": 2,
  - "process_errors":
    [
    {
    "error_source": "carrier",
    "error_type": "account_status",
    "error_code": "auto_fund_not_supported",
    "message": "Body of request cannot be null.",
    "carrier_id": "se-28529731",
    "carrier_code": "dhl_express",
    "field_name": "shipment.ship_to.phone_number"
    }
    ],
  - "warnings": 1,
  - "completed": 1,
  - "forms": 3,
  - "count": 2,
  - "batch_shipments_url":
    {
    "type": "string"
    },
  - "batch_labels_url":
    {
    "type": "string"
    },
  - "batch_errors_url":
    {
    "type": "string"
    },
  - "form_download":
    {
    "type": "string"
    },
  - "paperless_download":
    {
    "instructions": null,
    "handoff_code": null
    },
  - "status": "open"
  }
],
"total": 10,
"page": 1,
"pages": 10,
"links":
{
- "first":
  {
  - "type": "string"
  },
- "last":
  {
  - "type": "string"
  },
- "prev":
  {
  - "type": "string"
  },
- "next":
  {
  - "type": "string"
  }
}

}

Create A Batch

Authorizations:

Request Body schema: application/json

One of

create_batch_request_body
create_and_process_batch_request_body

external_batch_id	string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ A string that uniquely identifies the external batch
batch_notes	string non-empty Add custom messages for a particular batch
shipment_ids	Array of strings Array of shipment IDs used in the batch
rate_ids	Array of strings Array of rate IDs used in the batch

Responses

200

The requested object creation was a success.

207

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

400

The request contained errors.

500

An error occurred on ShipEngine's side.

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

Request samples

Payload

Content type

application/json

Example

Copy

Expand all Collapse all

{

"external_batch_id": "se-28529731",
"batch_notes": "This is my batch",
"shipment_ids":
[
- "se-28529731"
],
"rate_ids":
[
- "se-28529731"
]

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"label_layout": "4x6",
"label_format": "pdf",
"batch_id": "se-28529731",
"batch_number": "string",
"external_batch_id": "string",
"batch_notes": "Batch for morning shipment",
"created_at": "2018-09-23T15:00:00.000Z",
"processed_at": "2018-09-23T15:00:00.000Z",
"errors": 2,
"process_errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
],
"warnings": 1,
"completed": 1,
"forms": 3,
"count": 2,
"batch_shipments_url":
{
- "type": "string"
},
"batch_labels_url":
{
- "type": "string"
},
"batch_errors_url":
{
- "type": "string"
},
"label_download":
{
},
"form_download":
{
- "type": "string"
},
"paperless_download":
{
- "instructions": null,
- "handoff_code": null
},
"status": "open"

}

Get Batch By External ID

Authorizations:

path Parameters

external_batch_id

required

string

Example: 13553d7f-3c87-4771-bae1-c49bacef11cb

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/batches/external_batch_id/{external_batch_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"label_layout": "4x6",
"label_format": "pdf",
"batch_id": "se-28529731",
"batch_number": "string",
"external_batch_id": "string",
"batch_notes": "Batch for morning shipment",
"created_at": "2018-09-23T15:00:00.000Z",
"processed_at": "2018-09-23T15:00:00.000Z",
"errors": 2,
"process_errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
],
"warnings": 1,
"completed": 1,
"forms": 3,
"count": 2,
"batch_shipments_url":
{
- "type": "string"
},
"batch_labels_url":
{
- "type": "string"
},
"batch_errors_url":
{
- "type": "string"
},
"label_download":
{
},
"form_download":
{
- "type": "string"
},
"paperless_download":
{
- "instructions": null,
- "handoff_code": null
},
"status": "open"

}

Delete Batch By Id

Authorizations:

path Parameters

batch_id

required

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

Example: se-28529731

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

delete/v1/batches/{batch_id}

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

Response samples

Get Batch By ID

Authorizations:

path Parameters

batch_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/batches/{batch_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"label_layout": "4x6",
"label_format": "pdf",
"batch_id": "se-28529731",
"batch_number": "string",
"external_batch_id": "string",
"batch_notes": "Batch for morning shipment",
"created_at": "2018-09-23T15:00:00.000Z",
"processed_at": "2018-09-23T15:00:00.000Z",
"errors": 2,
"process_errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
],
"warnings": 1,
"completed": 1,
"forms": 3,
"count": 2,
"batch_shipments_url":
{
- "type": "string"
},
"batch_labels_url":
{
- "type": "string"
},
"batch_errors_url":
{
- "type": "string"
},
"label_download":
{
},
"form_download":
{
- "type": "string"
},
"paperless_download":
{
- "instructions": null,
- "handoff_code": null
},
"status": "open"

}

Update Batch By Id

Authorizations:

path Parameters

batch_id

required

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

Example: se-28529731

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/batches/{batch_id}

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

Response samples

Add to a Batch

Add a Shipment or Rate to a Batch

Authorizations:

path Parameters

batch_id

required

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

Example: se-28529731

Request Body schema: application/json

shipment_ids	Array of strings The Shipment Ids to be modified on the batch
rate_ids	Array of strings Array of Rate IDs to be modifed on the batch

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/batches/{batch_id}/add

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"shipment_ids":
[
- "se-28529731"
],
"rate_ids":
[
- "se-28529731"
]

}

Response samples

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:

path Parameters

batch_id

required

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

Example: se-28529731

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

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/batches/{batch_id}/errors

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"errors": [ ],
"links":
{
- "first":
  {
  - "type": "string"
  },
- "last":
  {
  - "type": "string"
  },
- "prev":
  {
  - "type": "string"
  },
- "next":
  {
  - "type": "string"
  }
}

}

Process Batch ID Labels

Authorizations:

path Parameters

batch_id

required

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

Example: se-28529731

Request Body schema: application/json

ship_date

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

The Ship date the batch is being processed for

label_layout

string

Default: "4x6"

Enum: "4x6" "letter" "A4" "A6"

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

label_format

string

Default: "pdf"

Enum: "pdf" "png" "zpl"

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

Label Format	Supported Carriers
`pdf`	All carriers
`png`	`fedex` `stamps_com` `ups` `usps`
`zpl`	`access_worldwide` `apc` `asendia` `dhl_global_mail` `dhl_express` `dhl_express_australia` `dhl_express_canada` `dhl_express_worldwide` `dhl_express_uk` `dpd` `endicia` `fedex` `fedex_uk` `firstmile` `imex` `newgistics` `ontrac` `rr_donnelley` `stamps_com` `ups` `usps`

display_scheme

string

Default: "label"

Enum: "label" "qr_code" "label_and_qr_code" "paperless" "label_and_paperless"

The display format that the label should be shown in.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/batches/{batch_id}/process/labels

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"ship_date": "2018-09-23T15:00:00.000Z",
"label_layout": "4x6",
"label_format": "pdf",
"display_scheme": "label"

}

Response samples

Remove From Batch

Remove a shipment or rate from a batch

Authorizations:

path Parameters

batch_id

required

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

Example: se-28529731

Request Body schema: application/json

shipment_ids	Array of strings The Shipment Ids to be modified on the batch
rate_ids	Array of strings Array of Rate IDs to be modifed on the batch

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/batches/{batch_id}/remove

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"shipment_ids":
[
- "se-28529731"
],
"rate_ids":
[
- "se-28529731"
]

}

Response samples

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

Authorizations:

path Parameters

carrier_name

required

string (carrier_name)

Enum: "access_worldwide" "amazon_buy_shipping" "amazon_shipping_uk" "apc" "asendia" "australia_post" "canada_post" "dhl_ecommerce" "dhl_express" "dhl_express_au" "dhl_express_ca" "dhl_express_uk" "dpd" "endicia" "fedex" "fedex_uk" "firstmile" "imex" "newgistics" "ontrac" "purolator_canada" "royal_mail" "rr_donnelley" "seko" "sendle" "stamps_com" "ups" "lasership"

Example: dhl_express

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

Request Body schema: application/json

One of

connect_access_worldwide_request_body
connect_amazon_buy_shipping_request_body
connect_amazon_shipping_uk
connect_apc_request_body
connect_asendia_request_body
connect_australia_post_request_body
connect_canada_post_request_body
connect_dhl_ecommerce_request_body
connect_dhl_express_request_body
connect_dhl_express_au_request_body
connect_dhl_express_ca_request_body
connect_dhl_express_uk_request_body
connect_dpd_request_body
connect_endicia_request_body
connect_fedex_request_body
connect_fedex_uk_request_body
connect_firstmile_request_body
connect_imex_request_body
connect_lasership_request_body
connect_newgistics_request_body
connect_ontrac_request_body
connect_purolator_request_body
connect_royal_mail_request_body
connect_rr_donnelley_request_body
connect_seko_request_body
connect_sendle_request_body
connect_stamps_request_body
connect_ups_request_body

nickname required	string non-empty The nickname associated with the carrier connection
username required	string non-empty Access Worldwide Username
password required	string non-empty Access Worldwide Password

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/connections/carriers/{carrier_name}

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

Request samples

Payload

Content type

application/json

Example

Copy

Expand all Collapse all

{

"nickname": "Stamps.com",
"username": "string",
"password": "string"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"carrier_id": "se-28529731"

}

Disconnect a carrier

Authorizations:

path Parameters

carrier_name

required

string (carrier_name)

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

Responses

204

The request was successful.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

delete/v1/connections/carriers/{carrier_name}/{carrier_id}

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

Response samples

Get carrier settings

Authorizations:

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

Responses

200

The request was a success.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/connections/carriers/{carrier_name}/{carrier_id}/settings

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

Response samples

Content type

application/json

Example

Copy

Expand all Collapse all

{

"nickname": "string",
"should_hide_account_number_on_archive_doc": true,
"is_primary_account": true

}

Update carrier settings

Authorizations:

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

Request Body schema: application/json

One of

update_dhl_express_settings_request_body
update_fedex_settings_request_body
update_newgistics_settings_request_body
update_ups_settings_request_body
update_amazon_buy_shipping_request_body

nickname
should_hide_account_number_on_archive_doc	boolean Indicates if the account number should be hidden on the archive documentation
is_primary_account	boolean Indicates if this is primary account

Responses

204

The request was successful.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/connections/carriers/{carrier_name}/{carrier_id}/settings

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

Request samples

Payload

Content type

application/json

Example

Copy

Expand all Collapse all

{

"nickname": "string",
"should_hide_account_number_on_archive_doc": true,
"is_primary_account": true

}

Response samples

Carriers

List Carriers

List all carriers that have been added to this account

Authorizations:

Responses

200

The request was a success.

207

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

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"carriers":
[
- {
  - "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":
    [
    {
    "carrier_id": "se-28529731",
    "carrier_code": "se-28529731",
    "service_code": "usps_media_mail",
    "name": "USPS First Class Mail",
    "domestic": true,
    "international": true,
    "is_multi_package_supported": true,
    "is_return_supported": true
    }
    ],
  - "packages":
    [
    {
    "package_id": "se-28529731",
    "package_code": "small_flat_rate_box",
    "name": "laptop_box",
    "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
    "description": "Packaging for laptops"
    }
    ],
  - "options":
    [
    {
    "name": "contains_alcohol",
    "default_value": false,
    "description": "string"
    }
    ],
  - "send_rates": true,
  - "supports_user_managed_rates": true,
  - "connection_status": "pending_approval"
  }
],
"request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
"errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
]

}

Get Carrier By ID

Retrive carrier info by ID

Authorizations:

path Parameters

carrier_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/carriers/{carrier_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"carrier_id": "se-28529731",
"carrier_code": "dhl_express",
"account_number": "account_570827",
"requires_funded_amount": true,
"balance": 3799.52,
"nickname": "ShipEngine Account - Stamps.com",
"friendly_name": "Stamps.com",
"funding_source_id": "se-28529731",
"primary": true,
"has_multi_package_supporting_services": true,
"allows_returns": true,
"supports_label_messages": true,
"disabled_by_billing_plan": true,
"services":
[
- {
  - "carrier_id": "se-28529731",
  - "carrier_code": "se-28529731",
  - "service_code": "usps_media_mail",
  - "name": "USPS First Class Mail",
  - "domestic": true,
  - "international": true,
  - "is_multi_package_supported": true,
  - "is_return_supported": true
  }
],
"packages":
[
- {
  - "package_id": "se-28529731",
  - "package_code": "small_flat_rate_box",
  - "name": "laptop_box",
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "description": "Packaging for laptops"
  }
],
"options":
[
- {
  - "name": "contains_alcohol",
  - "default_value": false,
  - "description": "string"
  }
],
"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:

path Parameters

carrier_id

required

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

Example: se-28529731

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

delete/v1/carriers/{carrier_id}

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

Response samples

Add Funds To Carrier

Authorizations:

path Parameters

carrier_id

required

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

Example: se-28529731

Request Body schema: application/json

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/carriers/{carrier_id}/add_funds

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"currency": "string",
"amount": 0

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"balance":
{
- "currency": "string",
- "amount": 0
}

}

Get Carrier Options

Get a list of the options available for the carrier

Authorizations:

path Parameters

carrier_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/carriers/{carrier_id}/options

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"options":
[
- {
  - "name": "contains_alcohol",
  - "default_value": false,
  - "description": "string"
  }
]

}

List Carrier Package Types

List the package types associated with the carrier

Authorizations:

path Parameters

carrier_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/carriers/{carrier_id}/packages

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"packages":
[
- {
  - "package_id": "se-28529731",
  - "package_code": "small_flat_rate_box",
  - "name": "laptop_box",
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "description": "Packaging for laptops"
  }
]

}

List Carrier Services

List the services associated with the carrier ID

Authorizations:

path Parameters

carrier_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/carriers/{carrier_id}/services

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"services":
[
- {
  - "carrier_id": "se-28529731",
  - "carrier_code": "se-28529731",
  - "service_code": "usps_media_mail",
  - "name": "USPS First Class Mail",
  - "domestic": true,
  - "international": true,
  - "is_multi_package_supported": true,
  - "is_return_supported": true
  }
]

}

Downloads

Download File

Authorizations:

path Parameters

subdir required
filename required
dir required

query Parameters

download
rotation

Responses

200

The request was a success

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/downloads/{dir}/{subdir}/{filename}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
"errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
]

}

Insurance

Disconnect a Shipsurance Account

Authorizations:

Responses

200

The request was a success

400

The request contained errors.

500

An error occurred on ShipEngine's side.

delete/v1/connections/insurance/shipsurance

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

Connect a Shipsurance Account

Authorizations:

Request Body schema: application/json

email required
policy_id required

Responses

200

The request was a success

400

The request contained errors.

500

An error occurred on ShipEngine's side.

post/v1/connections/insurance/shipsurance

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"email": "john.doe@example.com",
"policy_id": "string"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

Add Funds To Insurance

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

Authorizations:

Request Body schema: application/json

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

patch/v1/insurance/shipsurance/add_funds

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"currency": "string",
"amount": 0

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"currency": "string",
"amount": 0

}

Get Insurance Funds Balance

Retrieve the balance of your Shipsurance account.

Authorizations:

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

get/v1/insurance/shipsurance/balance

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"currency": "string",
"amount": 0

}

Labels

Created Combined Label Document

Download a combined label file

Authorizations:

Request Body schema: application/json

label_ids

Array of strings

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

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

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/documents/combined_labels

https://api.shipengine.com/v1/documents/combined_labels

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"label_ids":
[
- "se-28529731"
],
"label_format": "pdf",
"label_download_type": "url"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"label_download":
{
}

}

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:

query Parameters

label_status	string (label_status) Enum: "processing" "completed" "error" "voided" Only return labels that are currently in the specified status
service_code	string (service_code) ^[a-z0-9]+(_[a-z0-9-]+)* ?$ Example: service_code=usps_first_class_mail Only return labels for a specific carrier service
carrier_id	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: carrier_id=se-28529731 Only return labels for a specific carrier account
tracking_number	string non-empty Example: tracking_number=9405511899223197428490 Only return labels with a specific tracking number
batch_id	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: batch_id=se-28529731 Only return labels that were created in a specific batch
rate_id	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: rate_id=se-28529731 Rate ID
shipment_id	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: shipment_id=se-28529731 Shipment ID
warehouse_id	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: warehouse_id=se-28529731 Only return labels that originate from a specific warehouse
created_at_start	string <date-time> Example: created_at_start=2019-03-12T19:24:13.657Z Only return labels that were created on or after a specific date/time
created_at_end	string <date-time> Example: created_at_end=2019-03-12T19:24:13.657Z Only return labels that were created on or before a specific date/time
page	integer <int32> >= 1 Default: 1 Example: page=2 Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.
page_size	integer <int32> >= 1 Default: 25 Example: page_size=50 The number of results to return per response.
sort_dir	string Default: "desc" Enum: "asc" "desc" Controls the sort order of the query.
sort_by	string Default: "created_at" Enum: "modified_at" "created_at" "voided_at" Controls which field the query is sorted by.

Responses

200

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

400

The request contained errors.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"labels":
[
- {
  - "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":
    {
    "currency": "string",
    "amount": 0
    },
  - "insurance_cost":
    {
    "currency": "string",
    "amount": 0
    },
  - "requested_comparison_amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "rate_details":
    [
    {
    "rate_detail_type": "uncategorized",
    "carrier_description": "string",
    "carrier_billing_code": "string",
    "carrier_memo": "string",
    "amount":
    {
    "currency": "string",
    "amount": 0
    },
    "rate_detail_attributes":
    {
    "tax_type": "vat",
    "tax_percentage": 0
    },
    "billing_source": "string"
    }
    ],
  - "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",
  - "form_download":
    {
    "type": "string"
    },
  - "qr_code_download":
    {
    "type": "string"
    },
  - "paperless_download":
    {
    "instructions": null,
    "handoff_code": null
    },
  - "insurance_claim":
    {
    "type": "string"
    },
  - "packages":
    [
    {
    "package_id": 0,
    "package_code": "small_flat_rate_box",
    "weight":
    {
    "value": 0,
    "unit": "pound"
    },
    "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
    "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
    "tracking_number": "1Z932R800392060079",
    "form_download":
    {
    "type": "string"
    },
    "qr_code_download":
    {
    "type": "string"
    },
    "paperless_download":
    {
    "instructions": null,
    "handoff_code": null
    },
    "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
    "external_package_id": "string",
    "content_description": "Hand knitted wool socks",
    "sequence": 0,
    "has_label_documents": true,
    "has_form_documents": true,
    "has_qr_code_documents": true,
    "has_paperless_label_documents": true,
    "alternative_identifiers":
    [
    {
    "type": "last_mile_tracking_number",
    "value": "12345678912345678912"
    }
    ]
    }
    ],
  - "alternative_identifiers":
    [
    {
    "type": "last_mile_tracking_number",
    "value": "12345678912345678912"
    }
    ],
  - "ship_to":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no",
    "instructions": "string",
    "geolocation":
    [
    {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
    ]
    }
  }
],
"total": 2750,
"page": 1,
"pages": 4,
"links":
{
- "first":
  {
  - "type": "string"
  },
- "last":
  {
  - "type": "string"
  },
- "prev":
  {
  - "type": "string"
  },
- "next":
  {
  - "type": "string"
  }
}

}

Purchase Label

Purchase and print a label for shipment

Authorizations:

Request Body schema: application/json

ship_to_service_point_id

string Nullable

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

ship_from_service_point_id

string Nullable

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

shipment

required

object

The shipment information used to generate the label

is_return_label

boolean

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

rma_number

string Nullable

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

charge_event

string

Enum: "carrier_default" "on_creation" "on_carrier_acceptance"

The label charge event.

outbound_label_id

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

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

test_label

boolean

Deprecated

Default: false

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

validate_address

string

Default: "no_validation"

Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

label_download_type

string

Default: "url"

Enum: "url" "inline"

There are two different ways to download a label:

Label Download Type	Description
`url`	You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
`inline`	You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.

label_format

string

Default: "pdf"

Enum: "pdf" "png" "zpl"

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

display_scheme

string

Default: "label"

Enum: "label" "qr_code" "label_and_qr_code" "paperless" "label_and_paperless"

The display format that the label should be shown in.

label_layout

string

Default: "4x6"

Enum: "4x6" "letter" "A4" "A6"

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

label_image_id

string >= 4 characters Nullable

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

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"ship_to_service_point_id": "614940",
"ship_from_service_point_id": "614940",
"shipment":
{
- "carrier_id": "se-28529731",
- "service_code": "usps_first_class_mail",
- "shipping_rule_id": "se-28529731",
- "external_order_id": "string",
- "items": [ ],
- "tax_identifiers":
  [
  - {
    "taxable_entity_type": "shipper",
    "identifier_type": "vat",
    "issuing_authority": "string",
    "value": "string"
    }
  ],
- "external_shipment_id": "string",
- "shipment_number": "string",
- "ship_date": "2018-09-23T00:00:00.000Z",
- "ship_to":
  {
  - "name": "John Doe",
  - "phone": "+1 204-253-9411 ext. 123",
  - "email": "example@example.com",
  - "company_name": "The Home Depot",
  - "address_line1": "1999 Bishop Grandin Blvd.",
  - "address_line2": "Unit 408",
  - "address_line3": "Building #7",
  - "city_locality": "Winnipeg",
  - "state_province": "Manitoba",
  - "postal_code": "78756-3717",
  - "country_code": "CA",
  - "address_residential_indicator": "no",
  - "instructions": "string",
  - "geolocation":
    [
    {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
    ]
  },
- "ship_from":
  {
  - "name": "John Doe",
  - "phone": "+1 204-253-9411 ext. 123",
  - "email": "example@example.com",
  - "company_name": "The Home Depot",
  - "address_line1": "1999 Bishop Grandin Blvd.",
  - "address_line2": "Unit 408",
  - "address_line3": "Building #7",
  - "city_locality": "Winnipeg",
  - "state_province": "Manitoba",
  - "postal_code": "78756-3717",
  - "country_code": "CA",
  - "address_residential_indicator": "no",
  - "instructions": "string"
  },
- "warehouse_id": "se-28529731",
- "return_to":
  {
  - "name": "John Doe",
  - "phone": "+1 204-253-9411 ext. 123",
  - "email": "example@example.com",
  - "company_name": "The Home Depot",
  - "address_line1": "1999 Bishop Grandin Blvd.",
  - "address_line2": "Unit 408",
  - "address_line3": "Building #7",
  - "city_locality": "Winnipeg",
  - "state_province": "Manitoba",
  - "postal_code": "78756-3717",
  - "country_code": "CA",
  - "address_residential_indicator": "no",
  - "instructions": "string"
  },
- "is_return": false,
- "confirmation": "none",
- "customs":
  {
  - "contents": "merchandise",
  - "contents_explanation": "string",
  - "non_delivery": "return_to_sender",
  - "terms_of_trade_code": "exw",
  - "declaration": "string",
  - "invoice_additional_details":
    {
    "freight_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "insurance_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "discount":
    {
    "currency": "string",
    "amount": 0
    },
    "estimated_import_charges":
    {
    "taxes":
    {
    "currency": "string",
    "amount": 0
    },
    "duties":
    {
    "currency": "string",
    "amount": 0
    }
    },
    "other_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "other_charge_description": "string",
    "invoice_number": "string"
    },
  - "importer_of_record":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA"
    },
  - "license_number": "string",
  - "certificate_number": "string",
  - "customs_items": [ ]
  },
- "advanced_options":
  {
  - "bill_to_account": null,
  - "bill_to_country_code": "CA",
  - "bill_to_party": "recipient",
  - "bill_to_postal_code": null,
  - "contains_alcohol": false,
  - "delivered_duty_paid": false,
  - "dry_ice": false,
  - "dry_ice_weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "non_machinable": false,
  - "saturday_delivery": false,
  - "fedex_freight":
    {
    "shipper_load_and_count": "string",
    "booking_confirmation": "string"
    },
  - "use_ups_ground_freight_pricing": null,
  - "freight_class": 77.5,
  - "custom_field1": null,
  - "custom_field2": null,
  - "custom_field3": null,
  - "origin_type": "pickup",
  - "additional_handling": null,
  - "shipper_release": null,
  - "collect_on_delivery":
    {
    "payment_type": "any",
    "payment_amount":
    {
    "currency": "string",
    "amount": 0
    }
    },
  - "third_party_consignee": false,
  - "dangerous_goods": false,
  - "dangerous_goods_contact":
    {
    "name": "string",
    "phone": "string"
    },
  - "windsor_framework_details":
    {
    "movement_indicator": "c2c",
    "not_at_risk": true
    },
  - "license_number": 514785,
  - "invoice_number": "IOC56888",
  - "certificate_number": 784515,
  - "delivery-as-addressed": false,
  - "return-after-first-attempt": false,
  - "regulated_content_type": "day_old_poultry"
  },
- "insurance_provider": "none",
- "order_source_code": "amazon_ca",
- "packages":
  [
  - {
    "package_id": "se-28529731",
    "package_code": "small_flat_rate_box",
    "package_name": "string",
    "weight":
    {
    "value": 0,
    "unit": "pound"
    },
    "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
    "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
    "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
    "external_package_id": "string",
    "content_description": "Hand knitted wool socks",
    "products": [ ]
    }
  ],
- "comparison_rate_type": "retail"
},
"is_return_label": true,
"rma_number": "string",
"charge_event": "carrier_default",
"outbound_label_id": "se-28529731",
"test_label": false,
"validate_address": "no_validation",
"label_download_type": "url",
"label_format": "pdf",
"display_scheme": "label",
"label_layout": "4x6",
"label_image_id": "img_DtBXupDBxREpHnwEXhTfgK"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"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":
{
- "currency": "string",
- "amount": 0
},
"insurance_cost":
{
- "currency": "string",
- "amount": 0
},
"requested_comparison_amount":
{
- "currency": "string",
- "amount": 0
},
"rate_details":
[
- {
  - "rate_detail_type": "uncategorized",
  - "carrier_description": "string",
  - "carrier_billing_code": "string",
  - "carrier_memo": "string",
  - "amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "rate_detail_attributes":
    {
    "tax_type": "vat",
    "tax_percentage": 0
    },
  - "billing_source": "string"
  }
],
"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":
{
- "type": "string"
},
"qr_code_download":
{
- "type": "string"
},
"paperless_download":
{
- "instructions": null,
- "handoff_code": null
},
"insurance_claim":
{
- "type": "string"
},
"packages":
[
- {
  - "package_id": 0,
  - "package_code": "small_flat_rate_box",
  - "weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
  - "tracking_number": "1Z932R800392060079",
  - "form_download":
    {
    "type": "string"
    },
  - "qr_code_download":
    {
    "type": "string"
    },
  - "paperless_download":
    {
    "instructions": null,
    "handoff_code": null
    },
  - "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
  - "external_package_id": "string",
  - "content_description": "Hand knitted wool socks",
  - "sequence": 0,
  - "has_label_documents": true,
  - "has_form_documents": true,
  - "has_qr_code_documents": true,
  - "has_paperless_label_documents": true,
  - "alternative_identifiers":
    [
    {
    "type": "last_mile_tracking_number",
    "value": "12345678912345678912"
    }
    ]
  }
],
"alternative_identifiers":
[
- {
  - "type": "last_mile_tracking_number",
  - "value": "12345678912345678912"
  }
],
"tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
"ship_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string",
- "geolocation":
  [
  - {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
  ]
}

}

Get Label By External Shipment ID

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

Authorizations:

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

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/labels/external_shipment_id/{external_shipment_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"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":
{
- "currency": "string",
- "amount": 0
},
"insurance_cost":
{
- "currency": "string",
- "amount": 0
},
"requested_comparison_amount":
{
- "currency": "string",
- "amount": 0
},
"rate_details":
[
- {
  - "rate_detail_type": "uncategorized",
  - "carrier_description": "string",
  - "carrier_billing_code": "string",
  - "carrier_memo": "string",
  - "amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "rate_detail_attributes":
    {
    "tax_type": "vat",
    "tax_percentage": 0
    },
  - "billing_source": "string"
  }
],
"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":
{
- "type": "string"
},
"qr_code_download":
{
- "type": "string"
},
"paperless_download":
{
- "instructions": null,
- "handoff_code": null
},
"insurance_claim":
{
- "type": "string"
},
"packages":
[
- {
  - "package_id": 0,
  - "package_code": "small_flat_rate_box",
  - "weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
  - "tracking_number": "1Z932R800392060079",
  - "form_download":
    {
    "type": "string"
    },
  - "qr_code_download":
    {
    "type": "string"
    },
  - "paperless_download":
    {
    "instructions": null,
    "handoff_code": null
    },
  - "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
  - "external_package_id": "string",
  - "content_description": "Hand knitted wool socks",
  - "sequence": 0,
  - "has_label_documents": true,
  - "has_form_documents": true,
  - "has_qr_code_documents": true,
  - "has_paperless_label_documents": true,
  - "alternative_identifiers":
    [
    {
    "type": "last_mile_tracking_number",
    "value": "12345678912345678912"
    }
    ]
  }
],
"alternative_identifiers":
[
- {
  - "type": "last_mile_tracking_number",
  - "value": "12345678912345678912"
  }
],
"tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
"ship_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string",
- "geolocation":
  [
  - {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
  ]
}

}

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:

path Parameters

rate_id

required

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

Example: se-28529731

Request Body schema: application/json

custom_field1

string

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

custom_field2

string

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

custom_field3

string

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

validate_address

string

Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

label_layout

string

Default: "4x6"

Enum: "4x6" "letter" "A4" "A6"

label_format

string

Default: "pdf"

Enum: "pdf" "png" "zpl"

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

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

Default: "label"

Enum: "label" "qr_code" "label_and_qr_code" "paperless" "label_and_paperless"

The display format that the label should be shown in.

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/labels/rates/{rate_id}

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"custom_field1": "string",
"custom_field2": "string",
"custom_field3": "string",
"validate_address": "no_validation",
"label_layout": "4x6",
"label_format": "pdf",
"label_download_type": "url",
"display_scheme": "label"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"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":
{
- "currency": "string",
- "amount": 0
},
"insurance_cost":
{
- "currency": "string",
- "amount": 0
},
"requested_comparison_amount":
{
- "currency": "string",
- "amount": 0
},
"rate_details":
[
- {
  - "rate_detail_type": "uncategorized",
  - "carrier_description": "string",
  - "carrier_billing_code": "string",
  - "carrier_memo": "string",
  - "amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "rate_detail_attributes":
    {
    "tax_type": "vat",
    "tax_percentage": 0
    },
  - "billing_source": "string"
  }
],
"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":
{
- "type": "string"
},
"qr_code_download":
{
- "type": "string"
},
"paperless_download":
{
- "instructions": null,
- "handoff_code": null
},
"insurance_claim":
{
- "type": "string"
},
"packages":
[
- {
  - "package_id": 0,
  - "package_code": "small_flat_rate_box",
  - "weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
  - "tracking_number": "1Z932R800392060079",
  - "form_download":
    {
    "type": "string"
    },
  - "qr_code_download":
    {
    "type": "string"
    },
  - "paperless_download":
    {
    "instructions": null,
    "handoff_code": null
    },
  - "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
  - "external_package_id": "string",
  - "content_description": "Hand knitted wool socks",
  - "sequence": 0,
  - "has_label_documents": true,
  - "has_form_documents": true,
  - "has_qr_code_documents": true,
  - "has_paperless_label_documents": true,
  - "alternative_identifiers":
    [
    {
    "type": "last_mile_tracking_number",
    "value": "12345678912345678912"
    }
    ]
  }
],
"alternative_identifiers":
[
- {
  - "type": "last_mile_tracking_number",
  - "value": "12345678912345678912"
  }
],
"tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
"ship_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string",
- "geolocation":
  [
  - {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
  ]
}

}

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:

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

Label creation details with inline shipment

shipment

required

object

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 Nullable

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

charge_event

string

Enum: "carrier_default" "on_creation" "on_carrier_acceptance"

The label charge event.

outbound_label_id

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

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

test_label

boolean

Deprecated

Default: false

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

validate_address

string

Default: "no_validation"

Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

label_download_type

string

Default: "url"

Enum: "url" "inline"

There are two different ways to download a label:

Label Download Type	Description
`url`	You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
`inline`	You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.

label_format

string

Default: "pdf"

Enum: "pdf" "png" "zpl"

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

display_scheme

string

Default: "label"

Enum: "label" "qr_code" "label_and_qr_code" "paperless" "label_and_paperless"

The display format that the label should be shown in.

label_layout

string

Default: "4x6"

Enum: "4x6" "letter" "A4" "A6"

label_image_id

string >= 4 characters Nullable

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

Responses

200

Label created successfully using Rate Shopper. The response includes the selected carrier_id, service_code, and rate_shopper_id that was used.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/labels/rate_shopper_id/{rate_shopper_id}

https://api.shipengine.com/v1/labels/rate_shopper_id/{rate_shopper_id}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"shipment":
{
- "ship_to":
  {
  - "name": "John Doe",
  - "company_name": "Example Corp",
  - "address_line1": "123 Main St",
  - "city_locality": "Austin",
  - "state_province": "TX",
  - "postal_code": "78701",
  - "country_code": "US",
  - "phone": "512-555-1234"
  },
- "ship_from":
  {
  - "name": "Warehouse A",
  - "address_line1": "456 Warehouse Blvd",
  - "city_locality": "Dallas",
  - "state_province": "TX",
  - "postal_code": "75001",
  - "country_code": "US"
  },
- "packages":
  [
  - {
    "weight":
    {
    "value": 5,
    "unit": "pound"
    },
    "dimensions":
    {
    "length": 12,
    "width": 8,
    "height": 6,
    "unit": "inch"
    }
    }
  ]
},
"label_format": "pdf",
"label_layout": "4x6"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"label_id": "se-123456",
"status": "completed",
"shipment_id": "se-789012",
"ship_date": "2026-02-25T00:00:00Z",
"created_at": "2026-02-25T10:30:00Z",
"shipment_cost":
{
- "currency": "usd",
- "amount": 7.33
},
"insurance_cost":
{
- "currency": "usd",
- "amount": 0
},
"tracking_number": "1Z999AA10123456784",
"is_return_label": false,
"rma_number": null,
"is_international": false,
"batch_id": "",
"carrier_id": "se-456789",
"service_code": "usps_priority_mail",
"package_code": "package",
"voided": false,
"voided_at": null,
"label_format": "pdf",
"label_layout": "4x6",
"trackable": true,
"label_image_id": null,
"carrier_code": "stamps_com",
"tracking_status": "in_transit",
"label_download":
{
},
"form_download": null,
"insurance_claim": null,
"packages": [ ],
"charge_event": "carrier_default",
"rate_shopper_id": "cheapest"

}

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:

path Parameters

shipment_id

required

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

Example: se-28529731

Request Body schema: application/json

validate_address

string

Enum: "no_validation" "validate_only" "validate_and_clean"

The possible validate address values

label_layout

string

Default: "4x6"

Enum: "4x6" "letter" "A4" "A6"

label_format

string

Default: "pdf"

Enum: "pdf" "png" "zpl"

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

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

Default: "label"

Enum: "label" "qr_code" "label_and_qr_code" "paperless" "label_and_paperless"

The display format that the label should be shown in.

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/labels/shipment/{shipment_id}

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"validate_address": "no_validation",
"label_layout": "4x6",
"label_format": "pdf",
"label_download_type": "url",
"display_scheme": "label"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"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":
{
- "currency": "string",
- "amount": 0
},
"insurance_cost":
{
- "currency": "string",
- "amount": 0
},
"requested_comparison_amount":
{
- "currency": "string",
- "amount": 0
},
"rate_details":
[
- {
  - "rate_detail_type": "uncategorized",
  - "carrier_description": "string",
  - "carrier_billing_code": "string",
  - "carrier_memo": "string",
  - "amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "rate_detail_attributes":
    {
    "tax_type": "vat",
    "tax_percentage": 0
    },
  - "billing_source": "string"
  }
],
"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":
{
- "type": "string"
},
"qr_code_download":
{
- "type": "string"
},
"paperless_download":
{
- "instructions": null,
- "handoff_code": null
},
"insurance_claim":
{
- "type": "string"
},
"packages":
[
- {
  - "package_id": 0,
  - "package_code": "small_flat_rate_box",
  - "weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
  - "tracking_number": "1Z932R800392060079",
  - "form_download":
    {
    "type": "string"
    },
  - "qr_code_download":
    {
    "type": "string"
    },
  - "paperless_download":
    {
    "instructions": null,
    "handoff_code": null
    },
  - "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
  - "external_package_id": "string",
  - "content_description": "Hand knitted wool socks",
  - "sequence": 0,
  - "has_label_documents": true,
  - "has_form_documents": true,
  - "has_qr_code_documents": true,
  - "has_paperless_label_documents": true,
  - "alternative_identifiers":
    [
    {
    "type": "last_mile_tracking_number",
    "value": "12345678912345678912"
    }
    ]
  }
],
"alternative_identifiers":
[
- {
  - "type": "last_mile_tracking_number",
  - "value": "12345678912345678912"
  }
],
"tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
"ship_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string",
- "geolocation":
  [
  - {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
  ]
}

}

Get Label By ID

Retrieve information for individual labels.

Authorizations:

path Parameters

label_id

required

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

Example: se-28529731

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

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"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":
{
- "currency": "string",
- "amount": 0
},
"insurance_cost":
{
- "currency": "string",
- "amount": 0
},
"requested_comparison_amount":
{
- "currency": "string",
- "amount": 0
},
"rate_details":
[
- {
  - "rate_detail_type": "uncategorized",
  - "carrier_description": "string",
  - "carrier_billing_code": "string",
  - "carrier_memo": "string",
  - "amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "rate_detail_attributes":
    {
    "tax_type": "vat",
    "tax_percentage": 0
    },
  - "billing_source": "string"
  }
],
"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":
{
- "type": "string"
},
"qr_code_download":
{
- "type": "string"
},
"paperless_download":
{
- "instructions": null,
- "handoff_code": null
},
"insurance_claim":
{
- "type": "string"
},
"packages":
[
- {
  - "package_id": 0,
  - "package_code": "small_flat_rate_box",
  - "weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
  - "tracking_number": "1Z932R800392060079",
  - "form_download":
    {
    "type": "string"
    },
  - "qr_code_download":
    {
    "type": "string"
    },
  - "paperless_download":
    {
    "instructions": null,
    "handoff_code": null
    },
  - "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
  - "external_package_id": "string",
  - "content_description": "Hand knitted wool socks",
  - "sequence": 0,
  - "has_label_documents": true,
  - "has_form_documents": true,
  - "has_qr_code_documents": true,
  - "has_paperless_label_documents": true,
  - "alternative_identifiers":
    [
    {
    "type": "last_mile_tracking_number",
    "value": "12345678912345678912"
    }
    ]
  }
],
"alternative_identifiers":
[
- {
  - "type": "last_mile_tracking_number",
  - "value": "12345678912345678912"
  }
],
"tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
"ship_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string",
- "geolocation":
  [
  - {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
  ]
}

}

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:

path Parameters

label_id

required

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

Example: se-28529731

Request Body schema: application/json

charge_event

string

Enum: "carrier_default" "on_creation" "on_carrier_acceptance"

The label charge event.

label_layout

string

Default: "4x6"

Enum: "4x6" "letter" "A4" "A6"

label_format

string

Default: "pdf"

Enum: "pdf" "png" "zpl"

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

label_download_type

string

Default: "url"

Enum: "url" "inline"

There are two different ways to download a label:

Label Download Type	Description
`url`	You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
`inline`	You will receive the Base64-encoded label as part of the response. No need for a second request to download the label.

display_scheme

string

Default: "label"

Enum: "label" "qr_code" "label_and_qr_code" "paperless" "label_and_paperless"

The display format that the label should be shown in.

label_image_id

string >= 4 characters Nullable

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

rma_number

string Nullable

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

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/labels/{label_id}/return

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

Request samples

Payload

Content type

application/json

Example

Create a return label with a specific RMA number

Copy

Expand all Collapse all

{

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

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"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":
{
- "currency": "string",
- "amount": 0
},
"insurance_cost":
{
- "currency": "string",
- "amount": 0
},
"requested_comparison_amount":
{
- "currency": "string",
- "amount": 0
},
"rate_details":
[
- {
  - "rate_detail_type": "uncategorized",
  - "carrier_description": "string",
  - "carrier_billing_code": "string",
  - "carrier_memo": "string",
  - "amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "rate_detail_attributes":
    {
    "tax_type": "vat",
    "tax_percentage": 0
    },
  - "billing_source": "string"
  }
],
"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":
{
- "type": "string"
},
"qr_code_download":
{
- "type": "string"
},
"paperless_download":
{
- "instructions": null,
- "handoff_code": null
},
"insurance_claim":
{
- "type": "string"
},
"packages":
[
- {
  - "package_id": 0,
  - "package_code": "small_flat_rate_box",
  - "weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
  - "tracking_number": "1Z932R800392060079",
  - "form_download":
    {
    "type": "string"
    },
  - "qr_code_download":
    {
    "type": "string"
    },
  - "paperless_download":
    {
    "instructions": null,
    "handoff_code": null
    },
  - "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
  - "external_package_id": "string",
  - "content_description": "Hand knitted wool socks",
  - "sequence": 0,
  - "has_label_documents": true,
  - "has_form_documents": true,
  - "has_qr_code_documents": true,
  - "has_paperless_label_documents": true,
  - "alternative_identifiers":
    [
    {
    "type": "last_mile_tracking_number",
    "value": "12345678912345678912"
    }
    ]
  }
],
"alternative_identifiers":
[
- {
  - "type": "last_mile_tracking_number",
  - "value": "12345678912345678912"
  }
],
"tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
"ship_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string",
- "geolocation":
  [
  - {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
  ]
}

}

Get Label Tracking Information

Retrieve the label's tracking information

Authorizations:

path Parameters

label_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/labels/{label_id}/track

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"tracking_number": "1Z932R800392060079",
"tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
"status_code": "DE",
"status_detail_code": "DELIVERED",
"carrier_code": "dhl_express",
"carrier_id": 0,
"status_description": "Delivered",
"status_detail_description": "Your 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":
[
- {
  - "occurred_at": "2018-09-23T15:00:00.000Z",
  - "carrier_occurred_at": "2018-09-23T15:00:00.000Z",
  - "description": "Delivered, In/At Mailbox",
  - "city_locality": "AUSTIN",
  - "state_province": "TX",
  - "postal_code": 78756,
  - "country_code": "CA",
  - "company_name": "Stamps.com",
  - "signer": "string",
  - "event_code": "string",
  - "carrier_detail_code": "OT",
  - "status_code": "IT",
  - "status_detail_code": "IN_TRANSIT",
  - "status_description": "In Transit",
  - "status_detail_description": "Your shipment is on its way between the carrier hubs.",
  - "carrier_status_code": 1,
  - "carrier_status_description": "Your item was delivered in or at the mailbox at 9:10 am on March",
  - "latitude": -90,
  - "longitude": -180,
  }
]

}

Void a Label By ID

Void a label by ID to get a refund.

Authorizations:

path Parameters

label_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/labels/{label_id}/void

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"approved": false,
"message": "Unable to delete FedEx shipment. Unable to retrieve record from database.",
"reason_code": "label_not_found_within_void_period"

}

Manifests

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:

query Parameters

warehouse_id	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: warehouse_id=se-28529731 Warehouse ID
ship_date_start	string <date-time> Example: ship_date_start=2018-09-23T15:00:00.000Z ship date start range
ship_date_end	string <date-time> Example: ship_date_end=2018-09-23T15:00:00.000Z ship date end range
created_at_start	string <date-time> Example: created_at_start=2019-03-12T19:24:13.657Z Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time)
created_at_end	string <date-time> Example: created_at_end=2019-03-12T19:24:13.657Z Used to create a filter for when a resource was created, (ex. A shipment that was created before a certain time)
carrier_id	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: carrier_id=se-28529731 Carrier ID
page	integer <int32> >= 1 Default: 1 Example: page=2 Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.
page_size	integer <int32> >= 1 Default: 25 Example: page_size=50 The number of results to return per response.
label_ids	Array of strings (se_id) Example: label_ids=se-28529731 Array of label ids

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"manifests": [ ],
"total": 3,
"page": 3,
"pages": 4,
"links":
{
- "first":
  {
  - "type": "string"
  },
- "last":
  {
  - "type": "string"
  },
- "prev":
  {
  - "type": "string"
  },
- "next":
  {
  - "type": "string"
  }
}

}

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:

Request Body schema: application/json

One of

create_manifest_by_object_request_body
create_manifest_label_ids_request_body

carrier_id required	string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ A string that uniquely identifies the carrier
excluded_label_ids	Array of strings The list of label ids to exclude from the manifest
label_ids	Array of strings The list of label ids to include for the manifest
warehouse_id required	string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ A string that uniquely identifies the warehouse
ship_date required	string <date-time> non-empty The ship date that the shipment will be sent out on

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

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

Request samples

Payload

Content type

application/json

Example

Copy

Expand all Collapse all

{

"carrier_id": "se-28529731",
"excluded_label_ids":
[
- "se-28529731"
],
"label_ids":
[
- "se-28529731"
],
"warehouse_id": "se-28529731",
"ship_date": "2018-09-23T15:00:00.000Z"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"manifests":
[
- {
  - "manifest_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":
    [
    "se-28529731"
    ],
  - "warehouse_id": "se-28529731",
  - "submission_id": "9475711899564878915476",
  - "carrier_id": "se-28529731",
  }
],
"manifest_requests":
[
- {
  - "manifest_request_id": "se-28529731",
  - "status": "in_progress"
  }
],
"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":
[
- "se-28529731"
],
"request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
"errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
]

}

Get Manifest By Id

Authorizations:

path Parameters

manifest_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/manifests/{manifest_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"manifest_id": "se-28529731",
"form_id": "se-28529731",
"created_at": "2019-07-12T13:37:39.050Z",
"ship_date": "2019-07-12T13:37:39.050Z",
"shipments": 100,
"label_ids":
[
- "se-28529731"
],
"warehouse_id": "se-28529731",
"submission_id": "9475711899564878915476",
"carrier_id": "se-28529731",
"manifest_download":
{
}

}

Get Manifest Request By Id

Authorizations:

path Parameters

manifest_request_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/manifests/requests/{manifest_request_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"manifests":
[
- {
  - "manifest_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":
    [
    "se-28529731"
    ],
  - "warehouse_id": "se-28529731",
  - "submission_id": "9475711899564878915476",
  - "carrier_id": "se-28529731",
  }
],
"manifest_requests":
[
- {
  - "manifest_request_id": "se-28529731",
  - "status": "in_progress"
  }
],
"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":
[
- "se-28529731"
],
"request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
"errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
]

}

Package Pickups

Scheduled package pickups

List Scheduled Pickups

List all pickups that have been scheduled for this carrier

Authorizations:

query Parameters

carrier_id	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: carrier_id=se-28529731 Carrier ID
warehouse_id	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: warehouse_id=se-28529731 Warehouse ID
created_at_start	string <date-time> Example: created_at_start=2019-03-12T19:24:13.657Z Only return scheduled pickups that were created on or after a specific date/time
created_at_end	string <date-time> Example: created_at_end=2019-03-12T19:24:13.657Z Only return scheduled pickups that were created on or before a specific date/time
page	integer <int32> >= 1 Default: 1 Example: page=2 Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.
page_size	integer <int32> >= 1 Default: 25 Example: page_size=50 The number of results to return per response.

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"pickups":
[
- {
  - "pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW",
  - "label_ids":
    [
    "se-28529731"
    ],
  - "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":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no"
    },
  - "contact_details":
    {
    "name": "string",
    "email": "john.doe@example.com",
    "phone": "strings"
    },
  - "pickup_notes": "string",
  - "pickup_windows":
    [
    {
    "start_at": "2018-09-23T15:00:00.000Z",
    "end_at": "2018-09-23T15:00:00.000Z"
    }
    ]
  }
],
"total": 3,
"page": 3,
"pages": 4,
"links":
{
- "first":
  {
  - "type": "string"
  },
- "last":
  {
  - "type": "string"
  },
- "prev":
  {
  - "type": "string"
  },
- "next":
  {
  - "type": "string"
  }
},
"request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
"errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
]

}

Schedule a Pickup

Schedule a package pickup with a carrier

Authorizations:

Request Body schema: application/json

label_ids required	Array of strings Label IDs that will be included in the pickup request
contact_details required
pickup_notes	string >= 0 characters Used by some carriers to give special instructions for a package pickup
pickup_window required	object (pickup_window) The desired time range for the package pickup.

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"label_ids":
[
- "se-28529731"
],
"contact_details":
{
- "name": "string",
- "email": "john.doe@example.com",
- "phone": "strings"
},
"pickup_notes": "string",
"pickup_window":
{
- "start_at": "2018-09-23T15:00:00.000Z",
- "end_at": "2018-09-23T15:00:00.000Z"
}

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW",
"label_ids":
[
- "se-28529731"
],
"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":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no"
},
"contact_details":
{
- "name": "string",
- "email": "john.doe@example.com",
- "phone": "strings"
},
"pickup_notes": "string",
"pickup_windows":
[
- {
  - "start_at": "2018-09-23T15:00:00.000Z",
  - "end_at": "2018-09-23T15:00:00.000Z"
  }
],
"request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
"errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
]

}

Get Pickup By ID

Authorizations:

path Parameters

pickup_id

required

string (pickup_resource_id) >= 4 characters

Example: pik_3YcKU5zdtJuCqoeNwyqqbW

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/pickups/{pickup_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW",
"label_ids":
[
- "se-28529731"
],
"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":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no"
},
"contact_details":
{
- "name": "string",
- "email": "john.doe@example.com",
- "phone": "strings"
},
"pickup_notes": "string",
"pickup_windows":
[
- {
  - "start_at": "2018-09-23T15:00:00.000Z",
  - "end_at": "2018-09-23T15:00:00.000Z"
  }
],
"request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
"errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
]

}

Delete a Scheduled Pickup

Delete a previously-scheduled pickup by ID

Authorizations:

path Parameters

pickup_id

required

string (pickup_resource_id) >= 4 characters

Example: pik_3YcKU5zdtJuCqoeNwyqqbW

Responses

200

Return the pickup_id of the scheduled pickup that was successfully deleted

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

delete/v1/pickups/{pickup_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009",
"errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
],
"pickup_id": "pik_3YcKU5zdtJuCqoeNwyqqbW"

}

Package Types

List Custom Package Types

List the custom package types associated with the account

Authorizations:

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"packages":
[
- {
  - "package_id": "se-28529731",
  - "package_code": "small_flat_rate_box",
  - "name": "laptop_box",
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "description": "Packaging for laptops"
  }
]

}

Create Custom Package Type

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

Authorizations:

Request Body schema: application/json

package_id	string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ A string that uniquely identifies the package.
package_code required	string [ 1 .. 50 ] characters ^[a-z0-9]+(_[a-z0-9]+)*$ A package type, such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc. Use the code `package` for custom or unknown package types.
name required	string [ 1 .. 50 ] characters
dimensions	object The custom dimensions for the package.
description	string <= 500 characters Nullable Provides a helpful description for the custom package.

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"package_id": "se-28529731",
"package_code": "small_flat_rate_box",
"name": "laptop_box",
"dimensions":
{
- "unit": "inch",
- "length": 0,
- "width": 0,
- "height": 0
},
"description": "Packaging for laptops"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"package_id": "se-28529731",
"package_code": "small_flat_rate_box",
"name": "laptop_box",
"dimensions":
{
- "unit": "inch",
- "length": 0,
- "width": 0,
- "height": 0
},
"description": "Packaging for laptops"

}

Get Custom Package Type By ID

Get Custom Package Type by ID

Authorizations:

path Parameters

package_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/packages/{package_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"package_id": "se-28529731",
"package_code": "small_flat_rate_box",
"name": "laptop_box",
"dimensions":
{
- "unit": "inch",
- "length": 0,
- "width": 0,
- "height": 0
},
"description": "Packaging for laptops"

}

Update Custom Package Type By ID

Update the custom package type object by ID

Authorizations:

path Parameters

package_id

required

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

Example: se-28529731

Request Body schema: application/json

package_id	string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ A string that uniquely identifies the package.
package_code required	string [ 1 .. 50 ] characters ^[a-z0-9]+(_[a-z0-9]+)*$ A package type, such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc. Use the code `package` for custom or unknown package types.
name required	string [ 1 .. 50 ] characters
dimensions	object The custom dimensions for the package.
description	string <= 500 characters Nullable Provides a helpful description for the custom package.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/packages/{package_id}

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"package_id": "se-28529731",
"package_code": "small_flat_rate_box",
"name": "laptop_box",
"dimensions":
{
- "unit": "inch",
- "length": 0,
- "width": 0,
- "height": 0
},
"description": "Packaging for laptops"

}

Response samples

Delete A Custom Package By ID

Delete a custom package using the ID

Authorizations:

path Parameters

package_id

required

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

Example: se-28529731

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

delete/v1/packages/{package_id}

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

Response samples

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.

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:

Request Body schema: application/json

One of

shipment_id_request
rate_shipment_request

shipment_id required	string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ A string that uniquely identifies the shipment
ship_to_service_point_id	string Nullable A unique identifier for a carrier service point where the shipment will be delivered by the carrier. This will take precedence over a shipment's ship to address.
ship_from_service_point_id	string Nullable A unique identifier for a carrier drop off point where a merchant plans to deliver packages. This will take precedence over a shipment's ship from address.
rate_options

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"shipment_id": "se-28529731",
"ship_to_service_point_id": "614940",
"ship_from_service_point_id": "614940",
"rate_options":
{
- "carrier_ids":
  [
  - "se-28529731"
  ],
- "package_types":
  [
  - "string"
  ],
- "service_codes":
  [
  - "string"
  ],
- "calculate_tax_amount": true,
- "preferred_currency": "string",
- "is_return": true,
- "rate_type": "check"
}

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"shipment_id": "se-28529731",
"carrier_id": "se-28529731",
"service_code": "usps_first_class_mail",
"shipping_rule_id": "se-28529731",
"external_order_id": "string",
"items": [ ],
"tax_identifiers":
[
- {
  - "taxable_entity_type": "shipper",
  - "identifier_type": "vat",
  - "issuing_authority": "string",
  - "value": "string"
  }
],
"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":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string",
- "geolocation":
  [
  - {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
  ]
},
"ship_from":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string"
},
"warehouse_id": "se-28529731",
"return_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string"
},
"is_return": false,
"confirmation": "none",
"customs":
{
- "contents": "merchandise",
- "contents_explanation": "string",
- "non_delivery": "return_to_sender",
- "terms_of_trade_code": "exw",
- "declaration": "string",
- "invoice_additional_details":
  {
  - "freight_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "insurance_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "discount":
    {
    "currency": "string",
    "amount": 0
    },
  - "estimated_import_charges":
    {
    "taxes":
    {
    "currency": "string",
    "amount": 0
    },
    "duties":
    {
    "currency": "string",
    "amount": 0
    }
    },
  - "other_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "other_charge_description": "string",
  - "invoice_number": "string"
  },
- "importer_of_record":
  {
  - "name": "John Doe",
  - "phone": "+1 204-253-9411 ext. 123",
  - "email": "example@example.com",
  - "company_name": "The Home Depot",
  - "address_line1": "1999 Bishop Grandin Blvd.",
  - "address_line2": "Unit 408",
  - "address_line3": "Building #7",
  - "city_locality": "Winnipeg",
  - "state_province": "Manitoba",
  - "postal_code": "78756-3717",
  - "country_code": "CA"
  },
- "license_number": "string",
- "certificate_number": "string",
- "customs_items": [ ]
},
"advanced_options":
{
- "bill_to_account": null,
- "bill_to_country_code": "CA",
- "bill_to_party": "recipient",
- "bill_to_postal_code": null,
- "contains_alcohol": false,
- "delivered_duty_paid": false,
- "dry_ice": false,
- "dry_ice_weight":
  {
  - "value": 0,
  - "unit": "pound"
  },
- "non_machinable": false,
- "saturday_delivery": false,
- "fedex_freight":
  {
  - "shipper_load_and_count": "string",
  - "booking_confirmation": "string"
  },
- "use_ups_ground_freight_pricing": null,
- "freight_class": 77.5,
- "custom_field1": null,
- "custom_field2": null,
- "custom_field3": null,
- "origin_type": "pickup",
- "additional_handling": null,
- "shipper_release": null,
- "collect_on_delivery":
  {
  - "payment_type": "any",
  - "payment_amount":
    {
    "currency": "string",
    "amount": 0
    }
  },
- "third_party_consignee": false,
- "dangerous_goods": false,
- "dangerous_goods_contact":
  {
  - "name": "string",
  - "phone": "string"
  },
- "windsor_framework_details":
  {
  - "movement_indicator": "c2c",
  - "not_at_risk": true
  },
- "license_number": 514785,
- "invoice_number": "IOC56888",
- "certificate_number": 784515,
- "delivery-as-addressed": false,
- "return-after-first-attempt": false,
- "regulated_content_type": "day_old_poultry"
},
"insurance_provider": "none",
"tags": [ ],
"order_source_code": "amazon_ca",
"packages":
[
- {
  - "shipment_package_id": "se-28529731",
  - "package_id": "se-28529731",
  - "package_code": "small_flat_rate_box",
  - "package_name": "string",
  - "weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
  - "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
  - "external_package_id": "string",
  - "tracking_number": "1Z932R800392060079",
  - "content_description": "Hand knitted wool socks",
  - "products": [ ]
  }
],
"total_weight":
{
- "value": 0,
- "unit": "pound"
},
"comparison_rate_type": "retail",
"zone": 6,
"rate_response":
{
- "rates":
  [
  - {
    "rate_id": "se-28529731",
    "rate_type": "check",
    "carrier_id": "se-28529731",
    "shipping_amount":
    {
    "currency": "string",
    "amount": 0
    },
    "insurance_amount":
    {
    "currency": "string",
    "amount": 0
    },
    "confirmation_amount":
    {
    "currency": "string",
    "amount": 0
    },
    "other_amount":
    {
    "currency": "string",
    "amount": 0
    },
    "requested_comparison_amount":
    {
    "currency": "string",
    "amount": 0
    },
    "tax_amount":
    {
    "currency": "string",
    "amount": 0
    },
    "rate_details":
    [
    {
    "rate_detail_type": "uncategorized",
    "carrier_description": "string",
    "carrier_billing_code": "string",
    "carrier_memo": "string",
    "amount":
    {
    "currency": "string",
    "amount": 0
    },
    "rate_detail_attributes":
    {
    "tax_type": "vat",
    "tax_percentage": 0
    },
    "billing_source": "string"
    }
    ],
    "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": "2026-03-18T01:40:39Z",
    "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":
    [
    "string"
    ],
    "error_messages":
    [
    "string"
    ],
    "rate_attributes":
    [
    "best_value"
    ]
    }
  ],
- "invalid_rates": [ ],
- "rate_request_id": "se-28529731",
- "shipment_id": "se-28529731",
- "created_at": "se-28529731",
- "status": "working",
- "errors":
  [
  - {
    "error_source": "carrier",
    "error_type": "account_status",
    "error_code": "auto_fund_not_supported",
    "message": "Body of request cannot be null.",
    "carrier_id": "se-28529731",
    "carrier_code": "dhl_express",
    "field_name": "shipment.ship_to.phone_number"
    }
  ]
}

}

Get Bulk Rates

Authorizations:

Request Body schema: application/json

One of

rate_request_by_shipment_ids
rate_request_by_shipments

shipment_ids required	Array of strings The array of shipment IDs
ship_to_service_point_id	string Nullable A unique identifier for a carrier service point where the shipment will be delivered by the carrier. This will take precedence over a shipment's ship to address.
ship_from_service_point_id	string Nullable A unique identifier for a carrier drop off point where a merchant plans to deliver packages. This will take precedence over a shipment's ship from address.
rate_options required

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

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

Request samples

Payload

Content type

application/json

Example

Copy

Expand all Collapse all

{

"shipment_ids":
[
- "se-28529731"
],
"ship_to_service_point_id": "614940",
"ship_from_service_point_id": "614940",
"rate_options":
{
- "carrier_ids":
  [
  - "se-28529731"
  ],
- "package_types":
  [
  - "string"
  ],
- "service_codes":
  [
  - "string"
  ],
- "calculate_tax_amount": true,
- "preferred_currency": "string",
- "is_return": true,
- "rate_type": "check"
}

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

[

{
- "rate_request_id": "se-28529731",
- "shipment_id": "se-28529731",
- "created_at": "2018-09-23T15:00:00.000Z",
- "status": "working",
- "errors":
  [
  - {
    "error_source": "carrier",
    "error_type": "account_status",
    "error_code": "auto_fund_not_supported",
    "message": "Body of request cannot be null.",
    "carrier_id": "se-28529731",
    "carrier_code": "dhl_express",
    "field_name": "shipment.ship_to.phone_number"
    }
  ]
}

]

Estimate Rates

Authorizations:

Request Body schema: application/json

One of

rate_estimate_by_carrier_id
rate_estimate_by_carrier_ids

carrier_id	string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Deprecated A string that uniquely identifies the carrier
from_country_code required	string 2 characters A two-letter ISO 3166-1 country code
from_postal_code required	string non-empty postal code
from_city_locality required	string non-empty from postal code
from_state_province required	string non-empty From state province
to_country_code required	string 2 characters A two-letter ISO 3166-1 country code
to_postal_code required	string non-empty postal code
to_city_locality required	string non-empty The city locality the package is being shipped to
to_state_province required	string non-empty To state province
weight required	object The weight of the package
dimensions	object The dimensions of the package
confirmation	string Enum: "none" "delivery" "signature" "adult_signature" "direct_signature" "delivery_mailed" "verbal_confirmation" "delivery_code" "age_verification_16_plus" The possible delivery confirmation values
address_residential_indicator	string Enum: "unknown" "yes" "no" Indicates whether an address is residential.
ship_date required	string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z\|[-+]\d{2}:\d{2})$ ship date

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

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

Request samples

Payload

Content type

application/json

Example

Copy

Expand all Collapse all

{

"carrier_id": "se-28529731",
"from_country_code": "CA",
"from_postal_code": "78756-3717",
"from_city_locality": "Austin",
"from_state_province": "Austin",
"to_country_code": "CA",
"to_postal_code": "78756-3717",
"to_city_locality": "Austin",
"to_state_province": "Houston",
"weight":
{
- "value": 0,
- "unit": "pound"
},
"dimensions":
{
- "unit": "inch",
- "length": 0,
- "width": 0,
- "height": 0
},
"confirmation": "none",
"address_residential_indicator": "unknown",
"ship_date": "2018-09-23T15:00:00.000Z"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

[

{
- "rate_type": "check",
- "carrier_id": "se-28529731",
- "shipping_amount":
  {
  - "currency": "string",
  - "amount": 0
  },
- "insurance_amount":
  {
  - "currency": "string",
  - "amount": 0
  },
- "confirmation_amount":
  {
  - "currency": "string",
  - "amount": 0
  },
- "other_amount":
  {
  - "currency": "string",
  - "amount": 0
  },
- "tax_amount":
  {
  - "currency": "string",
  - "amount": 0
  },
- "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": "2026-03-18T01:40:39Z",
- "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":
  [
  - "string"
  ],
- "error_messages":
  [
  - "string"
  ],
- "rate_attributes":
  [
  - "best_value"
  ]
}

]

Get Rate By ID

Retrieve a previously queried rate by its ID

Authorizations:

path Parameters

rate_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"rate_id": "se-28529731",
"rate_type": "check",
"carrier_id": "se-28529731",
"shipping_amount":
{
- "currency": "string",
- "amount": 0
},
"insurance_amount":
{
- "currency": "string",
- "amount": 0
},
"confirmation_amount":
{
- "currency": "string",
- "amount": 0
},
"other_amount":
{
- "currency": "string",
- "amount": 0
},
"requested_comparison_amount":
{
- "currency": "string",
- "amount": 0
},
"tax_amount":
{
- "currency": "string",
- "amount": 0
},
"rate_details":
[
- {
  - "rate_detail_type": "uncategorized",
  - "carrier_description": "string",
  - "carrier_billing_code": "string",
  - "carrier_memo": "string",
  - "amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "rate_detail_attributes":
    {
    "tax_type": "vat",
    "tax_percentage": 0
    },
  - "billing_source": "string"
  }
],
"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": "2026-03-18T01:40:39Z",
"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":
[
- "string"
],
"error_messages":
[
- "string"
]

}

Service Points

List Service Points

List carrier service points by location

Authorizations:

Request Body schema: application/json

One of

get_service_points_request_body

address_query	string Unstructured text to search for service points by.
address	object Structured address to search by.
providers required	Array of objects An array of shipping service providers and service codes
lat	number <double> The latitude of the point. Represented as signed degrees. Required if long is provided. http://www.geomidpoint.com/latlon.html
long	number <double> The longitude of the point. Represented as signed degrees. Required if lat is provided. http://www.geomidpoint.com/latlon.html
radius	integer <int32> Search radius in kilometers
max_results	integer <int32> The maximum number of service points to return
shipment	object Shipment information to be used for service point selection

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/service_points/list

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"address_query": "177A Bleecker Street New York",
"address":
{
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "string",
- "address_line3": "string",
- "city_locality": "string",
- "state_province": "string",
- "postal_code": "78756-3717",
- "country_code": "CA"
},
"providers":
[
- {
  - "carrier_id": "se-123456",
  - "service_code":
    [
    "chronoclassic"
    ]
  }
],
"lat": 48.874518928233094,
"long": 2.3591775711639404,
"radius": 500,
"max_results": 25,
"shipment":
{
- "total_weight":
  {
  - "value": 0,
  - "unit": "pound"
  },
- "packages":
  [
  - {
    "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    }
    }
  ]
}

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"lat": 48.842608,
"long": 0.032875,
"service_points":
[
- {
  - "carrier_code": "dhl_express",
  - "service_codes":
    [
    "chronoclassic"
    ],
  - "service_point_id": "614940",
  - "company_name": "My fancy company name",
  - "address_line1": "PLACE DU CANADA",
  - "city_locality": "TRUN",
  - "state_province": "TRUN",
  - "postal_code": "78756-3717",
  - "country_code": "CA",
  - "phone_number": "555-555-5555",
  - "lat": 48.842608,
  - "long": 0.032875,
  - "distance_in_meters": 728.9959308847579,
  - "hours_of_operation":
    {
    "monday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
    "tuesday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
    "wednesday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
    "thursday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
    "friday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
    "saturday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
    "sunday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ]
    },
  - "features":
    [
    "drop_off_point"
    ],
  - "type": "pudo"
  }
],
"errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
]

}

Get Service Point By ID

Returns a carrier service point by using the service_point_id

Authorizations:

path Parameters

carrier_code required	string non-empty Example: stamps_com
country_code required	string 2 characters Example: CA
service_point_id required

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/service_points/{carrier_code}/{country_code}/{service_point_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"service_point":
{
- "carrier_code": "dhl_express",
- "service_codes":
  [
  - "string"
  ],
- "service_point_id": "614940",
- "company_name": "My fancy company name",
- "address_line1": "PLACE DU CANADA",
- "city_locality": "TRUN",
- "state_province": "TRUN",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "phone_number": "555-555-5555",
- "lat": 48.842608,
- "long": 0.032875,
- "hours_of_operation":
  {
  - "monday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
  - "tuesday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
  - "wednesday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
  - "thursday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
  - "friday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
  - "saturday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ],
  - "sunday":
    [
    {
    "open": "09:15",
    "close": "12:00"
    }
    ]
  },
- "features":
  [
  - "drop_off_point"
  ],
- "type": "pudo"
}

}

Shipments

List Shipments

Authorizations:

query Parameters

shipment_status	string (shipment_status) Enum: "pending" "processing" "label_purchased" "cancelled" The possible shipment status values
batch_id	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: batch_id=se-28529731 Batch ID
tag	string non-empty Example: tag=Letters_to_santa Search for shipments based on the custom tag added to the shipment object
created_at_start	string <date-time> Example: created_at_start=2019-03-12T19:24:13.657Z Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time)
created_at_end	string <date-time> Example: created_at_end=2019-03-12T19:24:13.657Z Used to create a filter for when a resource was created, (ex. A shipment that was created before a certain time)
modified_at_start	string <date-time> Example: modified_at_start=2019-03-12T19:24:13.657Z Used to create a filter for when a resource was modified (ex. A shipment that was modified after a certain time)
modified_at_end	string <date-time> Example: modified_at_end=2019-03-12T19:24:13.657Z Used to create a filter for when a resource was modified (ex. A shipment that was modified before a certain time)
page	integer <int32> >= 1 Default: 1 Example: page=2 Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.
page_size	integer <int32> >= 1 Default: 25 Example: page_size=50 The number of results to return per response.
sales_order_id	string Sales Order ID
sort_dir	string Default: "desc" Enum: "asc" "desc" Controls the sort order of the query.
sort_by	string (shipments_sort_by) Enum: "modified_at" "created_at" Example: sort_by=modified_at The possible shipments sort by values

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"shipments":
[
- {
  - "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":
    [
    {
    "taxable_entity_type": "shipper",
    "identifier_type": "vat",
    "issuing_authority": "string",
    "value": "string"
    }
    ],
  - "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":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no",
    "instructions": "string",
    "geolocation":
    [
    {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
    ]
    },
  - "ship_from":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no",
    "instructions": "string"
    },
  - "warehouse_id": "se-28529731",
  - "return_to":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no",
    "instructions": "string"
    },
  - "is_return": false,
  - "confirmation": "none",
  - "customs":
    {
    "contents": "merchandise",
    "contents_explanation": "string",
    "non_delivery": "return_to_sender",
    "terms_of_trade_code": "exw",
    "declaration": "string",
    "invoice_additional_details":
    {
    "freight_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "insurance_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "discount":
    {
    "currency": "string",
    "amount": 0
    },
    "estimated_import_charges":
    {
    "taxes":
    {
    "currency": "string",
    "amount": 0
    },
    "duties":
    {
    "currency": "string",
    "amount": 0
    }
    },
    "other_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "other_charge_description": "string",
    "invoice_number": "string"
    },
    "importer_of_record":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA"
    },
    "license_number": "string",
    "certificate_number": "string",
    "customs_items": [ ]
    },
  - "advanced_options":
    {
    "bill_to_account": null,
    "bill_to_country_code": "CA",
    "bill_to_party": "recipient",
    "bill_to_postal_code": null,
    "contains_alcohol": false,
    "delivered_duty_paid": false,
    "dry_ice": false,
    "dry_ice_weight":
    {
    "value": 0,
    "unit": "pound"
    },
    "non_machinable": false,
    "saturday_delivery": false,
    "fedex_freight":
    {
    "shipper_load_and_count": "string",
    "booking_confirmation": "string"
    },
    "use_ups_ground_freight_pricing": null,
    "freight_class": 77.5,
    "custom_field1": null,
    "custom_field2": null,
    "custom_field3": null,
    "origin_type": "pickup",
    "additional_handling": null,
    "shipper_release": null,
    "collect_on_delivery":
    {
    "payment_type": "any",
    "payment_amount":
    {
    "currency": "string",
    "amount": 0
    }
    },
    "third_party_consignee": false,
    "dangerous_goods": false,
    "dangerous_goods_contact":
    {
    "name": "string",
    "phone": "string"
    },
    "windsor_framework_details":
    {
    "movement_indicator": "c2c",
    "not_at_risk": true
    },
    "license_number": 514785,
    "invoice_number": "IOC56888",
    "certificate_number": 784515,
    "delivery-as-addressed": false,
    "return-after-first-attempt": false,
    "regulated_content_type": "day_old_poultry"
    },
  - "insurance_provider": "none",
  - "tags": [ ],
  - "order_source_code": "amazon_ca",
  - "packages":
    [
    {
    "shipment_package_id": "se-28529731",
    "package_id": "se-28529731",
    "package_code": "small_flat_rate_box",
    "package_name": "string",
    "weight":
    {
    "value": 0,
    "unit": "pound"
    },
    "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
    "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
    "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
    "external_package_id": "string",
    "tracking_number": "1Z932R800392060079",
    "content_description": "Hand knitted wool socks",
    "products": [ ]
    }
    ],
  - "total_weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "comparison_rate_type": "retail",
  - "zone": 6
  }
],
"total": 1990,
"page": "????",
"pages": 1,
"links":
{
- "first":
  {
  - "type": "string"
  },
- "last":
  {
  - "type": "string"
  },
- "prev":
  {
  - "type": "string"
  },
- "next":
  {
  - "type": "string"
  }
}

}

Create Shipments

Create one or multiple shipments.

Authorizations:

Request Body schema: application/json

shipments

required

Array of objects non-empty

An array of shipments to be created.

Responses

200

The requested object creation was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"shipments":
[
- {
  - "validate_address": "no_validation",
  - "carrier_id": "se-28529731",
  - "service_code": "usps_first_class_mail",
  - "shipping_rule_id": "se-28529731",
  - "external_order_id": "string",
  - "items": [ ],
  - "tax_identifiers":
    [
    {
    "taxable_entity_type": "shipper",
    "identifier_type": "vat",
    "issuing_authority": "string",
    "value": "string"
    }
    ],
  - "external_shipment_id": "string",
  - "shipment_number": "string",
  - "ship_date": "2018-09-23T00:00:00.000Z",
  - "ship_to":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no",
    "instructions": "string",
    "geolocation":
    [
    {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
    ]
    },
  - "ship_from":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no",
    "instructions": "string"
    },
  - "warehouse_id": "se-28529731",
  - "return_to":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no",
    "instructions": "string"
    },
  - "is_return": false,
  - "confirmation": "none",
  - "customs":
    {
    "contents": "merchandise",
    "contents_explanation": "string",
    "non_delivery": "return_to_sender",
    "terms_of_trade_code": "exw",
    "declaration": "string",
    "invoice_additional_details":
    {
    "freight_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "insurance_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "discount":
    {
    "currency": "string",
    "amount": 0
    },
    "estimated_import_charges":
    {
    "taxes":
    {
    "currency": "string",
    "amount": 0
    },
    "duties":
    {
    "currency": "string",
    "amount": 0
    }
    },
    "other_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "other_charge_description": "string",
    "invoice_number": "string"
    },
    "importer_of_record":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA"
    },
    "license_number": "string",
    "certificate_number": "string",
    "customs_items": [ ]
    },
  - "advanced_options":
    {
    "bill_to_account": null,
    "bill_to_country_code": "CA",
    "bill_to_party": "recipient",
    "bill_to_postal_code": null,
    "contains_alcohol": false,
    "delivered_duty_paid": false,
    "dry_ice": false,
    "dry_ice_weight":
    {
    "value": 0,
    "unit": "pound"
    },
    "non_machinable": false,
    "saturday_delivery": false,
    "fedex_freight":
    {
    "shipper_load_and_count": "string",
    "booking_confirmation": "string"
    },
    "use_ups_ground_freight_pricing": null,
    "freight_class": 77.5,
    "custom_field1": null,
    "custom_field2": null,
    "custom_field3": null,
    "origin_type": "pickup",
    "additional_handling": null,
    "shipper_release": null,
    "collect_on_delivery":
    {
    "payment_type": "any",
    "payment_amount":
    {
    "currency": "string",
    "amount": 0
    }
    },
    "third_party_consignee": false,
    "dangerous_goods": false,
    "dangerous_goods_contact":
    {
    "name": "string",
    "phone": "string"
    },
    "windsor_framework_details":
    {
    "movement_indicator": "c2c",
    "not_at_risk": true
    },
    "license_number": 514785,
    "invoice_number": "IOC56888",
    "certificate_number": 784515,
    "delivery-as-addressed": false,
    "return-after-first-attempt": false,
    "regulated_content_type": "day_old_poultry"
    },
  - "insurance_provider": "none",
  - "order_source_code": "amazon_ca",
  - "packages":
    [
    {
    "package_id": "se-28529731",
    "package_code": "small_flat_rate_box",
    "package_name": "string",
    "weight":
    {
    "value": 0,
    "unit": "pound"
    },
    "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
    "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
    "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
    "external_package_id": "string",
    "content_description": "Hand knitted wool socks",
    "products": [ ]
    }
    ],
  - "comparison_rate_type": "retail"
  }
]

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"has_errors": false,
"shipments":
[
- {
  - "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":
    [
    {
    "taxable_entity_type": "shipper",
    "identifier_type": "vat",
    "issuing_authority": "string",
    "value": "string"
    }
    ],
  - "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":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no",
    "instructions": "string",
    "geolocation":
    [
    {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
    ]
    },
  - "ship_from":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no",
    "instructions": "string"
    },
  - "warehouse_id": "se-28529731",
  - "return_to":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no",
    "instructions": "string"
    },
  - "is_return": false,
  - "confirmation": "none",
  - "customs":
    {
    "contents": "merchandise",
    "contents_explanation": "string",
    "non_delivery": "return_to_sender",
    "terms_of_trade_code": "exw",
    "declaration": "string",
    "invoice_additional_details":
    {
    "freight_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "insurance_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "discount":
    {
    "currency": "string",
    "amount": 0
    },
    "estimated_import_charges":
    {
    "taxes":
    {
    "currency": "string",
    "amount": 0
    },
    "duties":
    {
    "currency": "string",
    "amount": 0
    }
    },
    "other_charge":
    {
    "currency": "string",
    "amount": 0
    },
    "other_charge_description": "string",
    "invoice_number": "string"
    },
    "importer_of_record":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA"
    },
    "license_number": "string",
    "certificate_number": "string",
    "customs_items": [ ]
    },
  - "advanced_options":
    {
    "bill_to_account": null,
    "bill_to_country_code": "CA",
    "bill_to_party": "recipient",
    "bill_to_postal_code": null,
    "contains_alcohol": false,
    "delivered_duty_paid": false,
    "dry_ice": false,
    "dry_ice_weight":
    {
    "value": 0,
    "unit": "pound"
    },
    "non_machinable": false,
    "saturday_delivery": false,
    "fedex_freight":
    {
    "shipper_load_and_count": "string",
    "booking_confirmation": "string"
    },
    "use_ups_ground_freight_pricing": null,
    "freight_class": 77.5,
    "custom_field1": null,
    "custom_field2": null,
    "custom_field3": null,
    "origin_type": "pickup",
    "additional_handling": null,
    "shipper_release": null,
    "collect_on_delivery":
    {
    "payment_type": "any",
    "payment_amount":
    {
    "currency": "string",
    "amount": 0
    }
    },
    "third_party_consignee": false,
    "dangerous_goods": false,
    "dangerous_goods_contact":
    {
    "name": "string",
    "phone": "string"
    },
    "windsor_framework_details":
    {
    "movement_indicator": "c2c",
    "not_at_risk": true
    },
    "license_number": 514785,
    "invoice_number": "IOC56888",
    "certificate_number": 784515,
    "delivery-as-addressed": false,
    "return-after-first-attempt": false,
    "regulated_content_type": "day_old_poultry"
    },
  - "insurance_provider": "none",
  - "tags": [ ],
  - "order_source_code": "amazon_ca",
  - "packages":
    [
    {
    "shipment_package_id": "se-28529731",
    "package_id": "se-28529731",
    "package_code": "small_flat_rate_box",
    "package_name": "string",
    "weight":
    {
    "value": 0,
    "unit": "pound"
    },
    "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
    "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
    "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
    "external_package_id": "string",
    "tracking_number": "1Z932R800392060079",
    "content_description": "Hand knitted wool socks",
    "products": [ ]
    }
    ],
  - "total_weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "comparison_rate_type": "retail",
  - "zone": 6,
  - "errors":
    [
    "Parameter value '100000000.00' is out of range."
    ],
  - "address_validation":
    {
    "status": "unverified",
    "original_address":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no"
    },
    "matched_address":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no"
    },
    "messages": [ ]
    }
  }
]

}

Get Shipment By External ID

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

Authorizations:

path Parameters

external_shipment_id

required

string

Example: 0bcb569d-1727-4ff9-ab49-b2fec0cee5ae

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/shipments/external_shipment_id/{external_shipment_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"shipment_id": "se-28529731",
"carrier_id": "se-28529731",
"service_code": "usps_first_class_mail",
"shipping_rule_id": "se-28529731",
"external_order_id": "string",
"items": [ ],
"tax_identifiers":
[
- {
  - "taxable_entity_type": "shipper",
  - "identifier_type": "vat",
  - "issuing_authority": "string",
  - "value": "string"
  }
],
"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":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string",
- "geolocation":
  [
  - {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
  ]
},
"ship_from":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string"
},
"warehouse_id": "se-28529731",
"return_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string"
},
"is_return": false,
"confirmation": "none",
"customs":
{
- "contents": "merchandise",
- "contents_explanation": "string",
- "non_delivery": "return_to_sender",
- "terms_of_trade_code": "exw",
- "declaration": "string",
- "invoice_additional_details":
  {
  - "freight_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "insurance_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "discount":
    {
    "currency": "string",
    "amount": 0
    },
  - "estimated_import_charges":
    {
    "taxes":
    {
    "currency": "string",
    "amount": 0
    },
    "duties":
    {
    "currency": "string",
    "amount": 0
    }
    },
  - "other_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "other_charge_description": "string",
  - "invoice_number": "string"
  },
- "importer_of_record":
  {
  - "name": "John Doe",
  - "phone": "+1 204-253-9411 ext. 123",
  - "email": "example@example.com",
  - "company_name": "The Home Depot",
  - "address_line1": "1999 Bishop Grandin Blvd.",
  - "address_line2": "Unit 408",
  - "address_line3": "Building #7",
  - "city_locality": "Winnipeg",
  - "state_province": "Manitoba",
  - "postal_code": "78756-3717",
  - "country_code": "CA"
  },
- "license_number": "string",
- "certificate_number": "string",
- "customs_items": [ ]
},
"advanced_options":
{
- "bill_to_account": null,
- "bill_to_country_code": "CA",
- "bill_to_party": "recipient",
- "bill_to_postal_code": null,
- "contains_alcohol": false,
- "delivered_duty_paid": false,
- "dry_ice": false,
- "dry_ice_weight":
  {
  - "value": 0,
  - "unit": "pound"
  },
- "non_machinable": false,
- "saturday_delivery": false,
- "fedex_freight":
  {
  - "shipper_load_and_count": "string",
  - "booking_confirmation": "string"
  },
- "use_ups_ground_freight_pricing": null,
- "freight_class": 77.5,
- "custom_field1": null,
- "custom_field2": null,
- "custom_field3": null,
- "origin_type": "pickup",
- "additional_handling": null,
- "shipper_release": null,
- "collect_on_delivery":
  {
  - "payment_type": "any",
  - "payment_amount":
    {
    "currency": "string",
    "amount": 0
    }
  },
- "third_party_consignee": false,
- "dangerous_goods": false,
- "dangerous_goods_contact":
  {
  - "name": "string",
  - "phone": "string"
  },
- "windsor_framework_details":
  {
  - "movement_indicator": "c2c",
  - "not_at_risk": true
  },
- "license_number": 514785,
- "invoice_number": "IOC56888",
- "certificate_number": 784515,
- "delivery-as-addressed": false,
- "return-after-first-attempt": false,
- "regulated_content_type": "day_old_poultry"
},
"insurance_provider": "none",
"tags": [ ],
"order_source_code": "amazon_ca",
"packages":
[
- {
  - "shipment_package_id": "se-28529731",
  - "package_id": "se-28529731",
  - "package_code": "small_flat_rate_box",
  - "package_name": "string",
  - "weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
  - "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
  - "external_package_id": "string",
  - "tracking_number": "1Z932R800392060079",
  - "content_description": "Hand knitted wool socks",
  - "products": [ ]
  }
],
"total_weight":
{
- "value": 0,
- "unit": "pound"
},
"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.

Authorizations:

Request Body schema: application/json

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

text required	string non-empty The unstructured text that contains shipping-related entities
shipment	object You can optionally provide a `shipment` object containing any already-known values. For example, you probably already know the `ship_from` address, and you may also already know what carrier and service you want to use.

Responses

200

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

400

The request contained errors.

500

An error occurred on ShipEngine's side.

put/v1/shipments/recognize

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

Request samples

Payload

Content type

application/json

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

Copy

Expand all Collapse all

{

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

}

Response samples

Content type

application/json

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

Copy

Expand all Collapse all

{

"score": 0.9031369611169101,
"shipment":
{
- "carrier_id": "se-118608",
- "service_code": "usps_first_class_mail",
- "confirmation": "adult_signature",
- "ship_to":
  {
  - "name": "Margie McMiller",
  - "company_name": "Adult Signature",
  - "address_line1": "3800 North Lamar",
  - "address_line2": "Suite 200",
  - "city_locality": "Austin",
  - "state_province": "TX",
  - "postal_code": 78652,
  - "address_residential_indicator": "unknown"
  },
- "packages":
  [
  - {
    "weight":
    {
    "value": 4,
    "unit": "ounce"
    },
    "dimensions":
    {
    "length": 5,
    "width": 10,
    "height": 14,
    "unit": "inch"
    },
    "insured_value":
    {
    "amount": 400,
    "currency": "USD"
    }
    }
  ]
},
"entities":
[
- {
  - "type": "weight",
  - "score": 0.9805313966503588,
  - "text": "4oz",
  - "start_index": 9,
  - "end_index": 11,
  - "result":
    {
    "value": 4,
    "unit": "ounce"
    }
  },
- {
  - "type": "dimensions",
  - "score": 1,
  - "text": "5x10x14in",
  - "start_index": 28,
  - "end_index": 36,
  - "result":
    {
    "length": 5,
    "width": 10,
    "height": 14,
    "unit": "inch"
    }
  },
- {
  - "type": "dimension",
  - "score": 0.9805313966503588,
  - "text": "14in",
  - "start_index": 33,
  - "end_index": 36,
  - "result":
    {
    "unit": "inch",
    "value": 14
    }
  },
- {
  - "type": "address",
  - "score": 0.9281558837267101,
  - "text": "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",
  - "start_index": 61,
  - "end_index": 196,
  - "result":
    {
    "direction": "to",
    "name": "Margie McMiller",
    "company_name": "Adult Signature",
    "address_line1": "3800 North Lamar",
    "address_line2": "Suite 200",
    "city_locality": "Austin",
    "state_province": "TX",
    "postal_code": 78652
    }
  },
- {
  - "type": "person",
  - "score": 0.9519646137063122,
  - "text": "Margie McMiller",
  - "start_index": 64,
  - "end_index": 78,
  - "result":
    {
    "value": "Margie McMiller"
    }
  },
- {
  - "type": "address_line",
  - "score": 0.9805313966503588,
  - "text": "3800 North Lamar",
  - "start_index": 83,
  - "end_index": 98,
  - "result":
    {
    "line": 1,
    "value": "3800 North Lamar"
    }
  },
- {
  - "type": "number",
  - "score": 0.9805313966503588,
  - "text": 3800,
  - "start_index": 83,
  - "end_index": 86,
  - "result":
    {
    "type": "cardinal",
    "value": 3800
    }
  },
- {
  - "type": "address_line",
  - "score": 1,
  - "text": "suite 200",
  - "start_index": 100,
  - "end_index": 108,
  - "result":
    {
    "line": 2,
    "value": "Suite 200"
    }
  },
- {
  - "type": "dimension",
  - "score": 0.4792571878834418,
  - "text": "200 in",
  - "start_index": 106,
  - "end_index": 111,
  - "result":
    {
    "unit": "inch",
    "value": 200
    }
  },
- {
  - "type": "city_locality",
  - "score": 0.9805313966503588,
  - "text": "austin",
  - "start_index": 113,
  - "end_index": 118,
  - "result":
    {
    "value": "Austin"
    }
  },
- {
  - "type": "state_province",
  - "score": 0.6082904353940255,
  - "text": "tx",
  - "start_index": 121,
  - "end_index": 122,
  - "result":
    {
    "name": "Texas",
    "value": "TX"
    }
  },
- {
  - "type": "postal_code",
  - "score": 0.9519646137063122,
  - "text": 78652,
  - "start_index": 124,
  - "end_index": 128,
  - "result":
    {
    "value": 78652
    }
  },
- {
  - "type": "carrier",
  - "score": 0.9519646137063122,
  - "text": "USPS",
  - "start_index": 150,
  - "end_index": 153,
  - "result":
    {
    "name": "Stamps.com",
    "value": "se-118608"
    }
  },
- {
  - "type": "service",
  - "score": 0.6082904353940255,
  - "text": "first class",
  - "start_index": 155,
  - "end_index": 165,
  - "result":
    {
    "name": "USPS First Class Mail",
    "value": "usps_first_class_mail"
    }
  },
- {
  - "type": "number",
  - "score": 0.9805313966503588,
  - "text": "first",
  - "start_index": 155,
  - "end_index": 159,
  - "result":
    {
    "type": "ordinal",
    "value": 1
    }
  },
- {
  - "type": "company",
  - "score": 0.9519646137063122,
  - "text": "adult signature",
  - "start_index": 182,
  - "end_index": 196,
  - "result":
    {
    "value": "Adult Signature"
    }
  },
- {
  - "type": "delivery_confirmation",
  - "score": 0.8530163983409642,
  - "text": "adult signature",
  - "start_index": 182,
  - "end_index": 196,
  - "result":
    {
    "name": "Adult Signature",
    "value": "adult_signature"
    }
  },
- {
  - "type": "insurance",
  - "score": 0.8530163983409642,
  - "text": "insured for $400",
  - "start_index": 219,
  - "end_index": 234,
  - "result":
    {
    "value": 400,
    "unit": "USD"
    }
  },
- {
  - "type": "insured_value",
  - "score": 1,
  - "text": "$400",
  - "start_index": 231,
  - "end_index": 234,
  - "result":
    {
    "unit": "USD",
    "value": 400
    }
  }
]

}

Get Shipment By ID

Get an individual shipment based on its ID

Authorizations:

path Parameters

shipment_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/shipments/{shipment_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"shipment_id": "se-28529731",
"carrier_id": "se-28529731",
"service_code": "usps_first_class_mail",
"shipping_rule_id": "se-28529731",
"external_order_id": "string",
"items": [ ],
"tax_identifiers":
[
- {
  - "taxable_entity_type": "shipper",
  - "identifier_type": "vat",
  - "issuing_authority": "string",
  - "value": "string"
  }
],
"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":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string",
- "geolocation":
  [
  - {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
  ]
},
"ship_from":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string"
},
"warehouse_id": "se-28529731",
"return_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string"
},
"is_return": false,
"confirmation": "none",
"customs":
{
- "contents": "merchandise",
- "contents_explanation": "string",
- "non_delivery": "return_to_sender",
- "terms_of_trade_code": "exw",
- "declaration": "string",
- "invoice_additional_details":
  {
  - "freight_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "insurance_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "discount":
    {
    "currency": "string",
    "amount": 0
    },
  - "estimated_import_charges":
    {
    "taxes":
    {
    "currency": "string",
    "amount": 0
    },
    "duties":
    {
    "currency": "string",
    "amount": 0
    }
    },
  - "other_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "other_charge_description": "string",
  - "invoice_number": "string"
  },
- "importer_of_record":
  {
  - "name": "John Doe",
  - "phone": "+1 204-253-9411 ext. 123",
  - "email": "example@example.com",
  - "company_name": "The Home Depot",
  - "address_line1": "1999 Bishop Grandin Blvd.",
  - "address_line2": "Unit 408",
  - "address_line3": "Building #7",
  - "city_locality": "Winnipeg",
  - "state_province": "Manitoba",
  - "postal_code": "78756-3717",
  - "country_code": "CA"
  },
- "license_number": "string",
- "certificate_number": "string",
- "customs_items": [ ]
},
"advanced_options":
{
- "bill_to_account": null,
- "bill_to_country_code": "CA",
- "bill_to_party": "recipient",
- "bill_to_postal_code": null,
- "contains_alcohol": false,
- "delivered_duty_paid": false,
- "dry_ice": false,
- "dry_ice_weight":
  {
  - "value": 0,
  - "unit": "pound"
  },
- "non_machinable": false,
- "saturday_delivery": false,
- "fedex_freight":
  {
  - "shipper_load_and_count": "string",
  - "booking_confirmation": "string"
  },
- "use_ups_ground_freight_pricing": null,
- "freight_class": 77.5,
- "custom_field1": null,
- "custom_field2": null,
- "custom_field3": null,
- "origin_type": "pickup",
- "additional_handling": null,
- "shipper_release": null,
- "collect_on_delivery":
  {
  - "payment_type": "any",
  - "payment_amount":
    {
    "currency": "string",
    "amount": 0
    }
  },
- "third_party_consignee": false,
- "dangerous_goods": false,
- "dangerous_goods_contact":
  {
  - "name": "string",
  - "phone": "string"
  },
- "windsor_framework_details":
  {
  - "movement_indicator": "c2c",
  - "not_at_risk": true
  },
- "license_number": 514785,
- "invoice_number": "IOC56888",
- "certificate_number": 784515,
- "delivery-as-addressed": false,
- "return-after-first-attempt": false,
- "regulated_content_type": "day_old_poultry"
},
"insurance_provider": "none",
"tags": [ ],
"order_source_code": "amazon_ca",
"packages":
[
- {
  - "shipment_package_id": "se-28529731",
  - "package_id": "se-28529731",
  - "package_code": "small_flat_rate_box",
  - "package_name": "string",
  - "weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
  - "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
  - "external_package_id": "string",
  - "tracking_number": "1Z932R800392060079",
  - "content_description": "Hand knitted wool socks",
  - "products": [ ]
  }
],
"total_weight":
{
- "value": 0,
- "unit": "pound"
},
"comparison_rate_type": "retail",
"zone": 6

}

Update Shipment By ID

Update a shipment object based on its ID

Authorizations:

path Parameters

shipment_id

required

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

Example: se-28529731

Request Body schema: application/json

carrier_id	string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ The carrier account that is billed for the shipping charges
service_code	string ^[a-z0-9]+(_[a-z0-9-]+)* ?$ The carrier service used to ship the package, such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc.
shipping_rule_id	string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
external_order_id	string Nullable ID that the Order Source assigned
items	Array of objects Default: [] Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
tax_identifiers	Array of objects Nullable
external_shipment_id	string <= 50 characters Nullable A unique user-defined key to identify a shipment. This can be used to retrieve the shipment. Warning: The `external_shipment_id` is limited to 50 characters. Any additional characters will be truncated.
shipment_number	string <= 50 characters Nullable A non-unique user-defined number used to identify a shipment. If undefined, this will match the external_shipment_id of the shipment. Warning: The `shipment_number` is limited to 50 characters. Any additional characters will be truncated.
ship_date	string <date-time> ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z\|[-+]\d{2}:\d{2}))?$ The date that the shipment was (or will be) shipped. ShipEngine will take the day of week into consideration. For example, if the carrier does not operate on Sundays, then a package that would have shipped on Sunday will ship on Monday instead.
ship_to required	object The recipient's mailing address
ship_from required	object The shipment's origin address. If you frequently ship from the same location, consider creating a warehouse. Then you can simply specify the `warehouse_id` rather than the complete address each time.
warehouse_id	string [ 1 .. 25 ] characters Nullable ^se(-[a-z0-9]+)+$ Default: null The warehouse that the shipment is being shipped from. Either `warehouse_id` or `ship_from` must be specified.
return_to	object The return address for this shipment. Defaults to the `ship_from` address.
is_return	boolean Nullable Default: false An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
confirmation	string Default: "none" Enum: "none" "delivery" "signature" "adult_signature" "direct_signature" "delivery_mailed" "verbal_confirmation" "delivery_code" "age_verification_16_plus" The type of delivery confirmation that is required for this shipment.
customs	object Nullable Default: null Customs information. This is usually only needed for international shipments.
advanced_options	object Advanced shipment options. These are entirely optional.
insurance_provider	string Default: "none" Enum: "none" "shipsurance" "carrier" "third_party" The insurance provider to use for any insured packages in the shipment.
order_source_code	string Enum: "amazon_ca" "amazon_us" "brightpearl" "channel_advisor" "cratejoy" "ebay" "etsy" "jane" "groupon_goods" "magento" "paypal" "seller_active" "shopify" "stitch_labs" "squarespace" "three_dcart" "tophatter" "walmart" "woo_commerce" "volusion" The order sources that are supported by ShipEngine
packages	Array of objects non-empty The packages in the shipment. Note: Some carriers only allow one package per shipment. If you attempt to create a multi-package shipment for a carrier that doesn't allow it, an error will be returned.
comparison_rate_type	string Nullable Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.
validate_address	string Default: "no_validation" Enum: "no_validation" "validate_only" "validate_and_clean" The possible validate address values

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/shipments/{shipment_id}

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"carrier_id": "se-28529731",
"service_code": "usps_first_class_mail",
"shipping_rule_id": "se-28529731",
"external_order_id": "string",
"items": [ ],
"tax_identifiers":
[
- {
  - "taxable_entity_type": "shipper",
  - "identifier_type": "vat",
  - "issuing_authority": "string",
  - "value": "string"
  }
],
"external_shipment_id": "string",
"shipment_number": "string",
"ship_date": "2018-09-23T00:00:00.000Z",
"ship_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string",
- "geolocation":
  [
  - {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
  ]
},
"ship_from":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string"
},
"warehouse_id": "se-28529731",
"return_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string"
},
"is_return": false,
"confirmation": "none",
"customs":
{
- "contents": "merchandise",
- "contents_explanation": "string",
- "non_delivery": "return_to_sender",
- "terms_of_trade_code": "exw",
- "declaration": "string",
- "invoice_additional_details":
  {
  - "freight_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "insurance_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "discount":
    {
    "currency": "string",
    "amount": 0
    },
  - "estimated_import_charges":
    {
    "taxes":
    {
    "currency": "string",
    "amount": 0
    },
    "duties":
    {
    "currency": "string",
    "amount": 0
    }
    },
  - "other_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "other_charge_description": "string",
  - "invoice_number": "string"
  },
- "importer_of_record":
  {
  - "name": "John Doe",
  - "phone": "+1 204-253-9411 ext. 123",
  - "email": "example@example.com",
  - "company_name": "The Home Depot",
  - "address_line1": "1999 Bishop Grandin Blvd.",
  - "address_line2": "Unit 408",
  - "address_line3": "Building #7",
  - "city_locality": "Winnipeg",
  - "state_province": "Manitoba",
  - "postal_code": "78756-3717",
  - "country_code": "CA"
  },
- "license_number": "string",
- "certificate_number": "string",
- "customs_items": [ ]
},
"advanced_options":
{
- "bill_to_account": null,
- "bill_to_country_code": "CA",
- "bill_to_party": "recipient",
- "bill_to_postal_code": null,
- "contains_alcohol": false,
- "delivered_duty_paid": false,
- "dry_ice": false,
- "dry_ice_weight":
  {
  - "value": 0,
  - "unit": "pound"
  },
- "non_machinable": false,
- "saturday_delivery": false,
- "fedex_freight":
  {
  - "shipper_load_and_count": "string",
  - "booking_confirmation": "string"
  },
- "use_ups_ground_freight_pricing": null,
- "freight_class": 77.5,
- "custom_field1": null,
- "custom_field2": null,
- "custom_field3": null,
- "origin_type": "pickup",
- "additional_handling": null,
- "shipper_release": null,
- "collect_on_delivery":
  {
  - "payment_type": "any",
  - "payment_amount":
    {
    "currency": "string",
    "amount": 0
    }
  },
- "third_party_consignee": false,
- "dangerous_goods": false,
- "dangerous_goods_contact":
  {
  - "name": "string",
  - "phone": "string"
  },
- "windsor_framework_details":
  {
  - "movement_indicator": "c2c",
  - "not_at_risk": true
  },
- "license_number": 514785,
- "invoice_number": "IOC56888",
- "certificate_number": 784515,
- "delivery-as-addressed": false,
- "return-after-first-attempt": false,
- "regulated_content_type": "day_old_poultry"
},
"insurance_provider": "none",
"order_source_code": "amazon_ca",
"packages":
[
- {
  - "package_id": "se-28529731",
  - "package_code": "small_flat_rate_box",
  - "package_name": "string",
  - "weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
  - "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
  - "external_package_id": "string",
  - "content_description": "Hand knitted wool socks",
  - "products": [ ]
  }
],
"comparison_rate_type": "retail",
"validate_address": "no_validation"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"shipment_id": "se-28529731",
"carrier_id": "se-28529731",
"service_code": "usps_first_class_mail",
"shipping_rule_id": "se-28529731",
"external_order_id": "string",
"items": [ ],
"tax_identifiers":
[
- {
  - "taxable_entity_type": "shipper",
  - "identifier_type": "vat",
  - "issuing_authority": "string",
  - "value": "string"
  }
],
"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":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string",
- "geolocation":
  [
  - {
    "type": "what3words",
    "value": "cats.with.thumbs"
    }
  ]
},
"ship_from":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string"
},
"warehouse_id": "se-28529731",
"return_to":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no",
- "instructions": "string"
},
"is_return": false,
"confirmation": "none",
"customs":
{
- "contents": "merchandise",
- "contents_explanation": "string",
- "non_delivery": "return_to_sender",
- "terms_of_trade_code": "exw",
- "declaration": "string",
- "invoice_additional_details":
  {
  - "freight_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "insurance_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "discount":
    {
    "currency": "string",
    "amount": 0
    },
  - "estimated_import_charges":
    {
    "taxes":
    {
    "currency": "string",
    "amount": 0
    },
    "duties":
    {
    "currency": "string",
    "amount": 0
    }
    },
  - "other_charge":
    {
    "currency": "string",
    "amount": 0
    },
  - "other_charge_description": "string",
  - "invoice_number": "string"
  },
- "importer_of_record":
  {
  - "name": "John Doe",
  - "phone": "+1 204-253-9411 ext. 123",
  - "email": "example@example.com",
  - "company_name": "The Home Depot",
  - "address_line1": "1999 Bishop Grandin Blvd.",
  - "address_line2": "Unit 408",
  - "address_line3": "Building #7",
  - "city_locality": "Winnipeg",
  - "state_province": "Manitoba",
  - "postal_code": "78756-3717",
  - "country_code": "CA"
  },
- "license_number": "string",
- "certificate_number": "string",
- "customs_items": [ ]
},
"advanced_options":
{
- "bill_to_account": null,
- "bill_to_country_code": "CA",
- "bill_to_party": "recipient",
- "bill_to_postal_code": null,
- "contains_alcohol": false,
- "delivered_duty_paid": false,
- "dry_ice": false,
- "dry_ice_weight":
  {
  - "value": 0,
  - "unit": "pound"
  },
- "non_machinable": false,
- "saturday_delivery": false,
- "fedex_freight":
  {
  - "shipper_load_and_count": "string",
  - "booking_confirmation": "string"
  },
- "use_ups_ground_freight_pricing": null,
- "freight_class": 77.5,
- "custom_field1": null,
- "custom_field2": null,
- "custom_field3": null,
- "origin_type": "pickup",
- "additional_handling": null,
- "shipper_release": null,
- "collect_on_delivery":
  {
  - "payment_type": "any",
  - "payment_amount":
    {
    "currency": "string",
    "amount": 0
    }
  },
- "third_party_consignee": false,
- "dangerous_goods": false,
- "dangerous_goods_contact":
  {
  - "name": "string",
  - "phone": "string"
  },
- "windsor_framework_details":
  {
  - "movement_indicator": "c2c",
  - "not_at_risk": true
  },
- "license_number": 514785,
- "invoice_number": "IOC56888",
- "certificate_number": 784515,
- "delivery-as-addressed": false,
- "return-after-first-attempt": false,
- "regulated_content_type": "day_old_poultry"
},
"insurance_provider": "none",
"tags": [ ],
"order_source_code": "amazon_ca",
"packages":
[
- {
  - "shipment_package_id": "se-28529731",
  - "package_id": "se-28529731",
  - "package_code": "small_flat_rate_box",
  - "package_name": "string",
  - "weight":
    {
    "value": 0,
    "unit": "pound"
    },
  - "dimensions":
    {
    "unit": "inch",
    "length": 0,
    "width": 0,
    "height": 0
    },
  - "insured_value":
    {
    "currency": "string",
    "amount": 0
    },
  - "label_messages":
    {
    "reference1": null,
    "reference2": null,
    "reference3": null
    },
  - "external_package_id": "string",
  - "tracking_number": "1Z932R800392060079",
  - "content_description": "Hand knitted wool socks",
  - "products": [ ]
  }
],
"total_weight":
{
- "value": 0,
- "unit": "pound"
},
"comparison_rate_type": "retail",
"zone": 6,
"errors":
[
- "Parameter value '100000000.00' is out of range."
],
"address_validation":
{
- "status": "unverified",
- "original_address":
  {
  - "name": "John Doe",
  - "phone": "+1 204-253-9411 ext. 123",
  - "email": "example@example.com",
  - "company_name": "The Home Depot",
  - "address_line1": "1999 Bishop Grandin Blvd.",
  - "address_line2": "Unit 408",
  - "address_line3": "Building #7",
  - "city_locality": "Winnipeg",
  - "state_province": "Manitoba",
  - "postal_code": "78756-3717",
  - "country_code": "CA",
  - "address_residential_indicator": "no"
  },
- "matched_address":
  {
  - "name": "John Doe",
  - "phone": "+1 204-253-9411 ext. 123",
  - "email": "example@example.com",
  - "company_name": "The Home Depot",
  - "address_line1": "1999 Bishop Grandin Blvd.",
  - "address_line2": "Unit 408",
  - "address_line3": "Building #7",
  - "city_locality": "Winnipeg",
  - "state_province": "Manitoba",
  - "postal_code": "78756-3717",
  - "country_code": "CA",
  - "address_residential_indicator": "no"
  },
- "messages": [ ]
}

}

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:

path Parameters

shipment_id

required

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

Example: se-28529731

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/shipments/{shipment_id}/cancel

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

Response samples

Get Shipment Rates

Get Rates for the shipment information associated with the shipment ID

Authorizations:

path Parameters

shipment_id

required

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

Example: se-28529731

query Parameters

created_at_start

string <date-time>

Example: created_at_start=2019-03-12T19:24:13.657Z

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

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/shipments/{shipment_id}/rates

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"rates":
[
- {
  - "rate_id": "se-28529731",
  - "rate_type": "check",
  - "carrier_id": "se-28529731",
  - "shipping_amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "insurance_amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "confirmation_amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "other_amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "requested_comparison_amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "tax_amount":
    {
    "currency": "string",
    "amount": 0
    },
  - "rate_details":
    [
    {
    "rate_detail_type": "uncategorized",
    "carrier_description": "string",
    "carrier_billing_code": "string",
    "carrier_memo": "string",
    "amount":
    {
    "currency": "string",
    "amount": 0
    },
    "rate_detail_attributes":
    {
    "tax_type": "vat",
    "tax_percentage": 0
    },
    "billing_source": "string"
    }
    ],
  - "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": "2026-03-18T01:40:39Z",
  - "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":
    [
    "string"
    ],
  - "error_messages":
    [
    "string"
    ],
  - "rate_attributes":
    [
    "best_value"
    ]
  }
],
"invalid_rates": [ ],
"rate_request_id": "se-28529731",
"shipment_id": "se-28529731",
"created_at": "se-28529731",
"status": "working",
"errors":
[
- {
  - "error_source": "carrier",
  - "error_type": "account_status",
  - "error_code": "auto_fund_not_supported",
  - "message": "Body of request cannot be null.",
  - "carrier_id": "se-28529731",
  - "carrier_code": "dhl_express",
  - "field_name": "shipment.ship_to.phone_number"
  }
]

}

Add Tag to Shipment

Add a tag to the shipment object

Authorizations:

path Parameters

shipment_id required	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731
tag_name required	string (tag_name) non-empty Example: Fragile Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

post/v1/shipments/{shipment_id}/tags/{tag_name}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"tags":
[
- "string"
]

}

Remove Tag from Shipment

Remove an existing tag from the Shipment object

Authorizations:

path Parameters

shipment_id required	string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731
tag_name required	string (tag_name) non-empty Example: Fragile Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

delete/v1/shipments/{shipment_id}/tags/{tag_name}

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

Response samples

Create a New Tag

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

Authorizations:

Request Body schema: application/json

name required
color	string non-empty A hex-coded string identifying the color of the tag.

Responses

200

The requested object creation was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"name": "Fragile",
"color": "#FF0000"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"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:

path Parameters

tag_name

required

string (tag_name) non-empty

Example: Fragile

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

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"tag_id": 8712,
"name": "Fragile",
"color": "#FF0000"

}

Delete Tag

Delete a tag that is no longer needed

Authorizations:

path Parameters

tag_name

required

string (tag_name) non-empty

Example: Fragile

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

delete/v1/tags/{tag_name}

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

Response samples

Update Tag Name

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

Authorizations:

path Parameters

tag_name required	string (tag_name) non-empty Example: Fragile Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.
new_tag_name required	string (tag_name) non-empty Example: Fragile Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/tags/{tag_name}/{new_tag_name}

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

Response samples

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:

query Parameters

redirect

string (redirect)

Value: "shipengine-dashboard"

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

Responses

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"token": "string",
"redirect_url": "string"

}

Tracking

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

Get Tracking Information

Retrieve package tracking information

Authorizations:

query Parameters

carrier_code	string non-empty Example: carrier_code=stamps_com
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

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"tracking_number": "1Z932R800392060079",
"tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234",
"status_code": "DE",
"status_detail_code": "DELIVERED",
"carrier_code": "dhl_express",
"carrier_id": 0,
"status_description": "Delivered",
"status_detail_description": "Your 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":
[
- {
  - "occurred_at": "2018-09-23T15:00:00.000Z",
  - "carrier_occurred_at": "2018-09-23T15:00:00.000Z",
  - "description": "Delivered, In/At Mailbox",
  - "city_locality": "AUSTIN",
  - "state_province": "TX",
  - "postal_code": 78756,
  - "country_code": "CA",
  - "company_name": "Stamps.com",
  - "signer": "string",
  - "event_code": "string",
  - "carrier_detail_code": "OT",
  - "status_code": "IT",
  - "status_detail_code": "IN_TRANSIT",
  - "status_description": "In Transit",
  - "status_detail_description": "Your shipment is on its way between the carrier hubs.",
  - "carrier_status_code": 1,
  - "carrier_status_description": "Your item was delivered in or at the mailbox at 9:10 am on March",
  - "latitude": -90,
  - "longitude": -180,
  }
]

}

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:

query Parameters

carrier_code	string non-empty Example: carrier_code=stamps_com
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

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Stop Tracking a Package

Unsubscribe from tracking updates for a package.

Authorizations:

query Parameters

carrier_code	string non-empty Example: carrier_code=stamps_com
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

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Warehouses

List Warehouses

Retrieve a list of warehouses associated with this account.

Authorizations:

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"warehouses":
[
- {
  - "warehouse_id": "se-28529731",
  - "is_default": false,
  - "name": "Zero Cool HQ",
  - "created_at": "2019-06-25T18:12:35.583Z",
  - "origin_address":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no"
    },
  - "return_address":
    {
    "name": "John Doe",
    "phone": "+1 204-253-9411 ext. 123",
    "email": "example@example.com",
    "company_name": "The Home Depot",
    "address_line1": "1999 Bishop Grandin Blvd.",
    "address_line2": "Unit 408",
    "address_line3": "Building #7",
    "city_locality": "Winnipeg",
    "state_province": "Manitoba",
    "postal_code": "78756-3717",
    "country_code": "CA",
    "address_residential_indicator": "no"
    }
  }
]

}

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:

Request Body schema: application/json

is_default	boolean Nullable Default: false Designates which single warehouse is the default on the account
name required
origin_address required	object The origin address of the warehouse
return_address	object The return address associated with the warehouse

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"is_default": false,
"name": "Zero Cool HQ",
"origin_address":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no"
},
"return_address":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no"
}

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"warehouse_id": "se-28529731",
"is_default": false,
"name": "Zero Cool HQ",
"created_at": "2019-06-25T18:12:35.583Z",
"origin_address":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no"
},
"return_address":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no"
}

}

Get Warehouse By Id

Retrieve warehouse data based on the warehouse ID

Authorizations:

path Parameters

warehouse_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/warehouses/{warehouse_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"warehouse_id": "se-28529731",
"is_default": false,
"name": "Zero Cool HQ",
"created_at": "2019-06-25T18:12:35.583Z",
"origin_address":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no"
},
"return_address":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no"
}

}

Update Warehouse By Id

Update Warehouse object information

Authorizations:

path Parameters

warehouse_id

required

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

Example: se-28529731

Request Body schema: application/json

is_default	boolean Nullable Default: false Designates which single warehouse is the default on the account
name required
origin_address required	object The origin address of the warehouse
return_address	object The return address associated with the warehouse

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/warehouses/{warehouse_id}

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"is_default": false,
"name": "Zero Cool HQ",
"origin_address":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no"
},
"return_address":
{
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "email": "example@example.com",
- "company_name": "The Home Depot",
- "address_line1": "1999 Bishop Grandin Blvd.",
- "address_line2": "Unit 408",
- "address_line3": "Building #7",
- "city_locality": "Winnipeg",
- "state_province": "Manitoba",
- "postal_code": "78756-3717",
- "country_code": "CA",
- "address_residential_indicator": "no"
}

}

Response samples

Delete Warehouse By ID

Authorizations:

path Parameters

warehouse_id

required

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

Example: se-28529731

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

delete/v1/warehouses/{warehouse_id}

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

Response samples

Update Warehouse Settings

Update Warehouse settings object information

Authorizations:

path Parameters

warehouse_id

required

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

Example: se-28529731

Request Body schema: application/json

is_default

boolean Nullable

The default property on the warehouse.

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/warehouses/{warehouse_id}/settings

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

Response samples

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.

List Webhooks

List all webhooks currently enabled for the account.

Authorizations:

Responses

200

The request was a success.

400

The request contained errors.

500

An error occurred on ShipEngine's side.

get/v1/environment/webhooks

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

[

{
- "webhook_id": "se-28529731",
- "url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
- "event": "batch",
- "headers":
  [
  - {
    "key": "custom-key",
    "value": "custom-value"
    }
  ],
- "name": "My Webhook",
- "store_id": 123456
}

]

Create a Webhook

Create a webhook for specific events in the environment.

Authorizations:

Request Body schema: application/json

event required	string Enum: "batch" "carrier_connected" "order_source_refresh_complete" "rate" "report_complete" "sales_orders_imported" "track" The possible webhook event values
url required	string <url> non-empty The url that the webhook sends the request to
headers	Array of objects Array of custom webhook headers
name
store_id

Responses

200

The request was a success.

400

The request contained errors.

409

The request conflicts with an existing resource.

500

An error occurred on ShipEngine's side.

post/v1/environment/webhooks

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"event": "batch",
"url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
"headers":
[
- {
  - "key": "custom-key",
  - "value": "custom-value"
  }
],
"name": "My New Webhook",
"store_id": 123456

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"webhook_id": "se-28529731",
"url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
"event": "batch",
"headers":
[
- {
  - "key": "custom-key",
  - "value": "custom-value"
  }
],
"name": "My Webhook",
"store_id": 123456

}

Get Webhook By ID

Retrieve individual webhook by an ID

Authorizations:

path Parameters

webhook_id

required

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

Example: se-28529731

Responses

200

The request was a success.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

get/v1/environment/webhooks/{webhook_id}

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

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"webhook_id": "se-28529731",
"url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
"event": "batch",
"headers":
[
- {
  - "key": "custom-key",
  - "value": "custom-value"
  }
],
"name": "My Webhook",
"store_id": 123456

}

Update a Webhook

Update the webhook url property

Authorizations:

path Parameters

webhook_id

required

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

Example: se-28529731

Request Body schema: application/json

url	string <url> non-empty The url that the wehbook sends the request
headers	Array of objects Array of custom webhook headers
name
store_id

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

put/v1/environment/webhooks/{webhook_id}

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

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"url": "https://[YOUR ENDPOINT ID].x.requestbin.com",
"headers":
[
- {
  - "key": "custom-key",
  - "value": "custom-value"
  }
],
"name": "My Updated Webhook",
"store_id": 123456

}

Response samples

Delete Webhook By ID

Authorizations:

path Parameters

webhook_id

required

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

Example: se-28529731

Responses

204

The request was successful.

400

The request contained errors.

404

The specified resource does not exist.

500

An error occurred on ShipEngine's side.

delete/v1/environment/webhooks/{webhook_id}

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