ShipEngine's easy-to-use REST API lets you manage all of your shipping needs without worrying about the complexities of different carrier APIs and protocols. We handle all the heavy lifting so you can focus on providing a first-class shipping experience for your customers at the best possible prices.
Each of ShipEngine's features can be used by itself or in conjunction with each other to build powerful shipping functionality into your application or service.
No matter your shipping volume, failed deliveries and address change surcharges cut into your bottom line and damage perception with customers. Our address validation services ensure your packages make it to the right place the first time. Learn how to leverage our address validation services here.
ShipEngine supports address validation for virtually every country on Earth, including the United States, Canada, Great Britain, Australia, Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160 others.
The possible shipment status values
Search for shipments based on the custom tag added to the shipment object
Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time)
Used to create a filter for when a resource was created, (ex. A shipment that was created before a certain time)
Used to create a filter for when a resource was modified (ex. A shipment that was modified after a certain time)
Used to create a filter for when a resource was modified (ex. A shipment that was modified before a certain time)
Return a specific page of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page is returned.
The number of results to return per response.
curl -i -X GET \
'https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/shipments?shipment_status=pending&batch_id=se-28529731&tag=Letters_to_santa&created_at_start=2019-03-12T19%3A24%3A13.657Z&created_at_end=2019-03-12T19%3A24%3A13.657Z&modified_at_start=2019-03-12T19%3A24%3A13.657Z&modified_at_end=2019-03-12T19%3A24%3A13.657Z&page=2&page_size=50&sales_order_id=string&sort_dir=desc&sort_by=modified_at' \
-H 'API-Key: YOUR_API_KEY_HERE'The request was a success.
The list of shipments returned by the api call
A string that uniquely identifies the shipment
The carrier account that is billed for the shipping charges
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
Warning: The
external_shipment_idis limited to 50 characters. Any additional characters will be truncated.
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_numberis limited to 50 characters. Any additional characters will be truncated.
An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.
An ISO 8601 string that represents a date and time.
An ISO 8601 string that represents a date and time.
The current status of the shipment
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Email for the address owner.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The name of the city or locality
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
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
Additional text about how to handle the shipment at this address.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Email for the address owner.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The name of the city or locality
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
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
The warehouse that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Email for the address owner.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The name of the city or locality
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
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
The type of delivery confirmation that is required for this shipment.
Customs information. This is usually only needed for international shipments.
The type of contents in this shipment. This may impact import duties or customs treatment.
Explanation for contents (required if the contents is provided as other)
Indicates what to do if a package is unable to be delivered.
Specifies the supported terms of trade code (incoterms)
The additional information to put on commercial invoice
importer of records address, anywhere in the world.
Advanced shipment options. These are entirely optional.
This field is used to bill shipping costs to a third party. This field must be used in conjunction with the bill_to_country_code, bill_to_party, and bill_to_postal_code fields.
Indicates whether to bill shipping costs to the recipient or to a third-party. When billing to a third-party, the bill_to_account, bill_to_country_code, and bill_to_postal_code fields must also be set.
The postal code of the third-party that is responsible for shipping costs.
Indicates that the shipment contains alcohol.
Indicates that the shipper is paying the international delivery duties for this shipment. This option is supported by UPS, FedEx, and DHL Express.
Indicates if the shipment contain dry ice
The weight of the dry ice in the shipment
Indicates that the package cannot be processed automatically because it is too large or irregularly shaped. This is primarily for USPS shipments. See Section 1.2 of the USPS parcel standards for details.
Enables Saturday delivery, if supported by the carrier.
Whether to use UPS Ground Freight pricing. If enabled, then a freight_class must also be specified.
The National Motor Freight Traffic Association freight class, such as "77.5", "110", or "250".
An arbitrary field that can be used to store information about the shipment.
An arbitrary field that can be used to store information about the shipment.
An arbitrary field that can be used to store information about the shipment.
Indicates if the package will be picked up or dropped off by the carrier
Indicate to the carrier that this shipment requires additional handling.
Defer payment until package is delivered, instead of when it is ordered.
Third Party Consignee option is a value-added service that allows the shipper to supply goods without commercial invoices being attached
Indicates if the Dangerous goods are present in the shipment
The Windsor framework is a new regulation in the UK that simplifies customs procedures for goods moved from the UK mainland to Northern Ireland.
license_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
invoice_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
certificate_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
Indicates that the contents of the package are fragile and should be handled with care.
Instructs the carrier to deliver the package only to the exact address provided.
Ensures the shipment is immediately flagged for return to the sender if the initial delivery attempt fails.
Indicates the category of goods in the shipment that is subject to special regulatory or compliance requirements.
The insurance provider to use for any insured packages in the shipment.
Arbitrary tags associated with this shipment. Tags can be used to categorize shipments, and shipments can be queried by their tags.
The order sources that are supported by ShipEngine
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.
A string that uniquely identifies this shipment package
A string that uniquely identifies this package type
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
The package weight
The insured value of the package. Requires the insurance_provider field of the shipment to be set.
Custom messages to print on the shipping label for the package. These are typically used to print invoice numbers, product numbers, or other internal reference numbers. Not all carriers support label messages. The number of lines and the maximum length of each line also varies by carrier.
| Carrier | Max lines | Max line length |
|---|---|---|
| USPS (Stamps.com) | 3 | 60 |
| FedEx | 3 | 35 for the first line. 30 for additional lines. |
| UPS | 2 | 35 |
| OnTrac | 2 | 25 |
The tracking number for the package. The format depends on the carrier.
A short description of the package content. Required for shipments moving to, from, and through Mexico.
The combined weight of all packages in the shipment
Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.
Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location
Total number of shipments returned by the api call
Helpful links to other pages of results
The link to the first page of results. This object will always have an href field. If there are no results, then the first page will contain an empty array of items.
The link to the final page of results. This object will always have an href field. If there are no results, then the final page will contain an empty array of items.
The link to the previous page of results. The href field will only be set when the page is 2 or greater.
The link to the next page of results. The href field will only be set when the page is less than pages.
{ "shipments": [ { … } ], "total": 1990, "page": 1, "pages": 1, "links": { "first": { … }, "last": { … }, "prev": { … }, "next": { … } } }
An array of shipments to be created.
The possible validate address values
The carrier account that is billed for the shipping charges
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
Warning: The
external_shipment_idis limited to 50 characters. Any additional characters will be truncated.
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_numberis limited to 50 characters. Any additional characters will be truncated.
An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Email for the address owner.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The name of the city or locality
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
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
Additional text about how to handle the shipment at this address.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Email for the address owner.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The name of the city or locality
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
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
The warehouse that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
The type of delivery confirmation that is required for this shipment.
Customs information. This is usually only needed for international shipments.
Advanced shipment options. These are entirely optional.
The insurance provider to use for any insured packages in the shipment.
The order sources that are supported by ShipEngine
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.
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/shipments \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"shipments": [
{
"validate_address": "no_validation",
"carrier_id": "se-28529731",
"service_code": "usps_first_class_mail",
"shipping_rule_id": "se-28529731",
"external_order_id": "string",
"items": [],
"tax_identifiers": [
{
"taxable_entity_type": "shipper",
"identifier_type": "vat",
"issuing_authority": "string",
"value": "string"
}
],
"external_shipment_id": "string",
"shipment_number": "string",
"ship_date": "2018-09-23T00:00:00.000Z",
"ship_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"address_residential_indicator": "no",
"instructions": "string",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"ship_from": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"address_residential_indicator": "no",
"instructions": "string"
},
"warehouse_id": null,
"return_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"address_residential_indicator": "no",
"instructions": "string"
},
"is_return": false,
"confirmation": "none",
"customs": null,
"advanced_options": {
"bill_to_account": null,
"bill_to_country_code": null,
"bill_to_party": null,
"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": null,
"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": true,
"delivery-as-addressed": false,
"return-after-first-attempt": false,
"regulated_content_type": null
},
"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": "USD",
"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"
}
]
}'The requested object creation was a success.
An array of shipments that were created.
A string that uniquely identifies the shipment
The carrier account that is billed for the shipping charges
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
Warning: The
external_shipment_idis limited to 50 characters. Any additional characters will be truncated.
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_numberis limited to 50 characters. Any additional characters will be truncated.
An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.
An ISO 8601 string that represents a date and time.
An ISO 8601 string that represents a date and time.
The current status of the shipment
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The warehouse that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
The type of delivery confirmation that is required for this shipment.
Customs information. This is usually only needed for international shipments.
Advanced shipment options. These are entirely optional.
The insurance provider to use for any insured packages in the shipment.
Arbitrary tags associated with this shipment. Tags can be used to categorize shipments, and shipments can be queried by their tags.
The order sources that are supported by ShipEngine
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.
Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.
Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location
{ "has_errors": false, "shipments": [ { … } ] }
curl -i -X GET \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/shipments/external_shipment_id/0bcb569d-1727-4ff9-ab49-b2fec0cee5ae \
-H 'API-Key: YOUR_API_KEY_HERE'The request was a success.
A string that uniquely identifies the shipment
The carrier account that is billed for the shipping charges
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
Warning: The
external_shipment_idis limited to 50 characters. Any additional characters will be truncated.
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_numberis limited to 50 characters. Any additional characters will be truncated.
An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.
An ISO 8601 string that represents a date and time.
An ISO 8601 string that represents a date and time.
The current status of the shipment
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
Additional text about how to handle the shipment at this address.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
The warehouse that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
The type of delivery confirmation that is required for this shipment.
Customs information. This is usually only needed for international shipments.
The type of contents in this shipment. This may impact import duties or customs treatment.
Explanation for contents (required if the contents is provided as other)
Indicates what to do if a package is unable to be delivered.
Specifies the supported terms of trade code (incoterms)
The additional information to put on commercial invoice
importer of records address, anywhere in the world.
Advanced shipment options. These are entirely optional.
This field is used to bill shipping costs to a third party. This field must be used in conjunction with the bill_to_country_code, bill_to_party, and bill_to_postal_code fields.
Indicates whether to bill shipping costs to the recipient or to a third-party. When billing to a third-party, the bill_to_account, bill_to_country_code, and bill_to_postal_code fields must also be set.
The postal code of the third-party that is responsible for shipping costs.
Indicates that the shipment contains alcohol.
Indicates that the shipper is paying the international delivery duties for this shipment. This option is supported by UPS, FedEx, and DHL Express.
Indicates that the package cannot be processed automatically because it is too large or irregularly shaped. This is primarily for USPS shipments. See Section 1.2 of the USPS parcel standards for details.
Enables Saturday delivery, if supported by the carrier.
Whether to use UPS Ground Freight pricing. If enabled, then a freight_class must also be specified.
The National Motor Freight Traffic Association freight class, such as "77.5", "110", or "250".
An arbitrary field that can be used to store information about the shipment.
An arbitrary field that can be used to store information about the shipment.
An arbitrary field that can be used to store information about the shipment.
Indicates if the package will be picked up or dropped off by the carrier
Indicate to the carrier that this shipment requires additional handling.
Defer payment until package is delivered, instead of when it is ordered.
Third Party Consignee option is a value-added service that allows the shipper to supply goods without commercial invoices being attached
Indicates if the Dangerous goods are present in the shipment
The Windsor framework is a new regulation in the UK that simplifies customs procedures for goods moved from the UK mainland to Northern Ireland.
license_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
invoice_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
certificate_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
Indicates that the contents of the package are fragile and should be handled with care.
Instructs the carrier to deliver the package only to the exact address provided.
Ensures the shipment is immediately flagged for return to the sender if the initial delivery attempt fails.
Indicates the category of goods in the shipment that is subject to special regulatory or compliance requirements.
The insurance provider to use for any insured packages in the shipment.
Arbitrary tags associated with this shipment. Tags can be used to categorize shipments, and shipments can be queried by their tags.
The order sources that are supported by ShipEngine
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.
A string that uniquely identifies this shipment package
A string that uniquely identifies this package type
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
The package weight
The insured value of the package. Requires the insurance_provider field of the shipment to be set.
Custom messages to print on the shipping label for the package. These are typically used to print invoice numbers, product numbers, or other internal reference numbers. Not all carriers support label messages. The number of lines and the maximum length of each line also varies by carrier.
| Carrier | Max lines | Max line length |
|---|---|---|
| USPS (Stamps.com) | 3 | 60 |
| FedEx | 3 | 35 for the first line. 30 for additional lines. |
| UPS | 2 | 35 |
| OnTrac | 2 | 25 |
The tracking number for the package. The format depends on the carrier.
A short description of the package content. Required for shipments moving to, from, and through Mexico.
The combined weight of all packages in the shipment
Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.
Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location
{ "shipment_id": "se-28529731", "carrier_id": "se-28529731", "service_code": "usps_first_class_mail", "shipping_rule_id": "se-28529731", "external_order_id": "string", "items": [], "tax_identifiers": [ { … } ], "external_shipment_id": "string", "shipment_number": "string", "ship_date": "2018-09-23T00:00:00.000Z", "created_at": "2018-09-23T15:00:00.000Z", "modified_at": "2018-09-23T15:00:00.000Z", "shipment_status": "pending", "ship_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string", "geolocation": [ … ] }, "ship_from": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string" }, "warehouse_id": null, "return_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string" }, "is_return": false, "confirmation": "none", "customs": null, "advanced_options": { "bill_to_account": null, "bill_to_country_code": null, "bill_to_party": null, "bill_to_postal_code": null, "contains_alcohol": false, "delivered_duty_paid": false, "dry_ice": false, "dry_ice_weight": { … }, "non_machinable": false, "saturday_delivery": false, "fedex_freight": { … }, "use_ups_ground_freight_pricing": null, "freight_class": "77.5", "custom_field1": null, "custom_field2": null, "custom_field3": null, "origin_type": null, "additional_handling": null, "shipper_release": null, "collect_on_delivery": { … }, "third_party_consignee": false, "dangerous_goods": false, "dangerous_goods_contact": { … }, "windsor_framework_details": { … }, "license_number": "514785", "invoice_number": "IOC56888", "certificate_number": "784515", "fragile": true, "delivery-as-addressed": false, "return-after-first-attempt": false, "regulated_content_type": null }, "insurance_provider": "none", "tags": [], "order_source_code": "amazon_ca", "packages": [ { … } ], "total_weight": { "value": 0, "unit": "pound" }, "comparison_rate_type": "retail", "zone": 6 }
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.
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.
The unstructured text that contains shipping-related entities
curl -i -X PUT \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/shipments/recognize \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"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"
}'Returns the parsed shipment, as well as a confidence score and a list of all the shipping entities that were recognized in the text.
A confidence score between zero and one that indicates how certain the API is that it understood the text.
The parsed shipment. This shipment may not be complete, depending on how much information was included in the text and how confident the API is about each recognized entity.
Note: The shipment-recognition API does not currently perform any validation of the parsed addresses, so we recommend that you use the address-validation API to ensure that the addresses are correct.
A string that uniquely identifies the shipment
The carrier account that is billed for the shipping charges
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
Warning: The
external_shipment_idis limited to 50 characters. Any additional characters will be truncated.
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_numberis limited to 50 characters. Any additional characters will be truncated.
An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.
An ISO 8601 string that represents a date and time.
An ISO 8601 string that represents a date and time.
The current status of the shipment
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The warehouse that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
The type of delivery confirmation that is required for this shipment.
Customs information. This is usually only needed for international shipments.
Advanced shipment options. These are entirely optional.
The insurance provider to use for any insured packages in the shipment.
Arbitrary tags associated with this shipment. Tags can be used to categorize shipments, and shipments can be queried by their tags.
The order sources that are supported by ShipEngine
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.
Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.
Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location
All of the entities that were recognized in the text. An "entity" is a single piece of data, such as a city, a postal code, a carrier name, or a package weight. Each entity includes the original text and the parsed value.
The Entity type (e.g. "weight", "person", "address_line1", etc.)
A confidence score between zero and one that indicates how certain the API is that it correctly recognized this entity
The substring from the original text that was recognized as this entity
The index of the first character of this entity within the original text
The index of the last character of this entity within the original text
The normalized value of the entity.
Most entity results have a value field, which is the normalized value of the entity. For example, if the substring "john doe" was recognized as a "person" entity, then the value might be normalized to have proper capitalization (e.g. "John Doe"). Or if the substring "ft worth" was recognized as a "city" entity, then the value might be normalized to "Fort Worth".
Some entities have other information in addition to, or instead of a value. For example, a "dimensions" entity will have separate fields for length, width, height, and unit.
This response shows that the shipment-recognition API was able to recognize all the shipping entities in the text. Notice that the ship_from field is not populated, since it wasn't included in the request or in the parsed text.
{ "score": 0.9031369611169101, "shipment": { "carrier_id": "se-118608", "service_code": "usps_first_class_mail", "confirmation": "adult_signature", "ship_to": { … }, "packages": [ … ] }, "entities": [ { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … } ] }
curl -i -X GET \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/shipments/se-28529731 \
-H 'API-Key: YOUR_API_KEY_HERE'The request was a success.
A string that uniquely identifies the shipment
The carrier account that is billed for the shipping charges
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
Warning: The
external_shipment_idis limited to 50 characters. Any additional characters will be truncated.
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_numberis limited to 50 characters. Any additional characters will be truncated.
An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.
An ISO 8601 string that represents a date and time.
An ISO 8601 string that represents a date and time.
The current status of the shipment
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
Additional text about how to handle the shipment at this address.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
The warehouse that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
The type of delivery confirmation that is required for this shipment.
Customs information. This is usually only needed for international shipments.
The type of contents in this shipment. This may impact import duties or customs treatment.
Explanation for contents (required if the contents is provided as other)
Indicates what to do if a package is unable to be delivered.
Specifies the supported terms of trade code (incoterms)
The additional information to put on commercial invoice
importer of records address, anywhere in the world.
Advanced shipment options. These are entirely optional.
This field is used to bill shipping costs to a third party. This field must be used in conjunction with the bill_to_country_code, bill_to_party, and bill_to_postal_code fields.
Indicates whether to bill shipping costs to the recipient or to a third-party. When billing to a third-party, the bill_to_account, bill_to_country_code, and bill_to_postal_code fields must also be set.
The postal code of the third-party that is responsible for shipping costs.
Indicates that the shipment contains alcohol.
Indicates that the shipper is paying the international delivery duties for this shipment. This option is supported by UPS, FedEx, and DHL Express.
Indicates that the package cannot be processed automatically because it is too large or irregularly shaped. This is primarily for USPS shipments. See Section 1.2 of the USPS parcel standards for details.
Enables Saturday delivery, if supported by the carrier.
Whether to use UPS Ground Freight pricing. If enabled, then a freight_class must also be specified.
The National Motor Freight Traffic Association freight class, such as "77.5", "110", or "250".
An arbitrary field that can be used to store information about the shipment.
An arbitrary field that can be used to store information about the shipment.
An arbitrary field that can be used to store information about the shipment.
Indicates if the package will be picked up or dropped off by the carrier
Indicate to the carrier that this shipment requires additional handling.
Defer payment until package is delivered, instead of when it is ordered.
Third Party Consignee option is a value-added service that allows the shipper to supply goods without commercial invoices being attached
Indicates if the Dangerous goods are present in the shipment
The Windsor framework is a new regulation in the UK that simplifies customs procedures for goods moved from the UK mainland to Northern Ireland.
license_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
invoice_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
certificate_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
Indicates that the contents of the package are fragile and should be handled with care.
Instructs the carrier to deliver the package only to the exact address provided.
Ensures the shipment is immediately flagged for return to the sender if the initial delivery attempt fails.
Indicates the category of goods in the shipment that is subject to special regulatory or compliance requirements.
The insurance provider to use for any insured packages in the shipment.
Arbitrary tags associated with this shipment. Tags can be used to categorize shipments, and shipments can be queried by their tags.
The order sources that are supported by ShipEngine
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.
A string that uniquely identifies this shipment package
A string that uniquely identifies this package type
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
The package weight
The insured value of the package. Requires the insurance_provider field of the shipment to be set.
Custom messages to print on the shipping label for the package. These are typically used to print invoice numbers, product numbers, or other internal reference numbers. Not all carriers support label messages. The number of lines and the maximum length of each line also varies by carrier.
| Carrier | Max lines | Max line length |
|---|---|---|
| USPS (Stamps.com) | 3 | 60 |
| FedEx | 3 | 35 for the first line. 30 for additional lines. |
| UPS | 2 | 35 |
| OnTrac | 2 | 25 |
The tracking number for the package. The format depends on the carrier.
A short description of the package content. Required for shipments moving to, from, and through Mexico.
The combined weight of all packages in the shipment
Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.
Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location
{ "shipment_id": "se-28529731", "carrier_id": "se-28529731", "service_code": "usps_first_class_mail", "shipping_rule_id": "se-28529731", "external_order_id": "string", "items": [], "tax_identifiers": [ { … } ], "external_shipment_id": "string", "shipment_number": "string", "ship_date": "2018-09-23T00:00:00.000Z", "created_at": "2018-09-23T15:00:00.000Z", "modified_at": "2018-09-23T15:00:00.000Z", "shipment_status": "pending", "ship_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string", "geolocation": [ … ] }, "ship_from": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string" }, "warehouse_id": null, "return_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string" }, "is_return": false, "confirmation": "none", "customs": null, "advanced_options": { "bill_to_account": null, "bill_to_country_code": null, "bill_to_party": null, "bill_to_postal_code": null, "contains_alcohol": false, "delivered_duty_paid": false, "dry_ice": false, "dry_ice_weight": { … }, "non_machinable": false, "saturday_delivery": false, "fedex_freight": { … }, "use_ups_ground_freight_pricing": null, "freight_class": "77.5", "custom_field1": null, "custom_field2": null, "custom_field3": null, "origin_type": null, "additional_handling": null, "shipper_release": null, "collect_on_delivery": { … }, "third_party_consignee": false, "dangerous_goods": false, "dangerous_goods_contact": { … }, "windsor_framework_details": { … }, "license_number": "514785", "invoice_number": "IOC56888", "certificate_number": "784515", "fragile": true, "delivery-as-addressed": false, "return-after-first-attempt": false, "regulated_content_type": null }, "insurance_provider": "none", "tags": [], "order_source_code": "amazon_ca", "packages": [ { … } ], "total_weight": { "value": 0, "unit": "pound" }, "comparison_rate_type": "retail", "zone": 6 }
The carrier account that is billed for the shipping charges
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
Warning: The
external_shipment_idis limited to 50 characters. Any additional characters will be truncated.
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_numberis limited to 50 characters. Any additional characters will be truncated.
An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
Additional text about how to handle the shipment at this address.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
The warehouse that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
The type of delivery confirmation that is required for this shipment.
Customs information. This is usually only needed for international shipments.
Advanced shipment options. These are entirely optional.
The insurance provider to use for any insured packages in the shipment.
The order sources that are supported by ShipEngine
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.
Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.
curl -i -X PUT \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/shipments/se-28529731 \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"carrier_id": "se-28529731",
"service_code": "usps_first_class_mail",
"shipping_rule_id": "se-28529731",
"external_order_id": "string",
"items": [],
"tax_identifiers": [
{
"taxable_entity_type": "shipper",
"identifier_type": "vat",
"issuing_authority": "string",
"value": "string"
}
],
"external_shipment_id": "string",
"shipment_number": "string",
"ship_date": "2018-09-23T00:00:00.000Z",
"ship_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"address_residential_indicator": "no",
"instructions": "string",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"ship_from": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"address_residential_indicator": "no",
"instructions": "string"
},
"warehouse_id": null,
"return_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"address_residential_indicator": "no",
"instructions": "string"
},
"is_return": false,
"confirmation": "none",
"customs": null,
"advanced_options": {
"bill_to_account": null,
"bill_to_country_code": null,
"bill_to_party": null,
"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": null,
"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": true,
"delivery-as-addressed": false,
"return-after-first-attempt": false,
"regulated_content_type": null
},
"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": "USD",
"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"
}'The request was a success.
A string that uniquely identifies the shipment
The carrier account that is billed for the shipping charges
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
Warning: The
external_shipment_idis limited to 50 characters. Any additional characters will be truncated.
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_numberis limited to 50 characters. Any additional characters will be truncated.
An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.
An ISO 8601 string that represents a date and time.
An ISO 8601 string that represents a date and time.
The current status of the shipment
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
Additional text about how to handle the shipment at this address.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
The warehouse that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
The type of delivery confirmation that is required for this shipment.
Customs information. This is usually only needed for international shipments.
The type of contents in this shipment. This may impact import duties or customs treatment.
Explanation for contents (required if the contents is provided as other)
Indicates what to do if a package is unable to be delivered.
Specifies the supported terms of trade code (incoterms)
The additional information to put on commercial invoice
importer of records address, anywhere in the world.
Advanced shipment options. These are entirely optional.
This field is used to bill shipping costs to a third party. This field must be used in conjunction with the bill_to_country_code, bill_to_party, and bill_to_postal_code fields.
Indicates whether to bill shipping costs to the recipient or to a third-party. When billing to a third-party, the bill_to_account, bill_to_country_code, and bill_to_postal_code fields must also be set.
The postal code of the third-party that is responsible for shipping costs.
Indicates that the shipment contains alcohol.
Indicates that the shipper is paying the international delivery duties for this shipment. This option is supported by UPS, FedEx, and DHL Express.
Indicates that the package cannot be processed automatically because it is too large or irregularly shaped. This is primarily for USPS shipments. See Section 1.2 of the USPS parcel standards for details.
Enables Saturday delivery, if supported by the carrier.
Whether to use UPS Ground Freight pricing. If enabled, then a freight_class must also be specified.
The National Motor Freight Traffic Association freight class, such as "77.5", "110", or "250".
An arbitrary field that can be used to store information about the shipment.
An arbitrary field that can be used to store information about the shipment.
An arbitrary field that can be used to store information about the shipment.
Indicates if the package will be picked up or dropped off by the carrier
Indicate to the carrier that this shipment requires additional handling.
Defer payment until package is delivered, instead of when it is ordered.
Third Party Consignee option is a value-added service that allows the shipper to supply goods without commercial invoices being attached
Indicates if the Dangerous goods are present in the shipment
The Windsor framework is a new regulation in the UK that simplifies customs procedures for goods moved from the UK mainland to Northern Ireland.
license_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
invoice_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
certificate_number - This field was part of a historical implementation for passing customs-related data. For new integrations, please use the corresponding parameters within the shipment.customs object.
Indicates that the contents of the package are fragile and should be handled with care.
Instructs the carrier to deliver the package only to the exact address provided.
Ensures the shipment is immediately flagged for return to the sender if the initial delivery attempt fails.
Indicates the category of goods in the shipment that is subject to special regulatory or compliance requirements.
The insurance provider to use for any insured packages in the shipment.
Arbitrary tags associated with this shipment. Tags can be used to categorize shipments, and shipments can be queried by their tags.
The order sources that are supported by ShipEngine
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.
A string that uniquely identifies this shipment package
A string that uniquely identifies this package type
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
The package weight
The insured value of the package. Requires the insurance_provider field of the shipment to be set.
Custom messages to print on the shipping label for the package. These are typically used to print invoice numbers, product numbers, or other internal reference numbers. Not all carriers support label messages. The number of lines and the maximum length of each line also varies by carrier.
| Carrier | Max lines | Max line length |
|---|---|---|
| USPS (Stamps.com) | 3 | 60 |
| FedEx | 3 | 35 for the first line. 30 for additional lines. |
| UPS | 2 | 35 |
| OnTrac | 2 | 25 |
The tracking number for the package. The format depends on the carrier.
A short description of the package content. Required for shipments moving to, from, and through Mexico.
The combined weight of all packages in the shipment
Calculate a rate for this shipment with the requested carrier using a ratecard that differs from the default. Only supported for UPS and USPS.
Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location
The address validation
The possible address validation status values
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Email for the address owner.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The name of the city or locality
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
A two-letter ISO 3166-1 country code
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Email for the address owner.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The name of the city or locality
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
A two-letter ISO 3166-1 country code
The list of messages that were generated during the address validation request.
The error codes that can be returned by the address validation API
Message explaining the address validation error
The different types of messages that can be returned by the address validation API
The detailed error codes that can be returned by the address validation API
{ "shipment_id": "se-28529731", "carrier_id": "se-28529731", "service_code": "usps_first_class_mail", "shipping_rule_id": "se-28529731", "external_order_id": "string", "items": [], "tax_identifiers": [ { … } ], "external_shipment_id": "string", "shipment_number": "string", "ship_date": "2018-09-23T00:00:00.000Z", "created_at": "2018-09-23T15:00:00.000Z", "modified_at": "2018-09-23T15:00:00.000Z", "shipment_status": "pending", "ship_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string", "geolocation": [ … ] }, "ship_from": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string" }, "warehouse_id": null, "return_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string" }, "is_return": false, "confirmation": "none", "customs": null, "advanced_options": { "bill_to_account": null, "bill_to_country_code": null, "bill_to_party": null, "bill_to_postal_code": null, "contains_alcohol": false, "delivered_duty_paid": false, "dry_ice": false, "dry_ice_weight": { … }, "non_machinable": false, "saturday_delivery": false, "fedex_freight": { … }, "use_ups_ground_freight_pricing": null, "freight_class": "77.5", "custom_field1": null, "custom_field2": null, "custom_field3": null, "origin_type": null, "additional_handling": null, "shipper_release": null, "collect_on_delivery": { … }, "third_party_consignee": false, "dangerous_goods": false, "dangerous_goods_contact": { … }, "windsor_framework_details": { … }, "license_number": "514785", "invoice_number": "IOC56888", "certificate_number": "784515", "fragile": true, "delivery-as-addressed": false, "return-after-first-attempt": false, "regulated_content_type": null }, "insurance_provider": "none", "tags": [], "order_source_code": "amazon_ca", "packages": [ { … } ], "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": { … }, "matched_address": { … }, "messages": [] } }
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
curl -i -X PUT \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/shipments/se-28529731/cancel \
-H 'API-Key: YOUR_API_KEY_HERE'No response examplecurl -i -X GET \
'https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/shipments/se-28529731/rates?created_at_start=2019-03-12T19%3A24%3A13.657Z' \
-H 'API-Key: YOUR_API_KEY_HERE'The request was a success.
An array of shipment rates
A string that uniquely identifies the rate
The possible rate type values
A string that uniquely identifies the carrier
The shipping amount. Should be added with confirmation_amount, insurance_amount and other_amount to calculate the total purchase price.
The insurance amount. Should be added with shipping_amount, confirmation_amount and other_amount to calculate the total purchase price.
The confirmation amount. Should be added with shipping_amount, insurance_amount and other_amount to calculate the total purchase price.
The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html
Any other charges associated with this rate. Should be added with shipping_amount, insurance_amount and confirmation_amount to calculate the total purchase price.
The total shipping cost for the specified comparison_rate_type.
Tariff and additional taxes associated with an international shipment.
A list of rate details that are associated with this rate. This is useful for displaying a breakdown of the rate to the user.
Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location
package type that this rate was estimated for
The number of days estimated for delivery, this will show the actual delivery time if for example, the package gets shipped on a Friday
An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.
The possible validation status values
An array of invalid shipment rates
A string that uniquely identifies the rate
The possible rate type values
A string that uniquely identifies the carrier
The shipping amount. Should be added with confirmation_amount, insurance_amount and other_amount to calculate the total purchase price.
The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html
The insurance amount. Should be added with shipping_amount, confirmation_amount and other_amount to calculate the total purchase price.
The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html
The confirmation amount. Should be added with shipping_amount, insurance_amount and other_amount to calculate the total purchase price.
The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html
Any other charges associated with this rate. Should be added with shipping_amount, insurance_amount and confirmation_amount to calculate the total purchase price.
The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html
The total shipping cost for the specified comparison_rate_type.
Tariff and additional taxes associated with an international shipment.
A list of rate details that are associated with this rate. This is useful for displaying a breakdown of the rate to the user.
Certain carriers base their rates off of custom zones that vary depending upon the ship_to and ship_from location
package type that this rate was estimated for
The number of days estimated for delivery, this will show the actual delivery time if for example, the package gets shipped on a Friday
An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.
The possible validation status values
A string that uniquely identifies the rate request
A string that uniquely identifies the shipment
When the rate was created
The possible rate response status values
The source of the error, as indicated by the name this informs us if the API call failed because of the carrier, the order source, or the ShipEngine API itself.
The type of error
The error code specified for the failed API Call
An error message associated with the failed API call
A string that uniquely identifies the carrier that generated the error.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
{ "rates": [ { … } ], "invalid_rates": [], "rate_request_id": "se-28529731", "shipment_id": "se-28529731", "created_at": "se-28529731", "status": "working", "errors": [ { … } ] }
Shipment ID
Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/shipments/se-28529731/tags/Fragile \
-H 'API-Key: YOUR_API_KEY_HERE'{ "tags": [ "Fragile" ] }
Shipment ID
Tags are arbitrary strings that you can use to categorize shipments. For example, you may want to use tags to distinguish between domestic and international shipments, or between insured and uninsured shipments. Or maybe you want to create a tag for each of your customers so you can easily retrieve every shipment for a customer.
curl -i -X DELETE \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/shipments/se-28529731/tags/Fragile \
-H 'API-Key: YOUR_API_KEY_HERE'No response exampleWebhooks 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 state changes. This can include parcel tracking events, notification of the completion of a batch operation, or new sales orders.