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.
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!
A rate shipment request body
A string that uniquely identifies the shipment
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.
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.
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/rates \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"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"
}
}'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.
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.
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 rates response
An array of invalid shipment rates
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
{ "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, "rate_response": { "rates": [ … ], "invalid_rates": [], "rate_request_id": "se-28529731", "shipment_id": "se-28529731", "created_at": "se-28529731", "status": "working", "errors": [ … ] } }
A rate shipments request body
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.
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.
The rate options
Calculate the duties and tariffs for cross border shipments.
The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/rates/bulk \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"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"
}
}'The request was a success.
A string that uniquely identifies the rate request
A string that uniquely identifies the shipment
An ISO 8601 string that represents a date and time.
The possible rate response status values
An array of errors that were returned while retrieving the bulk rate
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.
[ { "rate_request_id": "se-28529731", "shipment_id": "se-28529731", "created_at": "2018-09-23T15:00:00.000Z", "status": "working", "errors": [ … ] } ]
A rate estimate request body
A two-letter ISO 3166-1 country code
A two-letter ISO 3166-1 country code
The city locality the package is being shipped to
The weight of the package
The possible delivery confirmation values
Indicates whether an address is residential.
An ISO 8601 string that represents a date and time.
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/rates/estimate \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"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"
}'The request was a success.
A string that uniquely identifies the carrier
The shipping amount
The insurance amount
The confirmation amount
Any other charges associated with this rate
Tariff and additional taxes associated with an international shipment.
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.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The possible validation status values
[ { "rate_type": "check", "carrier_id": "se-28529731", "shipping_amount": { … }, "insurance_amount": { … }, "confirmation_amount": { … }, "other_amount": { … }, "tax_amount": { … }, "zone": 6, "package_type": "package", "delivery_days": 5, "guaranteed_service": true, "estimated_delivery_date": "2018-09-23T00:00:00.000Z", "carrier_delivery_days": "string", "ship_date": "2019-08-24T14:15:22Z", "negotiated_rate": true, "service_type": "string", "service_code": "string", "trackable": true, "carrier_code": "string", "carrier_nickname": "string", "carrier_friendly_name": "string", "validation_status": "valid", "warning_messages": [ … ], "error_messages": [ … ], "rate_attributes": [ … ] } ]
curl -i -X GET \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/rates/se-28529731 \
-H 'API-Key: YOUR_API_KEY_HERE'The request was a success.
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
{ "rates": [ { … } ], "invalid_rates": [], "rate_request_id": "se-28529731", "shipment_id": "se-28529731", "created_at": "se-28529731", "status": "working", "errors": [ { … } ] }
Webhooks are a powerful feature of ShipEngine that can save you from sending repeated polling requests to check on the state of something. With webhooks, ShipEngine will automatically contact your servers when the state changes. This can include parcel tracking events, notification of the completion of a batch operation, or new sales orders.