"+e+""},a.prototype.br=function(){return this.options.xhtml?"
":"
"},a.prototype.del=function(e){return""+e+""},a.prototype.link=function(e,t,n){if(null===(e=d(this.options.sanitize,this.options.baseUrl,e)))return n;var r='":">"},a.prototype.text=function(e){return e},s.prototype.strong=s.prototype.em=s.prototype.codespan=s.prototype.del=s.prototype.text=function(e){return e},s.prototype.link=s.prototype.image=function(e,t,n){return""+n},s.prototype.br=function(){return""},l.parse=function(e,t){return new l(t).parse(e)},l.prototype.parse=function(e){this.inline=new i(e.links,this.options),this.inlineText=new i(e.links,y({},this.options,{renderer:new s})),this.tokens=e.reverse();for(var t="";this.next();)t+=this.tok();return t},l.prototype.next=function(){return this.token=this.tokens.pop(),this.token},l.prototype.peek=function(){return this.tokens[this.tokens.length-1]||0},l.prototype.parseText=function(){for(var e=this.token.text;"text"===this.peek().type;)e+="\n"+this.next().text;return this.inline.output(e)},l.prototype.tok=function(){switch(this.token.type){case"space":return"";case"hr":return this.renderer.hr();case"heading":return this.renderer.heading(this.inline.output(this.token.text),this.token.depth,p(this.inlineText.output(this.token.text)),this.slugger);case"code":return this.renderer.code(this.token.text,this.token.lang,this.token.escaped);case"table":var e,t,n,r,o="",i="";for(n="",e=0;e?@[\]^`{|}~]/g,"").replace(/\s/g,"-");if(this.seen.hasOwnProperty(t)){var n=t;do{this.seen[n]++,t=n+"-"+this.seen[n]}while(this.seen.hasOwnProperty(t))}return this.seen[t]=0,t},u.escapeTest=/[&<>"']/,u.escapeReplace=/[&<>"']/g,u.replacements={"&":"&","<":"<",">":">",'"':""","'":"'"},u.escapeTestNoEncode=/[<>"']|&(?!#?\w+;)/,u.escapeReplaceNoEncode=/[<>"']|&(?!#?\w+;)/g;var h={},m=/^$|^[a-z][a-z0-9+.-]*:|^[?#]/i;function g(){}function y(e){for(var t,n,r=1;r=0&&"\\"===n[o];)r=!r;return r?"|":" |"})).split(/ \|/),r=0;if(n.length>t)n.splice(t);else for(;n.lengthAn error occurred:"+u(e.message+"",!0)+"";throw e}}g.exec=g,k.options=k.setOptions=function(e){return y(k.defaults,e),k},k.getDefaults=function(){return{baseUrl:null,breaks:!1,gfm:!0,headerIds:!0,headerPrefix:"",highlight:null,langPrefix:"language-",mangle:!0,pedantic:!1,renderer:new a,sanitize:!1,sanitizer:null,silent:!1,smartLists:!1,smartypants:!1,xhtml:!1}},k.defaults=k.getDefaults(),k.Parser=l,k.parser=l.parse,k.Renderer=a,k.TextRenderer=s,k.Lexer=r,k.lexer=r.lex,k.InlineLexer=i,k.inlineLexer=i.output,k.Slugger=c,k.parse=k,e.exports=k}(this||"undefined"!=typeof window&&window)}).call(this,n(7))},function(e,t,n){var r=n(9);e.exports=function(e,t){if(!r(e))return e;var n,o;if(t&&"function"==typeof(n=e.toString)&&!r(o=n.call(e)))return o;if("function"==typeof(n=e.valueOf)&&!r(o=n.call(e)))return o;if(!t&&"function"==typeof(n=e.toString)&&!r(o=n.call(e)))return o;throw TypeError("Can't convert object to primitive value")}},function(e,t){var n=0,r=Math.random();e.exports=function(e){return"Symbol("+String(void 0===e?"":e)+")_"+(++n+r).toString(36)}},function(e,t,n){var r=n(70),o=n(55),i=r("keys");e.exports=function(e){return i[e]||(i[e]=o(e))}},function(e,t,n){var r,o=n(21),i=n(173),a=n(80),s=n(43),l=n(110),c=n(72),u=n(56),p=u("IE_PROTO"),f=function(){},d=function(e){return"
ShipEngine API (1.1.202603260803)
Download OpenAPI specification:Download
ShipEngine Sales & Support: [email protected] URL: https://www.shipengine.com/contact/ Terms of ServiceShipEngine'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.
If you're new to REST APIs then be sure to read our introduction to REST to understand the basics. Learn how to authenticate yourself to ShipEngine, and then use our sandbox environment to kick the tires and get familiar with our API. If you run into any problems, then be sure to check the error handling guide for tips.
Here are some step-by-step tutorials to get you started:
ShipEngine makes it easy to create shipping labels for any carrier and download them in a variety of file formats. You can even customize labels with your own messages and images.
With ShipEngine you can get the current status of a package or subscribe to real-time tracking updates via webhooks. You can also create custimized tracking pages with your own branding so your customers will always know where their package is.
Make sure you ship as cost-effectively as possible by comparing rates across carriers using the ShipEngine Rates API. Or if you don't know the full shipment details yet, then you can get rate estimates with limited address info.
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.
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
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.
This error will automatically be reported to our engineers.
get/v1/account/settingshttps://api.shipengine.com/v1/account/settings Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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.
This error will automatically be reported to our engineers.
get/v1/account/settings/imageshttps://api.shipengine.com/v1/account/settings/images Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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": {
}
}Create an Account Image
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.
This error will automatically be reported to our engineers.
post/v1/account/settings/imageshttps://api.shipengine.com/v1/account/settings/images Request samples
- Payload
Content typeapplication/jsonCopy 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
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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_DtBXupDBxREpHnwEXhTfgKLabel Image Id
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/account/settings/images/{label_image_id}https://api.shipengine.com/v1/account/settings/images/{label_image_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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_DtBXupDBxREpHnwEXhTfgKLabel Image Id
Request Body schema: application/json
name string [ 1 .. 50 ] characters A human readable name for the image.
is_default required boolean Indicates whether this image is set as default.
image_content_type string Enum: "image/png" "image/jpeg" The file type of the image.
image_data string A base64 encoded string representation of the image.
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
put/v1/account/settings/images/{label_image_id}https://api.shipengine.com/v1/account/settings/images/{label_image_id} Request samples
- Payload
Content typeapplication/jsonCopy 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
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleDelete Account Image By Id
Delete Account Image By Id
Authorizations:
path Parameters
label_image_id required string (image_id) >= 4 characters Example: img_DtBXupDBxREpHnwEXhTfgKLabel Image Id
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
delete/v1/account/settings/images/{label_image_id}https://api.shipengine.com/v1/account/settings/images/{label_image_id} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleNo matter your shipping volume, failed deliveries and address change surcharges cut into your bottom line and damage perception with customers. Our address validation services ensure your packages make it to the right place the first time. Learn how to leverage our address validation services here.
ShipEngine supports address validation for virtually every country on Earth, including the United States, Canada, Great Britain, Australia, Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160 others.
Parse an address
The address-recognition API makes it easy for you to extract address data from unstructured text, including the recipient name, line 1, line 2, city, postal code, and more.
Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's address-recognition API helps you extract meaningful, structured data from this unstructured text. The parsed address data is returned in the same structure that's used for other ShipEngine APIs, such as address validation, rate quotes, and shipping labels.
Note: Address recognition is currently supported for the United States, Canada, Australia, New Zealand, the United Kingdom, and Ireland.
Authorizations:
Request Body schema: application/json
The only required field is text, which is the text to be parsed. You can optionally also provide an address containing already-known values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines.
text required string non-empty The unstructured text that contains address-related entities
address object You can optionally provide any already-known address values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines.
Responses
200 Returns the parsed address, as well as a confidence score and a list of all the entities that were recognized in the text.
400 The request contained errors.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
put/v1/addresses/recognizehttps://api.shipengine.com/v1/addresses/recognize Request samples
- Payload
Content typeapplication/jsonExampleText onlyThis 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
- 200
- 400
- 500
Content typeapplication/jsonExampletext_onlyThis 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.
This error will automatically be reported to our engineers.
post/v1/addresses/validatehttps://api.shipengine.com/v1/addresses/validate Request samples
- Payload
Content typeapplication/jsonA 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
- 200
- 400
- 500
Content typeapplication/jsonExampleAll Known FieldsA 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": [ ]
}
]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=2Return 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=50The 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.657ZOnly 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.657ZOnly 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.657ZOnly 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.657ZOnly 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.
This error will automatically be reported to our engineers.
get/v1/batcheshttps://api.shipengine.com/v1/batches Response samples
- 200
- 404
- 500
Content typeapplication/jsonCopy 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"
}, - "label_download": {
}, - "paperless_download": {
- "instructions": null,
- "handoff_code": null
}, - "status": "open"
}
], - "total": 10,
- "page": 1,
- "pages": 10,
- "links": {
}
}Create A Batch
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.
This error will automatically be reported to our engineers.
post/v1/batcheshttps://api.shipengine.com/v1/batches Request samples
- Payload
Content typeapplication/jsonExamplecreate_batch_request_bodyCopy 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
- 200
- 207
- 400
- 500
Content typeapplication/jsonCopy 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"
}, - "label_download": {
}, - "paperless_download": {
- "instructions": null,
- "handoff_code": null
}, - "status": "open"
}Get Batch By External ID
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.
This error will automatically be reported to our engineers.
get/v1/batches/external_batch_id/{external_batch_id}https://api.shipengine.com/v1/batches/external_batch_id/{external_batch_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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"
}, - "label_download": {
}, - "paperless_download": {
- "instructions": null,
- "handoff_code": null
}, - "status": "open"
}Delete Batch By Id
Delete Batch By Id
Authorizations:
path Parameters
batch_id required string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731Batch ID
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
delete/v1/batches/{batch_id}https://api.shipengine.com/v1/batches/{batch_id} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleGet Batch By ID
Get Batch By ID
Authorizations:
path Parameters
batch_id required string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731Batch ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/batches/{batch_id}https://api.shipengine.com/v1/batches/{batch_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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"
}, - "label_download": {
}, - "paperless_download": {
- "instructions": null,
- "handoff_code": null
}, - "status": "open"
}Update Batch By Id
Update Batch By Id
Authorizations:
path Parameters
batch_id required string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731Batch ID
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
put/v1/batches/{batch_id}https://api.shipengine.com/v1/batches/{batch_id} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleAdd 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-28529731Batch ID
Request Body schema: application/json
shipment_ids Array of strings The Shipment Ids to be modified on the batch
rate_ids Array of strings Array of Rate IDs to be modifed on the batch
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/batches/{batch_id}/addhttps://api.shipengine.com/v1/batches/{batch_id}/add Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "shipment_ids": [
- "se-28529731"
], - "rate_ids": [
- "se-28529731"
]
} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleGet 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-28529731Batch ID
query Parameters
page integer <int32> >= 1 Default: 1 Example: page=2Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.
pagesize integer <int32> >= 1
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/batches/{batch_id}/errorshttps://api.shipengine.com/v1/batches/{batch_id}/errors Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy Expand all Collapse all {- "errors": [ ],
- "links": {
}
}Process Batch ID Labels
Process Batch ID Labels
Authorizations:
path Parameters
batch_id required string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731Batch ID
Request Body schema: application/json
ship_date string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2})$ The Ship date the batch is being processed for
label_layout string Default: "4x6" Enum: "4x6" "letter" "A4" "A6" The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
label_format string Default: "pdf" Enum: "pdf" "png" "zpl" The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
Label Format
Supported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_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" "paperless" "label_and_paperless" The display format that the label should be shown in.
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/batches/{batch_id}/process/labelshttps://api.shipengine.com/v1/batches/{batch_id}/process/labels Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "ship_date": "2018-09-23T15:00:00.000Z",
- "label_layout": "4x6",
- "label_format": "pdf",
- "display_scheme": "label"
} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleRemove 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-28529731Batch ID
Request Body schema: application/json
shipment_ids Array of strings The Shipment Ids to be modified on the batch
rate_ids Array of strings Array of Rate IDs to be modifed on the batch
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/batches/{batch_id}/removehttps://api.shipengine.com/v1/batches/{batch_id}/remove Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "shipment_ids": [
- "se-28529731"
], - "rate_ids": [
- "se-28529731"
]
} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleA carrier account is a connection to a shipping carrier that allows you to create labels, track packages, and more. You can connect your own carrier accounts to ShipEngine, or use one of our built-in carrier accounts. Learn more about carrier accounts here.
Connect a carrier account
Connect a carrier account
Authorizations:
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_expressThe carrier name, such as stamps_com, ups, fedex, or dhl_express.
Request Body schema: application/json
One of - connect_access_worldwide_request_body
- connect_amazon_buy_shipping_request_body
- connect_amazon_shipping_uk
- connect_apc_request_body
- connect_asendia_request_body
- connect_australia_post_request_body
- connect_canada_post_request_body
- connect_dhl_ecommerce_request_body
- connect_dhl_express_request_body
- connect_dhl_express_au_request_body
- connect_dhl_express_ca_request_body
- connect_dhl_express_uk_request_body
- connect_dpd_request_body
- connect_endicia_request_body
- connect_fedex_request_body
- connect_fedex_uk_request_body
- connect_firstmile_request_body
- connect_imex_request_body
- connect_lasership_request_body
- connect_newgistics_request_body
- connect_ontrac_request_body
- connect_purolator_request_body
- connect_royal_mail_request_body
- connect_rr_donnelley_request_body
- connect_seko_request_body
- connect_sendle_request_body
- connect_stamps_request_body
- connect_ups_request_body
nickname required string non-empty The nickname associated with the carrier connection
username required string non-empty Access Worldwide Username
password required string non-empty Access Worldwide Password
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/connections/carriers/{carrier_name}https://api.shipengine.com/v1/connections/carriers/{carrier_name} Request samples
- Payload
Content typeapplication/jsonExampleconnect_access_worldwide_request_bodyCopy Expand all Collapse all {- "nickname": "Stamps.com",
- "username": "string",
- "password": "string"
} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy Expand all Collapse all {- "carrier_id": "se-28529731"
}Disconnect a carrier
Disconnect a carrier
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_expressThe 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-28529731Carrier ID
Responses
204 The request was successful.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
delete/v1/connections/carriers/{carrier_name}/{carrier_id}https://api.shipengine.com/v1/connections/carriers/{carrier_name}/{carrier_id} Response samples
- 204
- 404
- 500
Content typetext/plainNo sampleGet carrier settings
Get carrier settings
Authorizations:
path Parameters
carrier_name required string (carrier_name_with_settings) Enum: "dhl_express" "fedex" "newgistics" "ups" Example: dhl_expressThe carrier name, such as ups, fedex, or dhl_express.
carrier_id required string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731Carrier ID
Responses
200 The request was a success.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/connections/carriers/{carrier_name}/{carrier_id}/settingshttps://api.shipengine.com/v1/connections/carriers/{carrier_name}/{carrier_id}/settings Response samples
- 200
- 404
- 500
Content typeapplication/jsonExampledhl_express_settings_response_bodyCopy Expand all Collapse all {- "nickname": "string",
- "should_hide_account_number_on_archive_doc": true,
- "is_primary_account": true
}Update carrier settings
Update carrier settings
Authorizations:
path Parameters
carrier_name required string (carrier_name_with_settings) Enum: "dhl_express" "fedex" "newgistics" "ups" Example: dhl_expressThe carrier name, such as ups, fedex, or dhl_express.
carrier_id required string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731Carrier ID
Request Body schema: application/json
One of - update_dhl_express_settings_request_body
- update_fedex_settings_request_body
- update_newgistics_settings_request_body
- update_ups_settings_request_body
- update_amazon_buy_shipping_request_body
nickname string non-empty Account nickname
should_hide_account_number_on_archive_doc boolean Indicates if the account number should be hidden on the archive documentation
is_primary_account boolean Indicates if this is primary account
Responses
204 The request was successful.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
put/v1/connections/carriers/{carrier_name}/{carrier_id}/settingshttps://api.shipengine.com/v1/connections/carriers/{carrier_name}/{carrier_id}/settings Request samples
- Payload
Content typeapplication/jsonExampleupdate_dhl_express_settings_request_bodyCopy Expand all Collapse all {- "nickname": "string",
- "should_hide_account_number_on_archive_doc": true,
- "is_primary_account": true
} Response samples
- 204
- 404
- 500
Content typetext/plainNo sampleList 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.
This error will automatically be reported to our engineers.
get/v1/carriershttps://api.shipengine.com/v1/carriers Response samples
- 200
- 207
- 400
- 404
- 500
Content typeapplication/jsonCopy 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-28529731Carrier ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/carriers/{carrier_id}https://api.shipengine.com/v1/carriers/{carrier_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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-28529731Carrier ID
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
delete/v1/carriers/{carrier_id}https://api.shipengine.com/v1/carriers/{carrier_id} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleAdd Funds To Carrier
Add Funds To A Carrier
Authorizations:
path Parameters
carrier_id required string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731Carrier ID
Request Body schema: application/json
currency required string The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html
amount required number >= 0 The monetary amount, in the specified currency.
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
put/v1/carriers/{carrier_id}/add_fundshttps://api.shipengine.com/v1/carriers/{carrier_id}/add_funds Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "currency": "string",
- "amount": 0
} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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-28529731Carrier ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/carriers/{carrier_id}/optionshttps://api.shipengine.com/v1/carriers/{carrier_id}/options Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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-28529731Carrier ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/carriers/{carrier_id}/packageshttps://api.shipengine.com/v1/carriers/{carrier_id}/packages Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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-28529731Carrier ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/carriers/{carrier_id}/serviceshttps://api.shipengine.com/v1/carriers/{carrier_id}/services Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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
}
]
}Download File
Get File
Authorizations:
path Parameters
subdir required string filename required string dir required string
query Parameters
download string rotation integer <int32>
Responses
200 The request was a success
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/downloads/{dir}/{subdir}/{filename}https://api.shipengine.com/v1/downloads/{dir}/{subdir}/{filename} Response samples
- 400
- 404
- 500
Content typeapplication/jsonCopy 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"
}
]
}Disconnect a Shipsurance Account
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.
This error will automatically be reported to our engineers.
delete/v1/connections/insurance/shipsurancehttps://api.shipengine.com/v1/connections/insurance/shipsurance Response samples
- 200
- 400
- 500
Content typeapplication/jsonCopy Expand all Collapse all { }Connect a Shipsurance Account
Connect a Shipsurance Account
Authorizations:
Request Body schema: application/json
email required string <email> non-empty An email address.
policy_id required string non-empty
Responses
200 The request was a success
400 The request contained errors.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/connections/insurance/shipsurancehttps://api.shipengine.com/v1/connections/insurance/shipsurance Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "policy_id": "string"
} Response samples
- 200
- 400
- 500
Content typeapplication/jsonCopy 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
currency required string The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html
amount required number >= 0 The monetary amount, in the specified currency.
Responses
200 The request was a success.
400 The request contained errors.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
patch/v1/insurance/shipsurance/add_fundshttps://api.shipengine.com/v1/insurance/shipsurance/add_funds Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "currency": "string",
- "amount": 0
} Response samples
- 200
- 400
- 500
Content typeapplication/jsonCopy 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.
This error will automatically be reported to our engineers.
get/v1/insurance/shipsurance/balancehttps://api.shipengine.com/v1/insurance/shipsurance/balance Response samples
- 200
- 400
- 500
Content typeapplication/jsonCopy Expand all Collapse all {- "currency": "string",
- "amount": 0
}Print shipping labels for any of the top global carriers in minutes—instead of weeks. Simply connect your existing carrier accounts in the API dashboard, and then begin creating labels.
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
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
inlineYou will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
Responses
200 The requested object creation was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/documents/combined_labelshttps://api.shipengine.com/v1/documents/combined_labels Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "label_ids": [
- "se-28529731"
], - "label_format": "pdf",
- "label_download_type": "url"
} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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_mailOnly return labels for a specific carrier service
carrier_id string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: carrier_id=se-28529731Only return labels for a specific carrier account
tracking_number string non-empty Example: tracking_number=9405511899223197428490Only return labels with a specific tracking number
batch_id string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: batch_id=se-28529731Only 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-28529731Rate ID
shipment_id string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: shipment_id=se-28529731Shipment ID
warehouse_id string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: warehouse_id=se-28529731Only return labels that originate from a specific warehouse
created_at_start string <date-time> Example: created_at_start=2019-03-12T19:24:13.657ZOnly 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.657ZOnly return labels that were created on or before a specific date/time
page integer <int32> >= 1 Default: 1 Example: page=2Return 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=50The 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.
This error will automatically be reported to our engineers.
get/v1/labelshttps://api.shipengine.com/v1/labels Response samples
- 200
- 400
- 500
Content typeapplication/jsonCopy 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",
- "label_download": {
}, - "paperless_download": {
- "instructions": null,
- "handoff_code": null
}, - "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",
- "label_download": {
}, - "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",
- "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": {
}
}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
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
inlineYou 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" "paperless" "label_and_paperless" The display format that the label should be shown in.
label_layout string Default: "4x6" Enum: "4x6" "letter" "A4" "A6" The layout (size) that you want the label to be in. The label_format determines which sizes are allowed. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
label_image_id string >= 4 characters Nullable The label image resource that was used to create a custom label image.
Responses
200 The requested object creation was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/labelshttps://api.shipengine.com/v1/labels Request samples
- Payload
Content typeapplication/jsonCopy 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",
- "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",
- "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",
- "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",
- "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,
- "fragile": false,
- "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
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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": {
}, - "paperless_download": {
- "instructions": null,
- "handoff_code": null
}, - "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",
- "label_download": {
}, - "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",
- "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=urlThere are two different ways to download a label:
Label Download Type
Description
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
inlineYou will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
Responses
200 The requested object creation was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/labels/external_shipment_id/{external_shipment_id}https://api.shipengine.com/v1/labels/external_shipment_id/{external_shipment_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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": {
}, - "paperless_download": {
- "instructions": null,
- "handoff_code": null
}, - "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",
- "label_download": {
}, - "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",
- "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-28529731Rate ID
Request Body schema: application/json
custom_field1 string Optional - Value will be saved in the shipment's advanced_options > custom_field1
custom_field2 string Optional - Value will be saved in the shipment's advanced_options > custom_field2
custom_field3 string Optional - Value will be saved in the shipment's advanced_options > custom_field3
validate_address string Enum: "no_validation" "validate_only" "validate_and_clean" The possible validate address values
label_layout string Default: "4x6" Enum: "4x6" "letter" "A4" "A6" The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
label_format string Default: "pdf" Enum: "pdf" "png" "zpl" The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
Label Format
Supported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_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
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
inlineYou 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" "paperless" "label_and_paperless" The display format that the label should be shown in.
Responses
200 The requested object creation was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/labels/rates/{rate_id}https://api.shipengine.com/v1/labels/rates/{rate_id} Request samples
- Payload
Content typeapplication/jsonCopy 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
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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": {
}, - "paperless_download": {
- "instructions": null,
- "handoff_code": null
}, - "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",
- "label_download": {
}, - "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",
- "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
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
inlineYou 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" "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 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.
This error will automatically be reported to our engineers.
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 typeapplication/jsonCopy 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
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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-28529731Shipment ID
Request Body schema: application/json
validate_address string Enum: "no_validation" "validate_only" "validate_and_clean" The possible validate address values
label_layout string Default: "4x6" Enum: "4x6" "letter" "A4" "A6" The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
label_format string Default: "pdf" Enum: "pdf" "png" "zpl" The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
Label Format
Supported Carriers
pdfAll carriers
pngfedex
stamps_com
ups
usps
zplaccess_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
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
inlineYou 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" "paperless" "label_and_paperless" The display format that the label should be shown in.
Responses
200 The requested object creation was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/labels/shipment/{shipment_id}https://api.shipengine.com/v1/labels/shipment/{shipment_id} Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "validate_address": "no_validation",
- "label_layout": "4x6",
- "label_format": "pdf",
- "label_download_type": "url",
- "display_scheme": "label"
} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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": {
}, - "paperless_download": {
- "instructions": null,
- "handoff_code": null
}, - "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",
- "label_download": {
}, - "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",
- "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-28529731Label ID
query Parameters
label_download_type string (label_download_type) Enum: "url" "inline" Example: label_download_type=urlThere are two different ways to download a label:
Label Download Type
Description
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
inlineYou will receive the Base64-encoded label as part of the response. No need for a second request to download the label.
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/labels/{label_id}https://api.shipengine.com/v1/labels/{label_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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": {
}, - "paperless_download": {
- "instructions": null,
- "handoff_code": null
}, - "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",
- "label_download": {
}, - "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",
- "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-28529731Label ID
Request Body schema: application/json
charge_event string Enum: "carrier_default" "on_creation" "on_carrier_acceptance" The label charge event.
label_layout string Default: "4x6" Enum: "4x6" "letter" "A4" "A6" The layout (size) that you want the label to be in. The label_format determines which sizes are allowed. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
label_format string Default: "pdf" Enum: "pdf" "png" "zpl" The file format that you want the label to be in. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
label_download_type string Default: "url" Enum: "url" "inline" There are two different ways to download a label:
Label Download Type
Description
urlYou will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.
inlineYou 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" "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.
This error will automatically be reported to our engineers.
post/v1/labels/{label_id}/returnhttps://api.shipengine.com/v1/labels/{label_id}/return Request samples
- Payload
Content typeapplication/jsonExampleReturn label with custom RMA numberCreate 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
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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": {
}, - "paperless_download": {
- "instructions": null,
- "handoff_code": null
}, - "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",
- "label_download": {
}, - "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",
- "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-28529731Label ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/labels/{label_id}/trackhttps://api.shipengine.com/v1/labels/{label_id}/track Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy Expand all Collapse all {- "tracking_number": "1Z932R800392060079",
- "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-28529731Label ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
put/v1/labels/{label_id}/voidhttps://api.shipengine.com/v1/labels/{label_id}/void Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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"
}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-28529731Warehouse ID
ship_date_start string <date-time> Example: ship_date_start=2018-09-23T15:00:00.000Zship date start range
ship_date_end string <date-time> Example: ship_date_end=2018-09-23T15:00:00.000Zship date end range
created_at_start string <date-time> Example: created_at_start=2019-03-12T19:24:13.657ZUsed 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.657ZUsed 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-28529731Carrier ID
page integer <int32> >= 1 Default: 1 Example: page=2Return 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=50The number of results to return per response.
label_ids Array of strings (se_id) Example: label_ids=se-28529731Array of label ids
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/manifestshttps://api.shipengine.com/v1/manifests Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy Expand all Collapse all {- "manifests": [ ],
- "total": 3,
- "page": 3,
- "pages": 4,
- "links": {
}
}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.
This error will automatically be reported to our engineers.
post/v1/manifestshttps://api.shipengine.com/v1/manifests Request samples
- Payload
Content typeapplication/jsonExamplecreate_manifest_by_object_request_bodyCopy 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
- 200
- 400
- 500
Content typeapplication/jsonCopy 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",
- "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
Get Manifest By Id
Authorizations:
path Parameters
manifest_id required string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731The Manifest Id
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/manifests/{manifest_id}https://api.shipengine.com/v1/manifests/{manifest_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
}Get Manifest Request By Id
Get Manifest Request By Id
Authorizations:
path Parameters
manifest_request_id required string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731The Manifest Request Id
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/manifests/requests/{manifest_request_id}https://api.shipengine.com/v1/manifests/requests/{manifest_request_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
- "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"
}
]
}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-28529731Carrier ID
warehouse_id string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: warehouse_id=se-28529731Warehouse ID
created_at_start string <date-time> Example: created_at_start=2019-03-12T19:24:13.657ZOnly 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.657ZOnly return scheduled pickups that were created on or before a specific date/time
page integer <int32> >= 1 Default: 1 Example: page=2Return 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=50The number of results to return per response.
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/pickupshttps://api.shipengine.com/v1/pickups Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
- "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"
}, - "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": {
}, - "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 object (contact_details) pickup_notes string >= 0 characters Used by some carriers to give special instructions for a package pickup
pickup_window required object (pickup_window) The desired time range for the package pickup.
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/pickupshttps://api.shipengine.com/v1/pickups Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "label_ids": [
- "se-28529731"
], - "pickup_notes": "string",
- "pickup_window": {
- "start_at": "2018-09-23T15:00:00.000Z",
- "end_at": "2018-09-23T15:00:00.000Z"
}
} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
- "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"
}, - "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
Get Pickup By ID
Authorizations:
path Parameters
pickup_id required string (pickup_resource_id) >= 4 characters Example: pik_3YcKU5zdtJuCqoeNwyqqbWPickup Resource ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/pickups/{pickup_id}https://api.shipengine.com/v1/pickups/{pickup_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
- "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"
}, - "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_3YcKU5zdtJuCqoeNwyqqbWPickup Resource ID
Responses
200 Return the pickup_id of the scheduled pickup that was successfully deleted
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
delete/v1/pickups/{pickup_id}https://api.shipengine.com/v1/pickups/{pickup_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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"
}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.
This error will automatically be reported to our engineers.
get/v1/packageshttps://api.shipengine.com/v1/packages Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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.
This error will automatically be reported to our engineers.
post/v1/packageshttps://api.shipengine.com/v1/packages Request samples
- Payload
Content typeapplication/jsonCopy 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
- 200
- 400
- 500
Content typeapplication/jsonCopy 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-28529731Package ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/packages/{package_id}https://api.shipengine.com/v1/packages/{package_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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-28529731Package ID
Request Body schema: application/json
package_id string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ A string that uniquely identifies the package.
package_code required string [ 1 .. 50 ] characters ^[a-z0-9]+(_[a-z0-9]+)*$ A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
name required string [ 1 .. 50 ] characters dimensions object The custom dimensions for the package.
description string <= 500 characters Nullable Provides a helpful description for the custom package.
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
put/v1/packages/{package_id}https://api.shipengine.com/v1/packages/{package_id} Request samples
- Payload
Content typeapplication/jsonCopy 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
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleDelete 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-28529731Package ID
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
delete/v1/packages/{package_id}https://api.shipengine.com/v1/packages/{package_id} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleMake 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 object The rate options
Responses
200 The request was a success.
400 The request contained errors.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/rateshttps://api.shipengine.com/v1/rates Request samples
- Payload
Content typeapplication/jsonExampleshipment_id_requestCopy 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
- 200
- 400
- 500
Content typeapplication/jsonCopy 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",
- "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",
- "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",
- "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",
- "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,
- "fragile": false,
- "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-26T08:10:11Z",
- "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
Get Bulk Shipment 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 object The rate options
Responses
200 The request was a success.
400 The request contained errors.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/rates/bulkhttps://api.shipengine.com/v1/rates/bulk Request samples
- Payload
Content typeapplication/jsonExamplerate_request_by_shipment_idsCopy 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
- 200
- 400
- 500
Content typeapplication/jsonCopy 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
Get Rate Estimates
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.
This error will automatically be reported to our engineers.
post/v1/rates/estimatehttps://api.shipengine.com/v1/rates/estimate Request samples
- Payload
Content typeapplication/jsonExamplerate_estimate_by_carrier_idCopy 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
- 200
- 400
- 500
Content typeapplication/jsonCopy 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-26T08:10:11Z",
- "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-28529731Rate ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/rates/{rate_id}https://api.shipengine.com/v1/rates/{rate_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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-26T08:10:11Z",
- "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"
]
}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.
This error will automatically be reported to our engineers.
post/v1/service_points/listhttps://api.shipengine.com/v1/service_points/list Request samples
- Payload
Content typeapplication/jsonCopy 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
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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_comCarrier code
country_code required service_point_id required string Example: 614940
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/service_points/{carrier_code}/{country_code}/{service_point_id}https://api.shipengine.com/v1/service_points/{carrier_code}/{country_code}/{service_point_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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 are at the center of the ShipEngine API. A shipment is the first step in creating a shipping label, or creating a manifest. It's also essential for getting shipping rates.
List Shipments
Get list of 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-28529731Batch ID
tag string non-empty Example: tag=Letters_to_santaSearch 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.657ZUsed 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.657ZUsed 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.657ZUsed 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.657ZUsed 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=2Return 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=50The 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_atThe possible shipments sort by values
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/shipmentshttps://api.shipengine.com/v1/shipments Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
- "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",
- "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",
- "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",
- "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,
- "fragile": false,
- "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": {
}
}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.
This error will automatically be reported to our engineers.
post/v1/shipmentshttps://api.shipengine.com/v1/shipments Request samples
- Payload
Content typeapplication/jsonCopy 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",
- "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",
- "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",
- "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",
- "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,
- "fragile": false,
- "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
- 200
- 400
- 500
Content typeapplication/jsonCopy 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",
- "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",
- "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",
- "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",
- "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,
- "fragile": false,
- "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",
- "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",
- "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.
This error will automatically be reported to our engineers.
get/v1/shipments/external_shipment_id/{external_shipment_id}https://api.shipengine.com/v1/shipments/external_shipment_id/{external_shipment_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
- "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",
- "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",
- "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",
- "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,
- "fragile": false,
- "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.
Note: Shipment recognition is currently supported for the United States, Canada, Australia, New Zealand, the United Kingdom, and Ireland.
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.
This error will automatically be reported to our engineers.
put/v1/shipments/recognizehttps://api.shipengine.com/v1/shipments/recognize Request samples
- Payload
Content typeapplication/jsonExampleText onlyThis 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
- 200
- 400
- 500
Content typeapplication/jsonExampletext_onlyThis 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-28529731Shipment ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/shipments/{shipment_id}https://api.shipengine.com/v1/shipments/{shipment_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
- "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",
- "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",
- "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",
- "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,
- "fragile": false,
- "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-28529731Shipment ID
Request Body schema: application/json
carrier_id string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ The carrier account that is billed for the shipping charges
service_code string ^[a-z0-9]+(_[a-z0-9-]+)* ?$ The carrier service used to ship the package, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
shipping_rule_id string [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
external_order_id string Nullable ID that the Order Source assigned
items Array of objects Default: [] Describe the packages included in this shipment as related to potential metadata that was imported from
external order sources
tax_identifiers Array of objects Nullable external_shipment_id string <= 50 characters Nullable A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
Warning: The external_shipment_id is limited to 50 characters. Any additional characters will be truncated.
shipment_number string <= 50 characters Nullable A non-unique user-defined number used to identify a shipment. If undefined, this will match the external_shipment_id of the shipment.
Warning: The shipment_number is limited to 50 characters. Any additional characters will be truncated.
ship_date string <date-time> ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[-+]\d{2}:\d{2}))?$ The date that the shipment was (or will be) shipped. ShipEngine will take the day of week into consideration. For example, if the carrier does not operate on Sundays, then a package that would have shipped on Sunday will ship on Monday instead.
ship_to required object The recipient's mailing address
ship_from required object The shipment's origin address. If you frequently ship from the same location, consider creating a warehouse. Then you can simply specify the warehouse_id rather than the complete address each time.
warehouse_id string [ 1 .. 25 ] characters Nullable ^se(-[a-z0-9]+)+$ Default: null The warehouse that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
return_to object The return address for this shipment. Defaults to the ship_from address.
is_return boolean Nullable Default: false An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
confirmation string Default: "none" Enum: "none" "delivery" "signature" "adult_signature" "direct_signature" "delivery_mailed" "verbal_confirmation" "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.
This error will automatically be reported to our engineers.
put/v1/shipments/{shipment_id}https://api.shipengine.com/v1/shipments/{shipment_id} Request samples
- Payload
Content typeapplication/jsonCopy 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",
- "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",
- "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",
- "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",
- "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,
- "fragile": false,
- "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
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
- "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",
- "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",
- "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",
- "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,
- "fragile": false,
- "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",
- "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",
- "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-28529731Shipment ID
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
put/v1/shipments/{shipment_id}/cancelhttps://api.shipengine.com/v1/shipments/{shipment_id}/cancel Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleGet 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-28529731Shipment ID
query Parameters
created_at_start string <date-time> Example: created_at_start=2019-03-12T19:24:13.657ZUsed to create a filter for when a resource was created (ex. A shipment that was created after a certain time)
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/shipments/{shipment_id}/rateshttps://api.shipengine.com/v1/shipments/{shipment_id}/rates Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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-26T08:10:11Z",
- "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-28529731Shipment ID
tag_name required string (tag_name) non-empty Example: FragileTags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.
Responses
200 The requested object creation was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/shipments/{shipment_id}/tags/{tag_name}https://api.shipengine.com/v1/shipments/{shipment_id}/tags/{tag_name} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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-28529731Shipment ID
tag_name required string (tag_name) non-empty Example: FragileTags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
delete/v1/shipments/{shipment_id}/tags/{tag_name}https://api.shipengine.com/v1/shipments/{shipment_id}/tags/{tag_name} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleCreate a New Tag
Create a new tag for customizing how you track your shipments.
Authorizations:
Request Body schema: application/json
name required string non-empty The tag name.
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.
This error will automatically be reported to our engineers.
post/v1/tagshttps://api.shipengine.com/v1/tags Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "name": "Fragile",
- "color": "#FF0000"
} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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: FragileTags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/tags/{tag_name}https://api.shipengine.com/v1/tags/{tag_name} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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: FragileTags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
delete/v1/tags/{tag_name}https://api.shipengine.com/v1/tags/{tag_name} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleUpdate 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: FragileTags 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: FragileTags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
put/v1/tags/{tag_name}/{new_tag_name}https://api.shipengine.com/v1/tags/{tag_name}/{new_tag_name} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleGet 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
200 OK
post/v1/tokens/ephemeralhttps://api.shipengine.com/v1/tokens/ephemeral Response samples
- 200
Content typeapplication/jsonCopy Expand all Collapse all {- "token": "string",
- "redirect_url": "string"
}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_comA shipping carrier, such as fedex, dhl_express, stamps_com, etc.
tracking_number string non-empty Example: tracking_number=9405511899223197428490The tracking number associated with a shipment
carrier_id string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: carrier_id=se-28529731Carrier ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/trackinghttps://api.shipengine.com/v1/tracking Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy Expand all Collapse all {- "tracking_number": "1Z932R800392060079",
- "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_comA shipping carrier, such as fedex, dhl_express, stamps_com, etc.
tracking_number string non-empty Example: tracking_number=9405511899223197428490The tracking number associated with a shipment
carrier_id string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: carrier_id=se-28529731Carrier ID
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/tracking/starthttps://api.shipengine.com/v1/tracking/start Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleStop Tracking a Package
Unsubscribe from tracking updates for a package.
Authorizations:
query Parameters
carrier_code string non-empty Example: carrier_code=stamps_comA shipping carrier, such as fedex, dhl_express, stamps_com, etc.
tracking_number string non-empty Example: tracking_number=9405511899223197428490The tracking number associated with a shipment
carrier_id string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: carrier_id=se-28529731Carrier ID
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/tracking/stophttps://api.shipengine.com/v1/tracking/stop Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleList 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.
This error will automatically be reported to our engineers.
get/v1/warehouseshttps://api.shipengine.com/v1/warehouses Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
- "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",
- "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 string non-empty Name of the warehouse
origin_address required object The origin address of the warehouse
return_address object The return address associated with the warehouse
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
post/v1/warehouseshttps://api.shipengine.com/v1/warehouses Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "is_default": false,
- "name": "Zero Cool HQ",
- "origin_address": {
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "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",
- "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
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
- "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",
- "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-28529731Warehouse ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/warehouses/{warehouse_id}https://api.shipengine.com/v1/warehouses/{warehouse_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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",
- "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",
- "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-28529731Warehouse ID
Request Body schema: application/json
is_default boolean Nullable Default: false Designates which single warehouse is the default on the account
name required string non-empty Name of the warehouse
origin_address required object The origin address of the warehouse
return_address object The return address associated with the warehouse
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
put/v1/warehouses/{warehouse_id}https://api.shipengine.com/v1/warehouses/{warehouse_id} Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "is_default": false,
- "name": "Zero Cool HQ",
- "origin_address": {
- "name": "John Doe",
- "phone": "+1 204-253-9411 ext. 123",
- "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",
- "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
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleDelete Warehouse By ID
Delete a warehouse by ID
Authorizations:
path Parameters
warehouse_id required string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731Warehouse ID
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
delete/v1/warehouses/{warehouse_id}https://api.shipengine.com/v1/warehouses/{warehouse_id} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleUpdate 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-28529731Warehouse ID
Request Body schema: application/json
is_default boolean Nullable The default property on the warehouse.
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
put/v1/warehouses/{warehouse_id}/settingshttps://api.shipengine.com/v1/warehouses/{warehouse_id}/settings Request samples
- Payload
Content typeapplication/jsonCopy Expand all Collapse all {- "is_default": true
} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleWebhooks 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.
This error will automatically be reported to our engineers.
get/v1/environment/webhookshttps://api.shipengine.com/v1/environment/webhooks Response samples
- 200
- 400
- 500
Content typeapplication/jsonCopy 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 string The name of the webhook
store_id integer <int32> 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.
This error will automatically be reported to our engineers.
post/v1/environment/webhookshttps://api.shipengine.com/v1/environment/webhooks Request samples
- Payload
Content typeapplication/jsonCopy 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
- 200
- 400
- 409
- 500
Content typeapplication/jsonCopy 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-28529731Webhook ID
Responses
200 The request was a success.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
get/v1/environment/webhooks/{webhook_id}https://api.shipengine.com/v1/environment/webhooks/{webhook_id} Response samples
- 200
- 400
- 404
- 500
Content typeapplication/jsonCopy 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-28529731Webhook ID
Request Body schema: application/json
url string <url> non-empty The url that the wehbook sends the request
headers Array of objects Array of custom webhook headers
name string The name of the webhook
store_id integer <int32> 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.
This error will automatically be reported to our engineers.
put/v1/environment/webhooks/{webhook_id}https://api.shipengine.com/v1/environment/webhooks/{webhook_id} Request samples
- Payload
Content typeapplication/jsonCopy 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
- 204
- 400
- 404
- 500
Content typetext/plainNo sampleDelete Webhook By ID
Delete a webhook
Authorizations:
path Parameters
webhook_id required string (se_id) [ 1 .. 25 ] characters ^se(-[a-z0-9]+)+$ Example: se-28529731Webhook ID
Responses
204 The request was successful.
400 The request contained errors.
404 The specified resource does not exist.
500 An error occurred on ShipEngine's side.
This error will automatically be reported to our engineers.
delete/v1/environment/webhooks/{webhook_id}https://api.shipengine.com/v1/environment/webhooks/{webhook_id} Response samples
- 204
- 400
- 404
- 500
Content typetext/plainNo sample