labels
Get label by external shipment ID
<aside class="access" aria-label="Endpoint access"> <table class="access__table"> <thead> <tr> <th class="access__table-header">Products</th> <th class="access__table-header">Plans</th> </tr> </thead> <tbody> <tr> <td class="access__table-cell access__product"> <img class="access__logo" src="/static/logos/shipstation-api-logo.svg" alt="ShipStation API Logo" loading="lazy" decoding="async"/> <div class="access__sub">Formerly ShipEngine</div> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-free.md" class="access__plan">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Advanced</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Enterprise</a> </td> </tr> <tr> <td class="access__table-cell"> <img class="access__logo" src="/static/logos/shipstation-logo.svg" alt="ShipStation Logo" loading="lazy" decoding="async"/> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Starter</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Standard</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Premium</a> </td> </tr> </tbody> </table> <footer class="access__footer"> <a class="access__help" href="/apis/@shipstation-v2/docs/getting-started/products-and-plans.md"> Learn about products and plans <img src="/static/icons/external-link.svg" alt="External Link Icon" style="width: 16px;" loading="lazy" decoding="async"/> </a> </footer> </aside>Find a label by using the external shipment id that was used during label creation.
Warning: This endpoint returns only the first label found with the specified external_shipment_id. If multiple labels share the same external_shipment_id, only the earliest created label will be returned. To retrieve all labels with a specific external_shipment_id, use the list labels endpoint with the external_shipment_id query parameter.
get/v2/labels/external_shipment_id/{external_shipment_id}
Query parameters
label_download_type'url' | 'inline'
There are two different ways to [download a label]:
| Label Download Type | Description |
|---|---|
| url | You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days.<br><br>This is the default if label_download_type is unspecified. |
| inline | You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. |
Response
The requested label was successfully retrieved.
Example response
{
"label_id": "se-28529731",
"shipment_id": "se-28529731",
"external_shipment_id": "externalId-1234556",
"external_order_id": "externalOrderId-1232434",
"shipment": {
"shipment_id": "se-28529731",
"carrier_id": "se-28529731",
"service_code": "usps_first_class_mail",
"requested_shipment_service": "usps_priority_mail",
"external_order_id": "1232434",
"hold_until_date": "2025-01-15T00:00:00.000Z",
"ship_by_date": "2025-01-15T00:00:00.000Z",
"deliver_by_date": "2025-01-20T00:00:00.000Z",
"retail_rate": {
"amount": 12
},
"store_id": "se-28529731",
"items": [
{
"name": "box",
"sales_order_id": "12345",
"sales_order_item_id": "1234556",
"quantity": 1,
"sku": "sku-1234",
"bundle_sku": "bundle-123",
"external_order_id": "123445",
"external_order_item_id": "12",
"asin": "B00005N5PF",
"item_id": "1402291169813",
"allocation_status": "allocated",
"image_url": "https://example.com/image.jpg",
"weight": {
"value": 23
},
"unit_price": 88,
"tax_amount": 5.5,
"shipping_amount": 10,
"inventory_location": "warehouse-a",
"options": [
{
"name": "Color",
"value": "Red"
}
],
"product_id": "10408926",
"fullfilment_sku": "fulfill-123",
"upc": "123456789012"
}
],
"notes_from_buyer": "Please handle with care",
"notes_to_buyer": "Thank you for your order!",
"notes_for_gift": "Happy Birthday!",
"internal_notes": "Check packaging before shipping",
"is_gift": true,
"assigned_user": "user@example.com",
"amount_paid": {
"amount": 12
},
"shipping_paid": {
"amount": 12
},
"tax_paid": {
"amount": 12
},
"zone": 1,
"display_scheme": "label",
"tax_identifiers": [
{
"issuing_authority": "US",
"value": "value"
}
],
"external_shipment_id": "1234556",
"shipment_number": "10001",
"ship_date": "2018-09-23T00:00:00Z",
"created_at": "2018-09-23T15:00:00.000Z",
"modified_at": "2018-09-23T15: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",
"instructions": "any instruction",
"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",
"instructions": "any instructions",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"warehouse_id": "se-28529731",
"return_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"instructions": "any instructions",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"is_return": true,
"customs": {
"terms_of_trade_code": "ddp",
"contents": "gift",
"non_delivery": "return_to_sender"
},
"advanced_options": {
"bill_to_account": "123456789",
"bill_to_country_code": "CA",
"bill_to_postal_code": "28005",
"contains_alcohol": true,
"delivered_duty_paid": true,
"dry_ice": true,
"dry_ice_weight": {
"value": 23
},
"non_machinable": true,
"saturday_delivery": true,
"fedex_freight": {
"shipper_load_and_count": "shipper_load_and_count",
"booking_confirmation": "today"
},
"use_ups_ground_freight_pricing": true,
"freight_class": "77.5",
"custom_field1": "custom field 1",
"custom_field2": "custom field 2",
"custom_field3": "custom field 3",
"additional_handling": true,
"shipper_release": true,
"collect_on_delivery": {
"payment_amount": {
"amount": 12
}
},
"third_party_consignee": true,
"dangerous_goods": true,
"dangerous_goods_contact": {
"name": "Michael Robinson",
"phone": "123456578789"
},
"movement_indicator": "b2b",
"windsor_framework_details": {
"movement_indicator": "b2b",
"not_at_risk": true
},
"ancillary_endorsements_option": "forward",
"return_pickup_attempts": 3,
"netstamps_options": {
"row": 1,
"column": 1
}
},
"tags": [
{
"name": "Fragile"
}
],
"packages": [
{
"shipment_package_id": "se-28529731",
"package_id": "se-28529731",
"package_code": "small_flat_rate_box",
"package_name": "Flat Rate Envelope",
"weight": {
"value": 23
},
"dimensions": {
"length": 2,
"width": 2,
"height": 1
},
"insured_value": {
"amount": 12
},
"label_messages": {
"reference1": "Reference",
"reference2": "Reference 2",
"reference3": "Reference 3"
},
"external_package_id": "se-1234545",
"content_description": "Hand knitted wool socks",
"products": [
{
"description": "a minimum description",
"quantity": 1,
"value": {
"amount": 12
},
"weight": {
"value": 23
},
"harmonized_tariff_code": "3926.10",
"country_of_origin": "CA",
"unit_of_measure": "pound",
"sku": "sku-1223344",
"sku_description": "this is a description",
"mid_code": "GBCOM15BRI",
"product_url": "https://myproduct.com",
"vat_rate": 0.2,
"dangerous_goods": [
{
"id_number": "1234r1",
"shipping_name": "things with dangerous goods",
"technical_name": "chloric acid",
"product_class": "1987",
"product_class_subsidiary": "1987",
"packaging_group": "ii",
"dangerous_amount": {
"amount": 12,
"unit": "GBP"
},
"quantity": 1,
"packaging_instruction": "Packaging materials and containers that are in contact with food products must comply with the provisions established by Regulation ",
"packaging_instruction_section": "section_1",
"packaging_type": "X",
"transport_mean": "ground",
"transport_category": "6.1",
"regulation_authority": "AEAT",
"regulation_level": "excepted_quantity",
"tunnel_code": "all",
"additional_description": "any description"
}
],
"manufacturer_product_id": "012345678905",
"manufacturer_ns_product_id": "MY-SKU-12345",
"cpsc_certificates": [
{
"certifier_id": "CERT-12345",
"certificate_version_id": "v1.0"
}
]
}
]
}
],
"total_weight": {
"value": 3
},
"comparison_rate_type": "retail"
},
"ship_date": "2018-09-23T00:00:00Z",
"created_at": "2018-09-23T15:00:00.000Z",
"shipment_cost": {
"amount": 12
},
"insurance_cost": {
"amount": 12
},
"requested_comparison_amount": {
"amount": 12
},
"tracking_number": "782758401696",
"is_return_label": true,
"rma_number": "asd12323",
"is_international": true,
"batch_id": "se-28529731",
"carrier_id": "se-28529731",
"outbound_label_id": "se-28529731",
"service_code": "usps_first_class_mail",
"test_label": true,
"package_code": "small_flat_rate_box",
"voided": true,
"voided_at": "2018-09-23T15:00:00.000Z",
"refund_details": {
"refund_status": "request_scheduled",
"request_date": "2018-09-23T15:00:00.000Z",
"amount_paid": {
"amount": 12
},
"amount_requested": {
"amount": 12
},
"amount_approved": {
"amount": 12
},
"amount_credited": {
"amount": 12
}
},
"trackable": true,
"label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
"carrier_code": "dhl_express",
"label_download": {
"href": "https://example.com/resource",
"pdf": "https://example.com/resource",
"png": "https://example.com/resource",
"zpl": "https://example.com/resource"
},
"form_download": {
"href": "https://example.com/resource",
"type": "child"
},
"qr_code_download": {
"href": "https://example.com/resource",
"type": "child"
},
"paperless_download": {
"href": "https://example.com/resource",
"instructions": "any instructions",
"handoff_code": "122334"
},
"insurance_claim": {
"href": "https://example.com/resource",
"type": "child"
},
"packages": [
{
"package_id": 1234545,
"package_code": "small_flat_rate_box",
"weight": {
"value": 23
},
"dimensions": {
"length": 2,
"width": 2,
"height": 1
},
"insured_value": {
"amount": 12
},
"tracking_number": "1Z932R800392060079",
"label_download": {
"href": "https://example.com/resource",
"pdf": "https://example.com/resource",
"png": "https://example.com/resource",
"zpl": "https://example.com/resource"
},
"form_download": {
"href": "https://example.com/resource",
"type": "child"
},
"qr_code_download": {
"href": "https://example.com/resource",
"type": "child"
},
"paperless_download": {
"href": "https://example.com/resource",
"instructions": "any instructions",
"handoff_code": "122334"
},
"label_messages": {
"reference1": "Reference",
"reference2": "Reference 2",
"reference3": "Reference 3"
},
"external_package_id": "se-1234567",
"content_description": "Hand knitted wool socks",
"sequence": 34,
"has_label_documents": true,
"has_form_documents": true,
"has_qr_code_documents": true,
"has_paperless_label_documents": true,
"alternative_identifiers": [
{
"type": "last_mile_tracking_number",
"value": "12345678912345678912"
}
]
}
],
"alternative_identifiers": [
{
"type": "last_mile_tracking_number",
"value": "12345678912345678912"
}
],
"rate_details": [
{
"rate_detail_type": "shipping",
"carrier_description": "Shipping",
"carrier_billing_code": "BaseServiceCharge",
"amount": {
"amount": 12
},
"billing_source": "carrier"
}
],
"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",
"instructions": "any instruction",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
}
}