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 list of up to 30 label ids to include in the combined label document. Note that to avoid response size limits, you should only expect to be able to combine 30 single page labels similar in size to that of USPS labels.
The file format for the combined label document; note that currently only "pdf" is supported.
There are two different ways to download a label:
| Label Download Type | Description |
|---|---|
url | You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days. |
inline | You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. |
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/documents/combined_labels \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"label_ids": [
"se-28529731"
],
"label_format": "pdf",
"label_download_type": "inline"
}'{ "label_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "pdf": "http://api.shipengine.com/v1/labels/se-28529731", "png": "http://api.shipengine.com/v1/labels/se-28529731", "zpl": "http://api.shipengine.com/v1/labels/se-28529731" } }
This endpoint returns a list of labels that you've created. You can optionally filter the results as well as control their sort order and the number of results returned at a time.
By default, all labels are returned, 25 at a time, starting with the most recently created ones. You can combine multiple filter options to narrow-down the results. For example, if you only want to get your UPS labels for your east coast warehouse you could query by both warehouse_id and carrier_id
Only return labels that are currently in the specified status
Only return labels for a specific carrier service
Only return labels for a specific carrier account
Only return labels with a specific tracking number
Only return labels that were created in a specific batch
Shipment ID
Only return labels that originate from a specific warehouse
Only return labels that were created on or after a specific date/time
Only return labels that were created on or before a specific date/time
Only return labels with specific refund status/es.
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/labels?label_status=processing&service_code=usps_first_class_mail&carrier_id=se-28529731&tracking_number=9405511899223197428490&batch_id=se-28529731&rate_id=se-28529731&shipment_id=se-28529731&warehouse_id=se-28529731&created_at_start=2019-03-12T19%3A24%3A13.657Z&created_at_end=2019-03-12T19%3A24%3A13.657Z&refund_status=pending%2Capproved&page=2&page_size=50&sort_dir=desc&sort_by=modified_at' \
-H 'API-Key: YOUR_API_KEY_HERE'The response includes a labels array containing a page of results (as determined by the page_size query parameter). It also includes other useful information, such as the total number of labels that match the query criteria, the number of pages of results, and the URLs of the first, last, next, and previous pages of results.
The labels that matched the query criteria. If no matching labels were found, then this array is empty; otherwise, it contains one page of results. The last page of results may have fewer labels than the page_size.
A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created.
The possible statuses that a shipping label can be in.
| Status | Description |
|---|---|
processing | When labels are created in a batch, it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in processing status. |
completed | The label was successfully created |
error | The label could not be created due to an error, such as an invalid delivery address |
voided | The label has been voided |
The shipment that this label is for. ShipEngine can create a shipment for you automatically when you create a label, or you can create your own shipment and then use it to print a label
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
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.
The cost of shipping, delivery confirmation, and other carrier charges. This amount does not include insurance costs.
The insurance cost for this package. Add this to the shipment_cost field to get the total cost.
The total shipping cost for the specified comparison_rate_type.
A list of rate details that are associated with shipping cost. This is useful for displaying a breakdown of the rate to the user.
The tracking number for the package. Tracking number formats vary across carriers.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
If this label was created as part of a batch, then this is the unique ID of that batch.
The unique ID of the carrier account that was used to create this label
The label charge event.
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
An ISO 8601 string that represents a date and time.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.
The label image resource that was used to create a custom label image.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The current status of the package, such as in_transit or delivered
The type of delivery confirmation that is required for this shipment.
Reference to the various downloadable file formats for the generated label
The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any. Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it.
The QR code download for the package
The paperless details which may contain elements like href, instructions and handoff_code.
The link to submit an insurance claim for the shipment. This field is null if the shipment is not insured or if the insurance provider does not support online claim submission.
The label's package(s).
Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.
Additional information some carriers may provide by which to identify a given label in their system.
The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
The current page number of results. For example, if there are 80 results, and the page size is 25, then page could be 1, 2, 3, or 4. The first three pages would contain 25 items each, and the fourth page would contain the five remaining items.
The total number of pages of results. For example, if there are 80 results, and the page size is 25, then pages would be 4. The first three pages would contain 25 items each, and the fourth page would contain the five remaining items. If there are no results, then pages will be zero.
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.
{ "labels": [ { … } ], "total": 2750, "page": 1, "pages": 4, "links": { "first": { … }, "last": { … }, "prev": { … }, "next": { … } } }
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 information necessary to ship a package, such as the origin, the destination, the carrier service, and the package dimensions and weight.
Note: Either
ship_fromorwarehouse_idmust be set.
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 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.
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 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.
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 |
A short description of the package content. Required for shipments moving to, from, and through Mexico.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
The label charge event.
The label_id of the original (outgoing) label that the return label is for. This associates the two labels together, which is required by some carriers.
The possible validate address values
There are two different ways to download a label:
| Label Download Type | Description |
|---|---|
url | You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days. |
inline | You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. |
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
The label image resource that was used to create a custom label image.
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/labels \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"ship_to_service_point_id": "614940",
"ship_from_service_point_id": "614940",
"shipment": {
"carrier_id": "se-28529731",
"service_code": "usps_first_class_mail",
"shipping_rule_id": "se-28529731",
"external_order_id": "string",
"items": [],
"tax_identifiers": [
{
"taxable_entity_type": "shipper",
"identifier_type": "vat",
"issuing_authority": "string",
"value": "string"
}
],
"external_shipment_id": "string",
"shipment_number": "string",
"ship_date": "2018-09-23T00:00:00.000Z",
"ship_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"address_residential_indicator": "no",
"instructions": "string",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"ship_from": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"address_residential_indicator": "no",
"instructions": "string"
},
"warehouse_id": 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"
},
"is_return_label": true,
"rma_number": "string",
"charge_event": "carrier_default",
"outbound_label_id": "se-28529731",
"test_label": false,
"validate_address": "no_validation",
"label_download_type": "url",
"label_format": "pdf",
"display_scheme": "label",
"label_layout": "4x6",
"label_image_id": "img_DtBXupDBxREpHnwEXhTfgK"
}'The requested object creation was a success.
A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created.
The possible statuses that a shipping label can be in.
| Status | Description |
|---|---|
processing | When labels are created in a batch, it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in processing status. |
completed | The label was successfully created |
error | The label could not be created due to an error, such as an invalid delivery address |
voided | The label has been voided |
The shipment that this label is for. ShipEngine can create a shipment for you automatically when you create a label, or you can create your own shipment and then use it to print a label
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
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.
The cost of shipping, delivery confirmation, and other carrier charges. This amount does not include insurance costs.
The insurance cost for this package. Add this to the shipment_cost field to get the total cost.
The total shipping cost for the specified comparison_rate_type.
A list of rate details that are associated with shipping cost. This is useful for displaying a breakdown of the rate to the user.
The tracking number for the package. Tracking number formats vary across carriers.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
If this label was created as part of a batch, then this is the unique ID of that batch.
The unique ID of the carrier account that was used to create this label
The label charge event.
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
An ISO 8601 string that represents a date and time.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.
The label image resource that was used to create a custom label image.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The current status of the package, such as in_transit or delivered
The type of delivery confirmation that is required for this shipment.
Reference to the various downloadable file formats for the generated label
The URL of the linked resource, if any
The URL for the pdf generated label
The URL for the png generated label
The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any. Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it.
The QR code download for the package
The paperless details which may contain elements like href, instructions and handoff_code.
The URL of the linked resource, if any
The instructions for the paperless download.
The link to submit an insurance claim for the shipment. This field is null if the shipment is not insured or if the insurance provider does not support online claim submission.
The label's package(s).
Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.
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.
The tracking number for the package. The format depends on the carrier.
The form download for any customs that are needed
The paperless details which may contain elements like href, instructions and handoff_code.
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 |
A short description of the package content. Required for shipments moving to, from, and through Mexico.
Whether the package has label documents available for download
Whether the package has QR code documents available for download
Whether the package has paperless documents available for download
Additional information some carriers may provide by which to identify a given label in their system.
The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
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.
Indicates how a label was voided. refund_assist means the label was voided through the Refund Assist program, while manual means it was voided manually by the user.
{ "label_id": "se-28529731", "status": "processing", "shipment_id": "se-28529731", "external_shipment_id": "string", "external_order_id": "string", "ship_date": "2018-09-23T00:00:00.000Z", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 0 }, "insurance_cost": { "currency": "string", "amount": 0 }, "requested_comparison_amount": { "currency": "string", "amount": 0 }, "rate_details": [ { … } ], "tracking_number": "782758401696", "is_return_label": true, "rma_number": "string", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-28529731", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "confirmation": "none", "label_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "pdf": "http://api.shipengine.com/v1/labels/se-28529731", "png": "http://api.shipengine.com/v1/labels/se-28529731", "zpl": "http://api.shipengine.com/v1/labels/se-28529731" }, "form_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "qr_code_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "paperless_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "instructions": null, "handoff_code": null }, "insurance_claim": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "packages": [ { … } ], "alternative_identifiers": [ { … } ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234", "ship_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string", "geolocation": [ … ] }, "void_type": "manual", "refund_details": { "refund_status": "request_scheduled", "request_date": "2018-09-23T15:00:00.000Z", "amount_paid": { … }, "amount_requested": { … }, "amount_approved": { … }, "amount_credited": { … } } }
There are two different ways to download a label:
| Label Download Type | Description |
|---|---|
url | You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days. |
inline | You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. |
curl -i -X GET \
'https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/labels/external_shipment_id/0bcb569d-1727-4ff9-ab49-b2fec0cee5ae?label_download_type=url' \
-H 'API-Key: YOUR_API_KEY_HERE'The requested object creation was a success.
A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created.
The possible statuses that a shipping label can be in.
| Status | Description |
|---|---|
processing | When labels are created in a batch, it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in processing status. |
completed | The label was successfully created |
error | The label could not be created due to an error, such as an invalid delivery address |
voided | The label has been voided |
The shipment that this label is for. ShipEngine can create a shipment for you automatically when you create a label, or you can create your own shipment and then use it to print a label
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
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.
The cost of shipping, delivery confirmation, and other carrier charges. This amount does not include insurance costs.
The insurance cost for this package. Add this to the shipment_cost field to get the total cost.
The total shipping cost for the specified comparison_rate_type.
A list of rate details that are associated with shipping cost. This is useful for displaying a breakdown of the rate to the user.
The tracking number for the package. Tracking number formats vary across carriers.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
If this label was created as part of a batch, then this is the unique ID of that batch.
The unique ID of the carrier account that was used to create this label
The label charge event.
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
An ISO 8601 string that represents a date and time.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.
The label image resource that was used to create a custom label image.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The current status of the package, such as in_transit or delivered
The type of delivery confirmation that is required for this shipment.
Reference to the various downloadable file formats for the generated label
The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any. Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it.
The paperless details which may contain elements like href, instructions and handoff_code.
The link to submit an insurance claim for the shipment. This field is null if the shipment is not insured or if the insurance provider does not support online claim submission.
The label's package(s).
Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.
Additional information some carriers may provide by which to identify a given label in their system.
The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
Indicates how a label was voided. refund_assist means the label was voided through the Refund Assist program, while manual means it was voided manually by the user.
{ "label_id": "se-28529731", "status": "processing", "shipment_id": "se-28529731", "external_shipment_id": "string", "external_order_id": "string", "ship_date": "2018-09-23T00:00:00.000Z", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 0 }, "insurance_cost": { "currency": "string", "amount": 0 }, "requested_comparison_amount": { "currency": "string", "amount": 0 }, "rate_details": [ { … } ], "tracking_number": "782758401696", "is_return_label": true, "rma_number": "string", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-28529731", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "confirmation": "none", "label_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "pdf": "http://api.shipengine.com/v1/labels/se-28529731", "png": "http://api.shipengine.com/v1/labels/se-28529731", "zpl": "http://api.shipengine.com/v1/labels/se-28529731" }, "form_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "qr_code_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "paperless_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "instructions": null, "handoff_code": null }, "insurance_claim": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "packages": [ { … } ], "alternative_identifiers": [ { … } ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234", "ship_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string", "geolocation": [ … ] }, "void_type": "manual", "refund_details": { "refund_status": "request_scheduled", "request_date": "2018-09-23T15:00:00.000Z", "amount_paid": { … }, "amount_requested": { … }, "amount_approved": { … }, "amount_credited": { … } } }
Optional - Value will be saved in the shipment's advanced_options > custom_field1
Optional - Value will be saved in the shipment's advanced_options > custom_field2
Optional - Value will be saved in the shipment's advanced_options > custom_field3
The possible validate address values
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
There are two different ways to download a label:
| Label Download Type | Description |
|---|---|
url | You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days. |
inline | You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. |
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/labels/rates/se-28529731 \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"custom_field1": "string",
"custom_field2": "string",
"custom_field3": "string",
"validate_address": "no_validation",
"label_layout": "4x6",
"label_format": "pdf",
"label_download_type": "url",
"display_scheme": "label"
}'The requested object creation was a success.
A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created.
The possible statuses that a shipping label can be in.
| Status | Description |
|---|---|
processing | When labels are created in a batch, it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in processing status. |
completed | The label was successfully created |
error | The label could not be created due to an error, such as an invalid delivery address |
voided | The label has been voided |
The shipment that this label is for. ShipEngine can create a shipment for you automatically when you create a label, or you can create your own shipment and then use it to print a label
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
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.
The cost of shipping, delivery confirmation, and other carrier charges. This amount does not include insurance costs.
The insurance cost for this package. Add this to the shipment_cost field to get the total cost.
The total shipping cost for the specified comparison_rate_type.
A list of rate details that are associated with shipping cost. This is useful for displaying a breakdown of the rate to the user.
The tracking number for the package. Tracking number formats vary across carriers.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
If this label was created as part of a batch, then this is the unique ID of that batch.
The unique ID of the carrier account that was used to create this label
The label charge event.
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
An ISO 8601 string that represents a date and time.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.
The label image resource that was used to create a custom label image.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The current status of the package, such as in_transit or delivered
The type of delivery confirmation that is required for this shipment.
Reference to the various downloadable file formats for the generated label
The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any. Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it.
The paperless details which may contain elements like href, instructions and handoff_code.
The link to submit an insurance claim for the shipment. This field is null if the shipment is not insured or if the insurance provider does not support online claim submission.
The label's package(s).
Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.
Additional information some carriers may provide by which to identify a given label in their system.
The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
Indicates how a label was voided. refund_assist means the label was voided through the Refund Assist program, while manual means it was voided manually by the user.
{ "label_id": "se-28529731", "status": "processing", "shipment_id": "se-28529731", "external_shipment_id": "string", "external_order_id": "string", "ship_date": "2018-09-23T00:00:00.000Z", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 0 }, "insurance_cost": { "currency": "string", "amount": 0 }, "requested_comparison_amount": { "currency": "string", "amount": 0 }, "rate_details": [ { … } ], "tracking_number": "782758401696", "is_return_label": true, "rma_number": "string", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-28529731", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "confirmation": "none", "label_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "pdf": "http://api.shipengine.com/v1/labels/se-28529731", "png": "http://api.shipengine.com/v1/labels/se-28529731", "zpl": "http://api.shipengine.com/v1/labels/se-28529731" }, "form_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "qr_code_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "paperless_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "instructions": null, "handoff_code": null }, "insurance_claim": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "packages": [ { … } ], "alternative_identifiers": [ { … } ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234", "ship_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string", "geolocation": [ … ] }, "void_type": "manual", "refund_details": { "refund_status": "request_scheduled", "request_date": "2018-09-23T15:00:00.000Z", "amount_paid": { … }, "amount_requested": { … }, "amount_approved": { … }, "amount_credited": { … } } }
Purchase and print a shipping label using the Rate Shopper. The Rate Shopper automatically selects the optimal carrier and service from your wallet carriers based on your specified rate selection strategy (cheapest, fastest, or best_value). For more information about this in the rates documentation.
Label creation details with inline shipment
The information necessary to ship a package for Rate Shopper, such as the origin, the destination, and the package dimensions and weight.
Note: This schema excludes carrier_id, service_code, and shipping_rule_id as these are automatically selected by the Rate Shopper based on your chosen strategy.
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.
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.
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.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
The label charge event.
The label_id of the original (outgoing) label that the return label is for. This associates the two labels together, which is required by some carriers.
The possible validate address values
There are two different ways to download a label:
| Label Download Type | Description |
|---|---|
url | You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days. |
inline | You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. |
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
The label image resource that was used to create a custom label image.
curl -i -X POST \
'https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/labels/rate_shopper_id/{rate_shopper_id}' \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"shipment": {
"ship_to": {
"name": "John Doe",
"company_name": "Example Corp",
"address_line1": "123 Main St",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78701",
"country_code": "US",
"phone": "512-555-1234"
},
"ship_from": {
"name": "Warehouse A",
"address_line1": "456 Warehouse Blvd",
"city_locality": "Dallas",
"state_province": "TX",
"postal_code": "75001",
"country_code": "US"
},
"packages": [
{
"weight": {
"value": 5,
"unit": "pound"
},
"dimensions": {
"length": 12,
"width": 8,
"height": 6,
"unit": "inch"
}
}
]
},
"label_format": "pdf",
"label_layout": "4x6"
}'Label created successfully using Rate Shopper. The response includes the selected carrier_id, service_code, and rate_shopper_id that was used.
The rate selection strategy that was used to create this label. This will match the rate_shopper_id provided in the request path.
A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created.
The possible statuses that a shipping label can be in.
| Status | Description |
|---|---|
processing | When labels are created in a batch, it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in processing status. |
completed | The label was successfully created |
error | The label could not be created due to an error, such as an invalid delivery address |
voided | The label has been voided |
The shipment that this label is for. ShipEngine can create a shipment for you automatically when you create a label, or you can create your own shipment and then use it to print a label
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
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.
The cost of shipping, delivery confirmation, and other carrier charges. This amount does not include insurance costs.
The insurance cost for this package. Add this to the shipment_cost field to get the total cost.
The total shipping cost for the specified comparison_rate_type.
A list of rate details that are associated with shipping cost. This is useful for displaying a breakdown of the rate to the user.
The tracking number for the package. Tracking number formats vary across carriers.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
If this label was created as part of a batch, then this is the unique ID of that batch.
The unique ID of the carrier account that was used to create this label
The label charge event.
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
An ISO 8601 string that represents a date and time.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.
The label image resource that was used to create a custom label image.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The current status of the package, such as in_transit or delivered
The type of delivery confirmation that is required for this shipment.
Reference to the various downloadable file formats for the generated label
The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any. Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it.
The paperless details which may contain elements like href, instructions and handoff_code.
The link to submit an insurance claim for the shipment. This field is null if the shipment is not insured or if the insurance provider does not support online claim submission.
The label's package(s).
Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.
Additional information some carriers may provide by which to identify a given label in their system.
The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
Indicates how a label was voided. refund_assist means the label was voided through the Refund Assist program, while manual means it was voided manually by the user.
{ "label_id": "se-123456", "status": "completed", "shipment_id": "se-789012", "ship_date": "2026-02-25T00:00:00Z", "created_at": "2026-02-25T10:30:00Z", "shipment_cost": { "currency": "usd", "amount": 7.33 }, "insurance_cost": { "currency": "usd", "amount": 0 }, "tracking_number": "1Z999AA10123456784", "is_return_label": false, "rma_number": null, "is_international": false, "batch_id": "se-987654", "carrier_id": "se-456789", "service_code": "usps_priority_mail", "package_code": "package", "voided": false, "label_format": "pdf", "label_layout": "4x6", "trackable": true, "carrier_code": "stamps_com", "tracking_status": "in_transit", "label_download": { "pdf": "https://api.shipengine.com/v1/downloads/10/label-123456.pdf", "png": "https://api.shipengine.com/v1/downloads/10/label-123456.png", "zpl": "https://api.shipengine.com/v1/downloads/10/label-123456.zpl", "href": "https://api.shipengine.com/v1/downloads/10/label-123456.pdf" }, "form_download": { "href": "https://api.shipengine.com/v1/downloads/10/form-123456.pdf" }, "insurance_claim": { "href": "https://api.shipengine.com/v1/claims/123456" }, "packages": [], "charge_event": "carrier_default", "rate_shopper_id": "cheapest" }
The possible validate address values
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
There are two different ways to download a label:
| Label Download Type | Description |
|---|---|
url | You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days. |
inline | You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. |
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/labels/shipment/se-28529731 \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"validate_address": "no_validation",
"label_layout": "4x6",
"label_format": "pdf",
"label_download_type": "url",
"display_scheme": "label"
}'The requested object creation was a success.
A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created.
The possible statuses that a shipping label can be in.
| Status | Description |
|---|---|
processing | When labels are created in a batch, it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in processing status. |
completed | The label was successfully created |
error | The label could not be created due to an error, such as an invalid delivery address |
voided | The label has been voided |
The shipment that this label is for. ShipEngine can create a shipment for you automatically when you create a label, or you can create your own shipment and then use it to print a label
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
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.
The cost of shipping, delivery confirmation, and other carrier charges. This amount does not include insurance costs.
The insurance cost for this package. Add this to the shipment_cost field to get the total cost.
The total shipping cost for the specified comparison_rate_type.
A list of rate details that are associated with shipping cost. This is useful for displaying a breakdown of the rate to the user.
The tracking number for the package. Tracking number formats vary across carriers.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
If this label was created as part of a batch, then this is the unique ID of that batch.
The unique ID of the carrier account that was used to create this label
The label charge event.
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
An ISO 8601 string that represents a date and time.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.
The label image resource that was used to create a custom label image.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The current status of the package, such as in_transit or delivered
The type of delivery confirmation that is required for this shipment.
Reference to the various downloadable file formats for the generated label
The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any. Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it.
The paperless details which may contain elements like href, instructions and handoff_code.
The link to submit an insurance claim for the shipment. This field is null if the shipment is not insured or if the insurance provider does not support online claim submission.
The label's package(s).
Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.
Additional information some carriers may provide by which to identify a given label in their system.
The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
Indicates how a label was voided. refund_assist means the label was voided through the Refund Assist program, while manual means it was voided manually by the user.
{ "label_id": "se-28529731", "status": "processing", "shipment_id": "se-28529731", "external_shipment_id": "string", "external_order_id": "string", "ship_date": "2018-09-23T00:00:00.000Z", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 0 }, "insurance_cost": { "currency": "string", "amount": 0 }, "requested_comparison_amount": { "currency": "string", "amount": 0 }, "rate_details": [ { … } ], "tracking_number": "782758401696", "is_return_label": true, "rma_number": "string", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-28529731", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "confirmation": "none", "label_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "pdf": "http://api.shipengine.com/v1/labels/se-28529731", "png": "http://api.shipengine.com/v1/labels/se-28529731", "zpl": "http://api.shipengine.com/v1/labels/se-28529731" }, "form_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "qr_code_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "paperless_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "instructions": null, "handoff_code": null }, "insurance_claim": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "packages": [ { … } ], "alternative_identifiers": [ { … } ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234", "ship_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string", "geolocation": [ … ] }, "void_type": "manual", "refund_details": { "refund_status": "request_scheduled", "request_date": "2018-09-23T15:00:00.000Z", "amount_paid": { … }, "amount_requested": { … }, "amount_approved": { … }, "amount_credited": { … } } }
There are two different ways to download a label:
| Label Download Type | Description |
|---|---|
url | You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days. |
inline | You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. |
curl -i -X GET \
'https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/labels/se-28529731?label_download_type=url' \
-H 'API-Key: YOUR_API_KEY_HERE'The request was a success.
A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created.
The possible statuses that a shipping label can be in.
| Status | Description |
|---|---|
processing | When labels are created in a batch, it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in processing status. |
completed | The label was successfully created |
error | The label could not be created due to an error, such as an invalid delivery address |
voided | The label has been voided |
The shipment that this label is for. ShipEngine can create a shipment for you automatically when you create a label, or you can create your own shipment and then use it to print a label
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
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.
The cost of shipping, delivery confirmation, and other carrier charges. This amount does not include insurance costs.
The insurance cost for this package. Add this to the shipment_cost field to get the total cost.
The total shipping cost for the specified comparison_rate_type.
A list of rate details that are associated with shipping cost. This is useful for displaying a breakdown of the rate to the user.
The tracking number for the package. Tracking number formats vary across carriers.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
If this label was created as part of a batch, then this is the unique ID of that batch.
The unique ID of the carrier account that was used to create this label
The label charge event.
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
An ISO 8601 string that represents a date and time.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.
The label image resource that was used to create a custom label image.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The current status of the package, such as in_transit or delivered
The type of delivery confirmation that is required for this shipment.
Reference to the various downloadable file formats for the generated label
The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any. Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it.
The paperless details which may contain elements like href, instructions and handoff_code.
The link to submit an insurance claim for the shipment. This field is null if the shipment is not insured or if the insurance provider does not support online claim submission.
The label's package(s).
Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.
Additional information some carriers may provide by which to identify a given label in their system.
The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
Indicates how a label was voided. refund_assist means the label was voided through the Refund Assist program, while manual means it was voided manually by the user.
{ "label_id": "se-28529731", "status": "processing", "shipment_id": "se-28529731", "external_shipment_id": "string", "external_order_id": "string", "ship_date": "2018-09-23T00:00:00.000Z", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 0 }, "insurance_cost": { "currency": "string", "amount": 0 }, "requested_comparison_amount": { "currency": "string", "amount": 0 }, "rate_details": [ { … } ], "tracking_number": "782758401696", "is_return_label": true, "rma_number": "string", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-28529731", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "confirmation": "none", "label_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "pdf": "http://api.shipengine.com/v1/labels/se-28529731", "png": "http://api.shipengine.com/v1/labels/se-28529731", "zpl": "http://api.shipengine.com/v1/labels/se-28529731" }, "form_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "qr_code_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "paperless_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "instructions": null, "handoff_code": null }, "insurance_claim": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "packages": [ { … } ], "alternative_identifiers": [ { … } ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234", "ship_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string", "geolocation": [ … ] }, "void_type": "manual", "refund_details": { "refund_status": "request_scheduled", "request_date": "2018-09-23T15:00:00.000Z", "amount_paid": { … }, "amount_requested": { … }, "amount_approved": { … }, "amount_credited": { … } } }
The label charge event.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
There are two different ways to download a label:
| Label Download Type | Description |
|---|---|
url | You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days. |
inline | You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. |
The display format that the label should be shown in.
The label image resource that was used to create a custom label image.
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/labels/se-28529731/return \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"label_format": "pdf",
"label_layout": "4x6",
"charge_event": "carrier_default",
"rma_number": "RMA-2024-001234"
}'The request was a success.
A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created.
The possible statuses that a shipping label can be in.
| Status | Description |
|---|---|
processing | When labels are created in a batch, it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in processing status. |
completed | The label was successfully created |
error | The label could not be created due to an error, such as an invalid delivery address |
voided | The label has been voided |
The shipment that this label is for. ShipEngine can create a shipment for you automatically when you create a label, or you can create your own shipment and then use it to print a label
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
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.
The cost of shipping, delivery confirmation, and other carrier charges. This amount does not include insurance costs.
The insurance cost for this package. Add this to the shipment_cost field to get the total cost.
The total shipping cost for the specified comparison_rate_type.
A list of rate details that are associated with shipping cost. This is useful for displaying a breakdown of the rate to the user.
The tracking number for the package. Tracking number formats vary across carriers.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
If this label was created as part of a batch, then this is the unique ID of that batch.
The unique ID of the carrier account that was used to create this label
The label charge event.
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
An ISO 8601 string that represents a date and time.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.
The label image resource that was used to create a custom label image.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The current status of the package, such as in_transit or delivered
The type of delivery confirmation that is required for this shipment.
Reference to the various downloadable file formats for the generated label
The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any. Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it.
The paperless details which may contain elements like href, instructions and handoff_code.
The link to submit an insurance claim for the shipment. This field is null if the shipment is not insured or if the insurance provider does not support online claim submission.
The label's package(s).
Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.
Additional information some carriers may provide by which to identify a given label in their system.
The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
Indicates how a label was voided. refund_assist means the label was voided through the Refund Assist program, while manual means it was voided manually by the user.
{ "label_id": "se-28529731", "status": "processing", "shipment_id": "se-28529731", "external_shipment_id": "string", "external_order_id": "string", "ship_date": "2018-09-23T00:00:00.000Z", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 0 }, "insurance_cost": { "currency": "string", "amount": 0 }, "requested_comparison_amount": { "currency": "string", "amount": 0 }, "rate_details": [ { … } ], "tracking_number": "782758401696", "is_return_label": true, "rma_number": "string", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-28529731", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "confirmation": "none", "label_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "pdf": "http://api.shipengine.com/v1/labels/se-28529731", "png": "http://api.shipengine.com/v1/labels/se-28529731", "zpl": "http://api.shipengine.com/v1/labels/se-28529731" }, "form_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "qr_code_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "paperless_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "instructions": null, "handoff_code": null }, "insurance_claim": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "packages": [ { … } ], "alternative_identifiers": [ { … } ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234", "ship_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string", "geolocation": [ … ] }, "void_type": "manual", "refund_details": { "refund_status": "request_scheduled", "request_date": "2018-09-23T15:00:00.000Z", "amount_paid": { … }, "amount_requested": { … }, "amount_approved": { … }, "amount_credited": { … } } }
curl -i -X GET \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/labels/se-28529731/track \
-H 'API-Key: YOUR_API_KEY_HERE'The request was a success.
A tracking number for a package. The format depends on the carrier.
Carrier Tracking Url, if available
The tracking status codes
| Value | Description |
|---|---|
UN | Unknown |
AC | Accepted |
IT | In Transit |
DE | Delivered |
EX | Exception |
AT | Delivery Attempt |
NY | Not Yet In System |
SP | Delivered To Collection Location |
The tracking status detail codes
| Value | Description |
|---|---|
CARRIER_STATUS_NOT_MAPPED | Status not mapped. Please check the carrier's website for updates. |
SHIPMENT_CREATED | Your tracking number is ready. Your parcel is waiting to be registered in the carrier system and scheduled for pickup. |
AWAITING_PICKUP_DROP_OFF | Your parcel is waiting to be handed over to the carrier. |
DROPPED_OFF | Your parcel has been dropped off and is ready for carrier processing. |
ELEC_ADVICE_RECD_BY_CARRIER | Your shipment is now in the carrier's system. |
PICKED_UP | Your parcel has been picked up by the carrier. |
CUSTOMS_CLEARED | Your parcel has cleared customs and is continuing its journey. |
CUSTOMS_PROCESSING | Your parcel is currently being processed by customs. |
DELIVERY_ARRANGED_WITH_RECIPIENT | Your parcel's delivery has been arranged with the carrier. |
HUB_SCAN_OUT | Your parcel has left the carrier's hub. |
HUB_SCAN_IN | Your parcel has arrived at the carrier's hub for processing. |
IN_TRANSIT | Your shipment is on its way between the carrier hubs. |
INFORMATION | The carrier has shared additional information about your parcel. |
PARCEL_OVER_LABELLED | Your parcel's label has been updated by the carrier, which may affect tracking visibility. |
PARCEL_UPDATE_NOTIFICATION | The carrier has sent you an update on your parcel status via SMS or email. |
RECEIVED_BY_CARRIER | Your parcel has been received by the carrier and is beginning its journey. |
RECEIVED_LOCAL_DELIVERY_DEPOT | Your parcel has arrived at the local delivery depot and is almost ready for delivery. |
SUB_CONTRACTOR_EVENT | The carrier has shared additional information about your parcel's handling by a delivery partner. |
SUB_CONTRACTOR_RECEIVED | Your parcel has been received by the carrier's local delivery partner. |
PARCEL_REDIRECTED | Your parcel has been redirected to a new delivery address per your request. |
DELIVERY_SCHEDULED | Your parcel's delivery has been scheduled and will soon be out for delivery. |
HUB_PROCESSING | Your parcel is being processed at a carrier hub. |
DELIVERY_RESCHEDULED | Your parcel's delivery has been rescheduled due to operational issues. |
ATTEMPTED_DELIVERY | The carrier attempted to deliver your parcel but was unable to complete delivery. |
ATTEMPTED_DELIVERY_FINAL | The carrier made a final attempt to deliver your parcel but was unable to complete delivery. Please check the carrier's instructions for next steps. |
COD_AMOUNT_PAID | Cash on delivery payment received. |
CUSTOMER_CARDED | Delivery attempt failed. Please follow delivery instructions left by the carrier. |
OUT_FOR_DELIVERY | Your parcel is on its way and will be delivered today. |
AWAITING_COLLECTION_FROM_PICKUP_POINT | Your parcel is ready for collection at the selected pickup point. |
COLLECT_AT_LOCAL_PO | Your parcel is ready for collection at your local post office. |
CUSTOMER_TO_COLLECT_FROM_CARRIER | Your parcel is available for collection from the carrier's local delivery unit. |
DELIVERED_TO_RECEPTION | Your parcel has been delivered to your building's reception or designated mail area. |
DELIVERED | Your parcel has been successfully delivered. |
DELIVERED_DAMAGED | Your parcel was delivered but arrived with visible damage. |
DELIVERED_IN_PART | Part of your shipment has been delivered. Check for updates on the rest. |
DELIVERED_SPECIFIED_SAFE_PLACE | Your parcel has been delivered to your specified safe place. |
DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATION | Your parcel was delivered to an alternative location due to the delivery company being unable to deliver it to the specified address. Check carrier instructions for pickup details. |
DELIVERED_TO_NEIGHBOUR | Your parcel was delivered to your neighbor. |
DELIVERED_TO_PO_BOX | Your parcel has been delivered to your specified PO Box. |
PARCEL_COLLECTED_FROM_PICKUP_POINT | Your package has been picked up from the pick up point. |
POST_TRANSIT_STATUS | The carrier has added more information about your delivery. |
PROOF_OF_DELIVERY | The carrier has confirmed delivery with proof, such as a signature or photo. |
PICKUP_FAILED | Parcel pickup failed. The delivery company will try again soon. |
NOT_YET_RECEIVED_BY_CARRIER | The carrier has not yet received your parcel, which may cause a delay. |
PARCEL_DAMAGED | Your parcel was damaged in transit but will still be delivered. |
ADDRESS_QUERY | There is an issue with the delivery address, which may delay your parcel. |
CARRIER_DELAYS | Your parcel is delayed due to issues within the carrier network. |
DELAYED_NOT_CARRIER | Your parcel is delayed due to circumstances beyond the carrier's control. |
HELD_BY_CARRIER | Your parcel is being held due to an operational issue. Contact with the carrier for more information. |
HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSING | Your parcel is being held by the carrier for customs documentation checks. This may occur when the carrier must confirm documentation before the parcel can continue its journey. |
HELD_BY_CUSTOMS | Your parcel is being held at customs, which may delay delivery. |
INCORRECT_DECLARATION | Your parcel has been incorrectly declared but is still moving forward for delivery. |
MISROUTED | Your parcel was sent to the wrong place due to a routing error but is being redirected. |
PARCEL_REPACKED | Your parcel was repackaged by the carrier due to damage and will still be delivered. |
RECD_BY_CARRIER_NO_ELEC_ADVICE | Your parcel has been received by the carrier but may experience delays due to missing pre-advice. |
COD_AMOUNT_NOT_PAID | Delivery failed due to unpaid cash on delivery. Please follow carrier instructions. |
CUSTOMER_IDENTIFICATION_FAILED | Delivery couldn't be completed as identification requirements were not met. |
NO_ACCESS_TO_RECIPIENTS_ADDRESS | The carrier couldn't access the delivery location due to restricted entry. |
CANCELLED | Your parcel has been cancelled. |
CUSTOMER_MOVED | Delivery failed as the recipient is no longer at the specified address. Your parcel is being returned. |
HAZARDOUS_PROHIBITED | Your parcel contains restricted items and will not be delivered. |
NOT_COLLECTED_FROM_PICKUP_POINT | Your parcel was not collected from the pickup point within the designated time and will be returned. |
NOT_DELIVERED | All delivery attempts failed. Your parcel is being returned to the sender. |
NOT_DELIVERED_ADDRESSEE_DECEASED | The parcel could not be delivered as the addressee is reported deceased. |
PARCEL_DISPOSED | Your parcel has been disposed of due to its contents or condition and will not be delivered. |
PARCEL_LOST | The carrier has reported that your parcel is lost and will not be delivered. |
PARCEL_OUTSIDE_OF_SERVICE_CAPABILITY | The parcel cannot be delivered as it exceeds the carrier's service limits. |
REFUSED_BY_CUSTOMER | You have refused the parcel, and it will be returned to the sender. |
RETURN_TO_SENDER | Your parcel is being returned to the sender due to delivery issues. |
UNSPECIFIED_EXCEPTION | The carrier has reported an issue with your parcel, but details are unavailable. |
TRACKING_EXPIRED | Tracking for this parcel has expired. If you are still expecting this delivery, please contact the carrier for assistance. |
DUTY_NOT_PAID | The import taxes or duties for this package havent been paid and it may be subject to disposal by customs authorities if payment is not made. |
PARCEL_REDIRECTED_BY_CARRIER | The carrier has redirected your parcel due to an operational issue. The package is likely being rerouted to a nearby pickup point. You may contact the carrier for more details about the new delivery location. |
DELIVERED_TO_PICKUP_POINT | Your package has been delivered to the pickup point. You will be notified when its ready for collection. |
UNDELIVERABLE_RETURNED_TO_SENDER | The shipment has been returned to the sender. Please contact the sender for further information. |
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The unique ID of the carrier account that was used to create this label
Status detail description
carrier status description
An ISO 8601 string that represents a date and time.
An ISO 8601 string that represents a date and time.
An ISO 8601 string that represents a date and time.
The events that have occured during the lifetime of this tracking number.
An ISO 8601 string that represents a date and time.
An ISO 8601 string that represents a date and time.
Event description
A two-letter ISO 3166-1 country code
The tracking status codes
| Value | Description |
|---|---|
UN | Unknown |
AC | Accepted |
IT | In Transit |
DE | Delivered |
EX | Exception |
AT | Delivery Attempt |
NY | Not Yet In System |
SP | Delivered To Collection Location |
The tracking status detail codes
| Value | Description |
|---|---|
CARRIER_STATUS_NOT_MAPPED | Status not mapped. Please check the carrier's website for updates. |
SHIPMENT_CREATED | Your tracking number is ready. Your parcel is waiting to be registered in the carrier system and scheduled for pickup. |
AWAITING_PICKUP_DROP_OFF | Your parcel is waiting to be handed over to the carrier. |
DROPPED_OFF | Your parcel has been dropped off and is ready for carrier processing. |
ELEC_ADVICE_RECD_BY_CARRIER | Your shipment is now in the carrier's system. |
PICKED_UP | Your parcel has been picked up by the carrier. |
CUSTOMS_CLEARED | Your parcel has cleared customs and is continuing its journey. |
CUSTOMS_PROCESSING | Your parcel is currently being processed by customs. |
DELIVERY_ARRANGED_WITH_RECIPIENT | Your parcel's delivery has been arranged with the carrier. |
HUB_SCAN_OUT | Your parcel has left the carrier's hub. |
HUB_SCAN_IN | Your parcel has arrived at the carrier's hub for processing. |
IN_TRANSIT | Your shipment is on its way between the carrier hubs. |
INFORMATION | The carrier has shared additional information about your parcel. |
PARCEL_OVER_LABELLED | Your parcel's label has been updated by the carrier, which may affect tracking visibility. |
PARCEL_UPDATE_NOTIFICATION | The carrier has sent you an update on your parcel status via SMS or email. |
RECEIVED_BY_CARRIER | Your parcel has been received by the carrier and is beginning its journey. |
RECEIVED_LOCAL_DELIVERY_DEPOT | Your parcel has arrived at the local delivery depot and is almost ready for delivery. |
SUB_CONTRACTOR_EVENT | The carrier has shared additional information about your parcel's handling by a delivery partner. |
SUB_CONTRACTOR_RECEIVED | Your parcel has been received by the carrier's local delivery partner. |
PARCEL_REDIRECTED | Your parcel has been redirected to a new delivery address per your request. |
DELIVERY_SCHEDULED | Your parcel's delivery has been scheduled and will soon be out for delivery. |
HUB_PROCESSING | Your parcel is being processed at a carrier hub. |
DELIVERY_RESCHEDULED | Your parcel's delivery has been rescheduled due to operational issues. |
ATTEMPTED_DELIVERY | The carrier attempted to deliver your parcel but was unable to complete delivery. |
ATTEMPTED_DELIVERY_FINAL | The carrier made a final attempt to deliver your parcel but was unable to complete delivery. Please check the carrier's instructions for next steps. |
COD_AMOUNT_PAID | Cash on delivery payment received. |
CUSTOMER_CARDED | Delivery attempt failed. Please follow delivery instructions left by the carrier. |
OUT_FOR_DELIVERY | Your parcel is on its way and will be delivered today. |
AWAITING_COLLECTION_FROM_PICKUP_POINT | Your parcel is ready for collection at the selected pickup point. |
COLLECT_AT_LOCAL_PO | Your parcel is ready for collection at your local post office. |
CUSTOMER_TO_COLLECT_FROM_CARRIER | Your parcel is available for collection from the carrier's local delivery unit. |
DELIVERED_TO_RECEPTION | Your parcel has been delivered to your building's reception or designated mail area. |
DELIVERED | Your parcel has been successfully delivered. |
DELIVERED_DAMAGED | Your parcel was delivered but arrived with visible damage. |
DELIVERED_IN_PART | Part of your shipment has been delivered. Check for updates on the rest. |
DELIVERED_SPECIFIED_SAFE_PLACE | Your parcel has been delivered to your specified safe place. |
DELIVERED_TO_ALTERNATIVE_DELIVERY_LOCATION | Your parcel was delivered to an alternative location due to the delivery company being unable to deliver it to the specified address. Check carrier instructions for pickup details. |
DELIVERED_TO_NEIGHBOUR | Your parcel was delivered to your neighbor. |
DELIVERED_TO_PO_BOX | Your parcel has been delivered to your specified PO Box. |
PARCEL_COLLECTED_FROM_PICKUP_POINT | Your package has been picked up from the pick up point. |
POST_TRANSIT_STATUS | The carrier has added more information about your delivery. |
PROOF_OF_DELIVERY | The carrier has confirmed delivery with proof, such as a signature or photo. |
PICKUP_FAILED | Parcel pickup failed. The delivery company will try again soon. |
NOT_YET_RECEIVED_BY_CARRIER | The carrier has not yet received your parcel, which may cause a delay. |
PARCEL_DAMAGED | Your parcel was damaged in transit but will still be delivered. |
ADDRESS_QUERY | There is an issue with the delivery address, which may delay your parcel. |
CARRIER_DELAYS | Your parcel is delayed due to issues within the carrier network. |
DELAYED_NOT_CARRIER | Your parcel is delayed due to circumstances beyond the carrier's control. |
HELD_BY_CARRIER | Your parcel is being held due to an operational issue. Contact with the carrier for more information. |
HELD_BY_CARRIER_FOR_CLEARANCE_PRE_PROCESSING | Your parcel is being held by the carrier for customs documentation checks. This may occur when the carrier must confirm documentation before the parcel can continue its journey. |
HELD_BY_CUSTOMS | Your parcel is being held at customs, which may delay delivery. |
INCORRECT_DECLARATION | Your parcel has been incorrectly declared but is still moving forward for delivery. |
MISROUTED | Your parcel was sent to the wrong place due to a routing error but is being redirected. |
PARCEL_REPACKED | Your parcel was repackaged by the carrier due to damage and will still be delivered. |
RECD_BY_CARRIER_NO_ELEC_ADVICE | Your parcel has been received by the carrier but may experience delays due to missing pre-advice. |
COD_AMOUNT_NOT_PAID | Delivery failed due to unpaid cash on delivery. Please follow carrier instructions. |
CUSTOMER_IDENTIFICATION_FAILED | Delivery couldn't be completed as identification requirements were not met. |
NO_ACCESS_TO_RECIPIENTS_ADDRESS | The carrier couldn't access the delivery location due to restricted entry. |
CANCELLED | Your parcel has been cancelled. |
CUSTOMER_MOVED | Delivery failed as the recipient is no longer at the specified address. Your parcel is being returned. |
HAZARDOUS_PROHIBITED | Your parcel contains restricted items and will not be delivered. |
NOT_COLLECTED_FROM_PICKUP_POINT | Your parcel was not collected from the pickup point within the designated time and will be returned. |
NOT_DELIVERED | All delivery attempts failed. Your parcel is being returned to the sender. |
NOT_DELIVERED_ADDRESSEE_DECEASED | The parcel could not be delivered as the addressee is reported deceased. |
PARCEL_DISPOSED | Your parcel has been disposed of due to its contents or condition and will not be delivered. |
PARCEL_LOST | The carrier has reported that your parcel is lost and will not be delivered. |
PARCEL_OUTSIDE_OF_SERVICE_CAPABILITY | The parcel cannot be delivered as it exceeds the carrier's service limits. |
REFUSED_BY_CUSTOMER | You have refused the parcel, and it will be returned to the sender. |
RETURN_TO_SENDER | Your parcel is being returned to the sender due to delivery issues. |
UNSPECIFIED_EXCEPTION | The carrier has reported an issue with your parcel, but details are unavailable. |
TRACKING_EXPIRED | Tracking for this parcel has expired. If you are still expecting this delivery, please contact the carrier for assistance. |
DUTY_NOT_PAID | The import taxes or duties for this package havent been paid and it may be subject to disposal by customs authorities if payment is not made. |
PARCEL_REDIRECTED_BY_CARRIER | The carrier has redirected your parcel due to an operational issue. The package is likely being rerouted to a nearby pickup point. You may contact the carrier for more details about the new delivery location. |
DELIVERED_TO_PICKUP_POINT | Your package has been delivered to the pickup point. You will be notified when its ready for collection. |
UNDELIVERABLE_RETURNED_TO_SENDER | The shipment has been returned to the sender. Please contact the sender for further information. |
Event Status Description
Event Status Detail Description
carrier status description
A URL to an image captured at the time of delivery, serving as evidence that the shipment was successfully delivered to the recipient. It can be used to capture things like recipient's signature, location of delivery, condition of the package upon delivery, etc.
{ "tracking_number": "1Z932R800392060079", "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234", "status_code": "DE", "status_detail_code": "DELIVERED", "carrier_code": "dhl_express", "carrier_id": 0, "status_description": "Delivered", "status_detail_description": "Your parcel has been successfully delivered.", "carrier_status_code": "1", "carrier_detail_code": "OT", "carrier_status_description": "Your item was delivered in or at the mailbox at 9:10 am on March", "ship_date": "2018-09-23T15:00:00.000Z", "estimated_delivery_date": "2018-09-23T15:00:00.000Z", "actual_delivery_date": "2018-09-23T15:00:00.000Z", "exception_description": "string", "events": [ { … } ] }
curl -i -X PUT \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/labels/se-28529731/void \
-H 'API-Key: YOUR_API_KEY_HERE'The request was a success.
Indicates whether the attempt to void the label was successful
Indicates a normalized reason for the conditions if the void attempt was not approved. Will not populate if approved is true. “unknown” codes may be specified later.
{ "approved": false, "message": "Unable to delete FedEx shipment. Unable to retrieve record from database.", "reason_code": "label_not_found_within_void_period" }
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/labels/se-28529731/cancel_refund \
-H 'API-Key: YOUR_API_KEY_HERE'The refund cancellation was successful. Returns the updated label object.
A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created.
The possible statuses that a shipping label can be in.
| Status | Description |
|---|---|
processing | When labels are created in a batch, it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in processing status. |
completed | The label was successfully created |
error | The label could not be created due to an error, such as an invalid delivery address |
voided | The label has been voided |
The shipment that this label is for. ShipEngine can create a shipment for you automatically when you create a label, or you can create your own shipment and then use it to print a label
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
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.
The cost of shipping, delivery confirmation, and other carrier charges. This amount does not include insurance costs.
The insurance cost for this package. Add this to the shipment_cost field to get the total cost.
The total shipping cost for the specified comparison_rate_type.
A list of rate details that are associated with shipping cost. This is useful for displaying a breakdown of the rate to the user.
The tracking number for the package. Tracking number formats vary across carriers.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
If this label was created as part of a batch, then this is the unique ID of that batch.
The unique ID of the carrier account that was used to create this label
The label charge event.
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
An ISO 8601 string that represents a date and time.
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
pdf | All carriers |
png | fedex stamps_com ups usps |
zpl | access_worldwide apc asendia dhl_global_mail dhl_express dhl_express_australia dhl_express_canada dhl_express_worldwide dhl_express_uk dpd endicia fedex fedex_uk firstmile imex newgistics ontrac rr_donnelley stamps_com ups usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.
The label image resource that was used to create a custom label image.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The current status of the package, such as in_transit or delivered
The type of delivery confirmation that is required for this shipment.
Reference to the various downloadable file formats for the generated label
The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any. Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it.
The paperless details which may contain elements like href, instructions and handoff_code.
The link to submit an insurance claim for the shipment. This field is null if the shipment is not insured or if the insurance provider does not support online claim submission.
The label's package(s).
Note: Some carriers only allow one package per label. If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.
Additional information some carriers may provide by which to identify a given label in their system.
The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
Indicates how a label was voided. refund_assist means the label was voided through the Refund Assist program, while manual means it was voided manually by the user.
{ "label_id": "se-28529731", "status": "processing", "shipment_id": "se-28529731", "external_shipment_id": "string", "external_order_id": "string", "ship_date": "2018-09-23T00:00:00.000Z", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 0 }, "insurance_cost": { "currency": "string", "amount": 0 }, "requested_comparison_amount": { "currency": "string", "amount": 0 }, "rate_details": [ { … } ], "tracking_number": "782758401696", "is_return_label": true, "rma_number": "string", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-28529731", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": true, "voided_at": "2018-09-23T15:00:00.000Z", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "confirmation": "none", "label_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "pdf": "http://api.shipengine.com/v1/labels/se-28529731", "png": "http://api.shipengine.com/v1/labels/se-28529731", "zpl": "http://api.shipengine.com/v1/labels/se-28529731" }, "form_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "qr_code_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "paperless_download": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "instructions": null, "handoff_code": null }, "insurance_claim": { "href": "http://api.shipengine.com/v1/labels/se-28529731", "type": "string" }, "packages": [ { … } ], "alternative_identifiers": [ { … } ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234", "ship_to": { "name": "John Doe", "phone": "+1 204-253-9411 ext. 123", "email": "example@example.com", "company_name": "The Home Depot", "address_line1": "1999 Bishop Grandin Blvd.", "address_line2": "Unit 408", "address_line3": "Building #7", "city_locality": "Winnipeg", "state_province": "Manitoba", "postal_code": "78756-3717", "country_code": "CA", "address_residential_indicator": "no", "instructions": "string", "geolocation": [ … ] }, "void_type": "manual", "refund_details": { "refund_status": "request_scheduled", "request_date": "2018-09-23T15:00:00.000Z", "amount_paid": { … }, "amount_requested": { … }, "amount_approved": { … }, "amount_credited": { … } } }
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.