Process labels in bulk and receive a large number of labels and customs forms in bulk responses. Batching is ideal for workflows that need to process hundreds or thousands of labels quickly.
ShipStation API v2 (2.0.0)
Download OpenAPI description
Overview
License
Languages
Servers
Mock server
https://docs.shipstation.com/_mock/apis/openapi/
Production
https://api.shipstation.com/
Bodyapplication/jsonrequired
The shipments to create NetStamps labels for. All shipments must use the same carrier_id.
Each shipment must include advanced_options.netstamps_options with row and column to control stamp placement. Row/column combinations must be unique across shipments.
The carrier account that is billed for the shipping charges
Example: "se-28529731"
A [carrier service], such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
Example: "usps_first_class_mail"
The requested shipment service
Example: "usps_priority_mail"
ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
Example: "se-28529731"
Date to hold the shipment until
Example: "2025-01-15T00:00:00.000Z"
Date by which the shipment should be shipped
Example: "2025-01-15T00:00:00.000Z"
The store ID associated with the shipment
Example: "se-28529731"
Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
Default []
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.
Example: "1234556"
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.
Example: "10001"
shipments[].ship_datestring or null(date-time)(date)^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?...
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 ShipStation .
Example: "2018-09-23T00:00:00Z"
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.
Example: "John Doe"
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Example: "+1 204-253-9411 ext. 123"
Email for the address owner.
Example: "example@example.com"
If this is a business address, then the company name should be specified here.
Example: "The Home Depot"
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
Example: "1999 Bishop Grandin Blvd."
The second line of the street address. For some addresses, this line may not be needed.
Example: "Unit 408"
The third line of the street address. For some addresses, this line may not be needed.
Example: "Building #7"
The name of the city or locality
Example: "Winnipeg"
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
Example: "Manitoba"
postal code
Example: "78756-3717"
A two-letter ISO 3166-1 country code
Example: "CA"
Indicates whether this is a residential address.
Default "unknown"
Enum"unknown""yes""no"
Example: "yes"
Additional text about how to handle the shipment at this address.
Example: "any instruction"
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.
Example: "John Doe"
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Example: "+1 204-253-9411 ext. 123"
Email for the address owner.
Example: "example@example.com"
If this is a business address, then the company name should be specified here.
Example: "The Home Depot"
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
Example: "1999 Bishop Grandin Blvd."
The second line of the street address. For some addresses, this line may not be needed.
Example: "Unit 408"
The third line of the street address. For some addresses, this line may not be needed.
Example: "Building #7"
The name of the city or locality
Example: "Winnipeg"
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
Example: "Manitoba"
postal code
Example: "78756-3717"
A two-letter ISO 3166-1 country code
Example: "CA"
Indicates whether this is a residential address.
Default "unknown"
Enum"unknown""yes""no"
Example: "yes"
The [warehouse] that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
Default null
Example: "se-28529731"
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.
Example: "John Doe"
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Example: "+1 204-253-9411 ext. 123"
Email for the address owner.
Example: "example@example.com"
If this is a business address, then the company name should be specified here.
Example: "The Home Depot"
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
Example: "1999 Bishop Grandin Blvd."
The second line of the street address. For some addresses, this line may not be needed.
Example: "Unit 408"
The third line of the street address. For some addresses, this line may not be needed.
Example: "Building #7"
The name of the city or locality
Example: "Winnipeg"
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
Example: "Manitoba"
postal code
Example: "78756-3717"
A two-letter ISO 3166-1 country code
Example: "CA"
Indicates whether this is a residential address.
Default "unknown"
Enum"unknown""yes""no"
Example: "yes"
An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
Default false
Example: true
The type of delivery confirmation that is required for this shipment
Default "none"
Enum"none""delivery""signature""adult_signature""direct_signature""delivery_mailed""verbal_confirmation""delivery_code""age_verification_16_plus"
Customs information. This is usually only needed for international shipments.
Default null
Advanced shipment options. These are entirely optional.
This field is used to [bill shipping costs to a third party]. This field must be used in conjunction with the bill_to_country_code, bill_to_party, and bill_to_postal_code fields.
Default null
Example: "123456789"
Indicates whether to bill shipping costs to the recipient or to a third-party. When billing to a third-party, the bill_to_account, bill_to_country_code, and bill_to_postal_code fields must also be set.
Default null
Enum"recipient""third_party"
Example: "third_party"
The postal code of the third-party that is responsible for shipping costs.
Default null
Example: "28005"
Indicates that the shipment contains alcohol.
Default false
Example: true
Indicates that the shipper is paying the international delivery duties for this shipment. This option is supported by UPS, FedEx, and DHL Express.
Default false
Example: true
Indicates if the shipment contain dry ice
Default false
Example: true
The weight of the dry ice in the shipment
Indicates that the package cannot be processed automatically because it is too large or irregularly shaped. This is primarily for USPS shipments. See Section 1.2 of the USPS parcel standards for details.
Default false
Example: true
Enables Saturday delivery, if supported by the carrier.
Default false
Example: true
Whether to use [UPS Ground Freight pricing] If enabled, then a freight_class must also be specified.
Default null
Example: true
The National Motor Freight Traffic Association freight class, such as "77.5", "110", or "250".
Default null
Example: "77.5"
An arbitrary field that can be used to store information about the shipment.
Default null
Example: "custom field 1"
An arbitrary field that can be used to store information about the shipment.
Default null
Example: "custom field 2"
An arbitrary field that can be used to store information about the shipment.
Default null
Example: "custom field 3"
Indicates if the package will be picked up or dropped off by the carrier
Default null
Enum"pickup""drop_off"
Indicate to the carrier that this shipment requires additional handling.
Default null
Example: true
Defer payment until package is delivered, instead of when it is ordered.
Third Party Consignee option is a value-added service that allows the shipper to supply goods without commercial invoices being attached
Default false
Example: true
Indicates if the Dangerous goods are present in the shipment
Default false
Example: true
The Windsor framework is a new regulation in the UK that simplifies customs procedures for goods moved from the UK mainland to Northern Ireland.
Ancillary endorsements option for the shipment
Example: "forward"
Number of return pickup attempts
Example: 3
Indicates if own document upload is enabled
Default false
Example: false
Indicates if the shipment contains limited quantities
Default false
Example: false
Indicates if event notifications are enabled
Default false
Example: false
Indicates if the shipment contains fragile items
Default false
Example: false
Instructs the carrier to deliver the package only to the exact address provided
Default false
Example: false
Ensures the shipment is immediately flagged for return to the sender if the initial delivery attempt fails
Default false
Example: false
Indicates the category of goods in the shipment that is subject to special regulatory or compliance requirements
Default null
Enum"day_old_poultry""other_live_animal"
The insurance provider to use for any insured packages in the shipment.
Default "none"
Enum"none""shipsurance""carrier""third_party"
Arbitrary tags associated with this shipment. Tags can be used to categorize shipments, and shipments can be queried by their tags. Note: Tags require object structure with name property, not simple strings.
Default []
The order sources that are supported by ShipStation
Enum"amazon_ca""amazon_us""brightpearl""channel_advisor""cratejoy""ebay""etsy""jane""groupon_goods""magento"
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]
Example: "se-28529731"
shipments[].packages[].package_codestring(package_code)[ 1 .. 50 ] characters^[a-z0-9]+(_[a-z0-9]+)*$
A [package type] , such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
Example: "small_flat_rate_box"
The name of the of the [package type]
Example: "Flat Rate Envelope"
The package weight
The insured value of the package. Requires the insurance_provider field of the shipment to be set.
Default [{"currency":"usd","amount":0}]
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 |
An external package id.
Example: "se-1234545"
A short description of the package content. Required for shipments moving to, from, and through Mexico.
Example: "Hand knitted wool socks"
The NetStamps layout to use.
Enum"netstamps_traditional""netstamps_standard""netstamps_alternate""netstamps_promotional""netstamps_themed""netstamps_photo_landscape""netstamps_photo_portrait""netstamps_photo_landscape_hs""netstamps_return_address""netstamps_roll_type_sd"
Example: "netstamps_traditional"
The display format that the label should be shown in.
Default "label"
Enum"label""paperless""label_and_paperless"
Indicate if this label is being used only for testing purposes. If true, then no charge will be added to your account.
Default false
Example: true
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. 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. |
Default "url"
Enum"url""inline"
An optional Return Merchandise Authorization number for return labels.
Example: "asd12323"
The label charge event.
Enum"carrier_default""on_creation""on_carrier_acceptance"
The label_id of the original (outgoing) label that the return label is for.
Example: "se-28529731"
The possible validate address values
Default "no_validation"
Enum"no_validation""validate_only""validate_and_clean"
The label image resource that was used to create a custom label image.
Example: "img_DtBXupDBxREpHnwEXhTfgK"
A unique identifier for a carrier service point where the shipment will be delivered.
Example: "614940"
- Mock serverhttps://docs.shipstation.com/_mock/apis/openapi/v2/mailing/netstamps
- Productionhttps://api.shipstation.com/v2/mailing/netstamps
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/openapi/v2/mailing/netstamps \
-H 'Content-Type: application/json' \
-H 'api-key: YOUR_API_KEY_HERE' \
-d '{
"shipments": [
{
"carrier_id": "se-1234567",
"service_code": "se_1234567",
"requested_shipment_service": "usps_priority_mail",
"shipping_rule_id": "se-1234",
"external_order_id": "1232434",
"hold_until_date": "2025-01-15T00:00:00.000Z",
"ship_by_date": "2025-01-15T00:00:00.000Z",
"retail_rate": {
"currency": "usd",
"amount": 12
},
"store_id": "se-12345",
"items": [],
"notes_from_buyer": "Please handle with care",
"notes_for_gift": "Happy Birthday!",
"is_gift": true,
"assigned_user": "user@example.com",
"amount_paid": {
"currency": "usd",
"amount": 12
},
"shipping_paid": {
"currency": "usd",
"amount": 12
},
"tax_paid": {
"currency": "usd",
"amount": 12
},
"zone": 1,
"display_scheme": "label",
"tax_identifiers": [
{
"taxable_entity_type": "shipper",
"identifier_type": "vat",
"issuing_authority": "US",
"value": "value"
}
],
"external_shipment_id": "1234556",
"shipment_number": "10001",
"ship_date": "2018-09-23T00:00:00Z",
"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": "yes",
"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",
"address_residential_indicator": "yes",
"instructions": "any instructions"
},
"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": "yes",
"instructions": "any instructions"
},
"is_return": true,
"confirmation": "none",
"customs": null,
"advanced_options": {
"bill_to_account": "123456789",
"bill_to_country_code": "US",
"bill_to_party": "third_party",
"bill_to_postal_code": "28005",
"contains_alcohol": true,
"delivered_duty_paid": true,
"dry_ice": true,
"dry_ice_weight": {
"value": 23,
"unit": "pound"
},
"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",
"origin_type": null,
"additional_handling": true,
"shipper_release": true,
"collect_on_delivery": {
"payment_type": "any",
"payment_amount": {
"currency": "USD",
"amount": 12
}
},
"third_party_consignee": true,
"dangerous_goods": true,
"dangerous_goods_contact": {
"name": "Michael Robinson",
"phone": "123456578789"
},
"windsor_framework_details": {
"movement_indicator": "b2b",
"not_at_risk": true
},
"ancillary_endorsements_option": "forward",
"return_pickup_attempts": 3,
"own_document_upload": false,
"limited_quantity": false,
"event_notification": false,
"fragile": false,
"delivery_as_addressed": false,
"return_after_first_attempt": false,
"regulated_content_type": null,
"netstamps_options": {
"row": 1,
"column": 1
}
},
"insurance_provider": "none",
"tags": [],
"order_source_code": "amazon_ca",
"packages": [
{
"package_id": "se-123456",
"package_code": "thick_envelope",
"package_name": "Flat Rate Envelope",
"weight": {
"value": 23,
"unit": "pound"
},
"dimensions": {
"unit": "inch",
"length": 2,
"width": 2,
"height": 1
},
"insured_value": [
{
"currency": "usd",
"amount": 0
}
],
"label_messages": {
"reference1": "Reference",
"reference2": "Reference 2",
"reference3": "Reference 3"
},
"external_package_id": "se-1234545",
"content_description": "Hand knitted wool socks",
"products": []
}
],
"comparison_rate_type": "retail"
}
],
"label_layout": "netstamps_traditional",
"label_format": "pdf",
"display_scheme": "label",
"test_label": true,
"label_download_type": "url",
"is_return_label": true,
"rma_number": "asd12323",
"charge_event": "carrier_default",
"outbound_label_id": "se-28529731",
"validate_address": "no_validation",
"label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
"ship_to_service_point_id": "614940",
"ship_from_service_point_id": "614940"
}'The labels were created successfully.
A string that uniquely identifies the label. This ID is generated by ShipStation when the label is created.
Example: "se-28529731"
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] |
Enum"processing""completed""error""voided"
Example: "completed"
The shipment that this label is for. ShipStation 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]
Example: "se-28529731"
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.
Example: "externalId-1234556"
ID that the Order Source assigned
Example: "externalOrderId-1232434"
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 ShipStation .
Example: "2018-09-23T00:00:00Z"
An ISO 8601 string that represents a date and time.
Example: "2018-09-23T15:00:00.000Z"
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.
The tracking number for the package. Tracking number formats vary across carriers.
Example: "782758401696"
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
Example: true
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Example: "asd12323"
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
Example: true
If this label was created as part of a [batch], then this is the unique ID of that batch.
Example: "se-28529731"
The unique ID of the [carrier account] that was used to create this label
Example: "se-28529731"
The label charge event.
Enum"carrier_default""on_creation""on_carrier_acceptance"
A [carrier service], such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
Example: "usps_first_class_mail"
A [package type] , such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
Example: "small_flat_rate_box"
voided_atstring or null(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only
An ISO 8601 string that represents a date and time.
Example: "2018-09-23T15:00:00.000Z"
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.
Enum"refund_assist""manual"
Example: "manual"
Information about the Refund Assist request for this label. This field is null if the label is not eligible for Refund Assist.
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 |
Default "pdf"
Enum"pdf""png""zpl"
The display format that the label should be shown in.
Default "label"
Enum"label""paperless""label_and_paperless"
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.
Default "4x6"
Enum"4x6""letter"
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.
Example: true
The label image resource that was used to create a custom label image.
Example: "img_DtBXupDBxREpHnwEXhTfgK"
A [shipping carrier] , such as fedex, dhl_express, stamps_com, etc.
Example: "dhl_express"
The type of delivery confirmation that is required for this shipment.
Default "none"
Enum"none""delivery""signature""adult_signature""direct_signature""delivery_mailed""verbal_confirmation""delivery_code""age_verification_16_plus"
The current status of the package, such as in_transit or delivered
Enum"unknown""in_transit""error""delivered"
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.
Example: "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
Response
application/json
{ "label_id": "se-123456", "status": "completed", "shipment_id": "se-1234567", "external_shipment_id": "externalId-1234556", "external_order_id": "externalOrderId-1232434", "ship_date": "2018-09-23T00:00:00Z", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "usd", "amount": 12 }, "insurance_cost": { "currency": "usd", "amount": 12 }, "requested_comparison_amount": { "currency": "usd", "amount": 12 }, "tracking_number": "782758401696", "is_return_label": true, "rma_number": "asd12323", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-1234567", "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", "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": { … } }, "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "confirmation": "none", "tracking_status": "unknown", "label_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "pdf": "http://api.shipstation.com/v2/labels/se-28529731", "png": "http://api.shipstation.com/v2/labels/se-28529731", "zpl": "http://api.shipstation.com/v2/labels/se-28529731" }, "form_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "qr_code_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "paperless_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "instructions": "any instructions", "handoff_code": "122334" }, "insurance_claim": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "packages": [ { … } ], "alternative_identifiers": [ { … } ], "rate_details": [ { … } ], "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": "yes", "instructions": "any instruction", "geolocation": [ … ] }, "total_cost": { "currency": "usd", "amount": 12 }, "associated_labels": [ { … } ] }
Bodyapplication/jsonrequired
The shipments to create mail labels for. All shipments must use the same carrier_id.
The carrier account that is billed for the shipping charges
Example: "se-28529731"
A [carrier service], such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
Example: "usps_first_class_mail"
The requested shipment service
Example: "usps_priority_mail"
ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
Example: "se-28529731"
Date to hold the shipment until
Example: "2025-01-15T00:00:00.000Z"
Date by which the shipment should be shipped
Example: "2025-01-15T00:00:00.000Z"
The store ID associated with the shipment
Example: "se-28529731"
Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
Default []
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.
Example: "1234556"
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.
Example: "10001"
shipments[].ship_datestring or null(date-time)(date)^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?...
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 ShipStation .
Example: "2018-09-23T00:00:00Z"
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.
Example: "John Doe"
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Example: "+1 204-253-9411 ext. 123"
Email for the address owner.
Example: "example@example.com"
If this is a business address, then the company name should be specified here.
Example: "The Home Depot"
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
Example: "1999 Bishop Grandin Blvd."
The second line of the street address. For some addresses, this line may not be needed.
Example: "Unit 408"
The third line of the street address. For some addresses, this line may not be needed.
Example: "Building #7"
The name of the city or locality
Example: "Winnipeg"
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
Example: "Manitoba"
postal code
Example: "78756-3717"
A two-letter ISO 3166-1 country code
Example: "CA"
Indicates whether this is a residential address.
Default "unknown"
Enum"unknown""yes""no"
Example: "yes"
Additional text about how to handle the shipment at this address.
Example: "any instruction"
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.
Example: "John Doe"
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Example: "+1 204-253-9411 ext. 123"
Email for the address owner.
Example: "example@example.com"
If this is a business address, then the company name should be specified here.
Example: "The Home Depot"
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
Example: "1999 Bishop Grandin Blvd."
The second line of the street address. For some addresses, this line may not be needed.
Example: "Unit 408"
The third line of the street address. For some addresses, this line may not be needed.
Example: "Building #7"
The name of the city or locality
Example: "Winnipeg"
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
Example: "Manitoba"
postal code
Example: "78756-3717"
A two-letter ISO 3166-1 country code
Example: "CA"
Indicates whether this is a residential address.
Default "unknown"
Enum"unknown""yes""no"
Example: "yes"
The [warehouse] that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
Default null
Example: "se-28529731"
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.
Example: "John Doe"
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Example: "+1 204-253-9411 ext. 123"
Email for the address owner.
Example: "example@example.com"
If this is a business address, then the company name should be specified here.
Example: "The Home Depot"
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
Example: "1999 Bishop Grandin Blvd."
The second line of the street address. For some addresses, this line may not be needed.
Example: "Unit 408"
The third line of the street address. For some addresses, this line may not be needed.
Example: "Building #7"
The name of the city or locality
Example: "Winnipeg"
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
Example: "Manitoba"
postal code
Example: "78756-3717"
A two-letter ISO 3166-1 country code
Example: "CA"
Indicates whether this is a residential address.
Default "unknown"
Enum"unknown""yes""no"
Example: "yes"
An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
Default false
Example: true
The type of delivery confirmation that is required for this shipment
Default "none"
Enum"none""delivery""signature""adult_signature""direct_signature""delivery_mailed""verbal_confirmation""delivery_code""age_verification_16_plus"
Customs information. This is usually only needed for international shipments.
Default null
Advanced shipment options. These are entirely optional.
This field is used to [bill shipping costs to a third party]. This field must be used in conjunction with the bill_to_country_code, bill_to_party, and bill_to_postal_code fields.
Default null
Example: "123456789"
Indicates whether to bill shipping costs to the recipient or to a third-party. When billing to a third-party, the bill_to_account, bill_to_country_code, and bill_to_postal_code fields must also be set.
Default null
Enum"recipient""third_party"
Example: "third_party"
The postal code of the third-party that is responsible for shipping costs.
Default null
Example: "28005"
Indicates that the shipment contains alcohol.
Default false
Example: true
Indicates that the shipper is paying the international delivery duties for this shipment. This option is supported by UPS, FedEx, and DHL Express.
Default false
Example: true
Indicates if the shipment contain dry ice
Default false
Example: true
The weight of the dry ice in the shipment
Indicates that the package cannot be processed automatically because it is too large or irregularly shaped. This is primarily for USPS shipments. See Section 1.2 of the USPS parcel standards for details.
Default false
Example: true
Enables Saturday delivery, if supported by the carrier.
Default false
Example: true
Whether to use [UPS Ground Freight pricing] If enabled, then a freight_class must also be specified.
Default null
Example: true
The National Motor Freight Traffic Association freight class, such as "77.5", "110", or "250".
Default null
Example: "77.5"
An arbitrary field that can be used to store information about the shipment.
Default null
Example: "custom field 1"
An arbitrary field that can be used to store information about the shipment.
Default null
Example: "custom field 2"
An arbitrary field that can be used to store information about the shipment.
Default null
Example: "custom field 3"
Indicates if the package will be picked up or dropped off by the carrier
Default null
Enum"pickup""drop_off"
Indicate to the carrier that this shipment requires additional handling.
Default null
Example: true
Defer payment until package is delivered, instead of when it is ordered.
Third Party Consignee option is a value-added service that allows the shipper to supply goods without commercial invoices being attached
Default false
Example: true
Indicates if the Dangerous goods are present in the shipment
Default false
Example: true
The Windsor framework is a new regulation in the UK that simplifies customs procedures for goods moved from the UK mainland to Northern Ireland.
Ancillary endorsements option for the shipment
Example: "forward"
Number of return pickup attempts
Example: 3
Indicates if own document upload is enabled
Default false
Example: false
Indicates if the shipment contains limited quantities
Default false
Example: false
Indicates if event notifications are enabled
Default false
Example: false
Indicates if the shipment contains fragile items
Default false
Example: false
Instructs the carrier to deliver the package only to the exact address provided
Default false
Example: false
Ensures the shipment is immediately flagged for return to the sender if the initial delivery attempt fails
Default false
Example: false
Indicates the category of goods in the shipment that is subject to special regulatory or compliance requirements
Default null
Enum"day_old_poultry""other_live_animal"
The insurance provider to use for any insured packages in the shipment.
Default "none"
Enum"none""shipsurance""carrier""third_party"
Arbitrary tags associated with this shipment. Tags can be used to categorize shipments, and shipments can be queried by their tags. Note: Tags require object structure with name property, not simple strings.
Default []
The order sources that are supported by ShipStation
Enum"amazon_ca""amazon_us""brightpearl""channel_advisor""cratejoy""ebay""etsy""jane""groupon_goods""magento"
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]
Example: "se-28529731"
shipments[].packages[].package_codestring(package_code)[ 1 .. 50 ] characters^[a-z0-9]+(_[a-z0-9]+)*$
A [package type] , such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
Example: "small_flat_rate_box"
The name of the of the [package type]
Example: "Flat Rate Envelope"
The package weight
The insured value of the package. Requires the insurance_provider field of the shipment to be set.
Default [{"currency":"usd","amount":0}]
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 |
An external package id.
Example: "se-1234545"
A short description of the package content. Required for shipments moving to, from, and through Mexico.
Example: "Hand knitted wool socks"
Layout options for printing mail labels on a single sheet. Controls the starting position on the label sheet.
The mail label layout to use.
Enum"mail_label_sdc3110""mail_label_avery5160""mail_label_avery5163"
Example: "mail_label_sdc3110"
The display format that the label should be shown in.
Default "label"
Enum"label""paperless""label_and_paperless"
Indicate if this label is being used only for testing purposes. If true, then no charge will be added to your account.
Default false
Example: true
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. 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. |
Default "url"
Enum"url""inline"
An optional Return Merchandise Authorization number for return labels.
Example: "asd12323"
The label charge event.
Enum"carrier_default""on_creation""on_carrier_acceptance"
The label_id of the original (outgoing) label that the return label is for.
Example: "se-28529731"
The possible validate address values
Default "no_validation"
Enum"no_validation""validate_only""validate_and_clean"
The label image resource that was used to create a custom label image.
Example: "img_DtBXupDBxREpHnwEXhTfgK"
A unique identifier for a carrier service point where the shipment will be delivered.
Example: "614940"
- Mock serverhttps://docs.shipstation.com/_mock/apis/openapi/v2/mailing/mail_labels
- Productionhttps://api.shipstation.com/v2/mailing/mail_labels
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/openapi/v2/mailing/mail_labels \
-H 'Content-Type: application/json' \
-H 'api-key: YOUR_API_KEY_HERE' \
-d '{
"shipments": [
{
"carrier_id": "se-1234567",
"service_code": "se_1234567",
"requested_shipment_service": "usps_priority_mail",
"shipping_rule_id": "se-1234",
"external_order_id": "1232434",
"hold_until_date": "2025-01-15T00:00:00.000Z",
"ship_by_date": "2025-01-15T00:00:00.000Z",
"retail_rate": {
"currency": "usd",
"amount": 12
},
"store_id": "se-12345",
"items": [],
"notes_from_buyer": "Please handle with care",
"notes_for_gift": "Happy Birthday!",
"is_gift": true,
"assigned_user": "user@example.com",
"amount_paid": {
"currency": "usd",
"amount": 12
},
"shipping_paid": {
"currency": "usd",
"amount": 12
},
"tax_paid": {
"currency": "usd",
"amount": 12
},
"zone": 1,
"display_scheme": "label",
"tax_identifiers": [
{
"taxable_entity_type": "shipper",
"identifier_type": "vat",
"issuing_authority": "US",
"value": "value"
}
],
"external_shipment_id": "1234556",
"shipment_number": "10001",
"ship_date": "2018-09-23T00:00:00Z",
"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": "yes",
"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",
"address_residential_indicator": "yes",
"instructions": "any instructions"
},
"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": "yes",
"instructions": "any instructions"
},
"is_return": true,
"confirmation": "none",
"customs": null,
"advanced_options": {
"bill_to_account": "123456789",
"bill_to_country_code": "US",
"bill_to_party": "third_party",
"bill_to_postal_code": "28005",
"contains_alcohol": true,
"delivered_duty_paid": true,
"dry_ice": true,
"dry_ice_weight": {
"value": 23,
"unit": "pound"
},
"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",
"origin_type": null,
"additional_handling": true,
"shipper_release": true,
"collect_on_delivery": {
"payment_type": "any",
"payment_amount": {
"currency": "USD",
"amount": 12
}
},
"third_party_consignee": true,
"dangerous_goods": true,
"dangerous_goods_contact": {
"name": "Michael Robinson",
"phone": "123456578789"
},
"windsor_framework_details": {
"movement_indicator": "b2b",
"not_at_risk": true
},
"ancillary_endorsements_option": "forward",
"return_pickup_attempts": 3,
"own_document_upload": false,
"limited_quantity": false,
"event_notification": false,
"fragile": false,
"delivery_as_addressed": false,
"return_after_first_attempt": false,
"regulated_content_type": null,
"netstamps_options": {
"row": 1,
"column": 1
}
},
"insurance_provider": "none",
"tags": [],
"order_source_code": "amazon_ca",
"packages": [
{
"package_id": "se-123456",
"package_code": "thick_envelope",
"package_name": "Flat Rate Envelope",
"weight": {
"value": 23,
"unit": "pound"
},
"dimensions": {
"unit": "inch",
"length": 2,
"width": 2,
"height": 1
},
"insured_value": [
{
"currency": "usd",
"amount": 0
}
],
"label_messages": {
"reference1": "Reference",
"reference2": "Reference 2",
"reference3": "Reference 3"
},
"external_package_id": "se-1234545",
"content_description": "Hand knitted wool socks",
"products": []
}
],
"comparison_rate_type": "retail"
}
],
"mailing_options": {
"start_row": 0,
"start_column": 0
},
"label_layout": "mail_label_sdc3110",
"label_format": "pdf",
"display_scheme": "label",
"test_label": true,
"label_download_type": "url",
"is_return_label": true,
"rma_number": "asd12323",
"charge_event": "carrier_default",
"outbound_label_id": "se-28529731",
"validate_address": "no_validation",
"label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
"ship_to_service_point_id": "614940",
"ship_from_service_point_id": "614940"
}'The labels were created successfully.
A string that uniquely identifies the label. This ID is generated by ShipStation when the label is created.
Example: "se-28529731"
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] |
Enum"processing""completed""error""voided"
Example: "completed"
The shipment that this label is for. ShipStation 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]
Example: "se-28529731"
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.
Example: "externalId-1234556"
ID that the Order Source assigned
Example: "externalOrderId-1232434"
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 ShipStation .
Example: "2018-09-23T00:00:00Z"
An ISO 8601 string that represents a date and time.
Example: "2018-09-23T15:00:00.000Z"
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.
The tracking number for the package. Tracking number formats vary across carriers.
Example: "782758401696"
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
Example: true
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Example: "asd12323"
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
Example: true
If this label was created as part of a [batch], then this is the unique ID of that batch.
Example: "se-28529731"
The unique ID of the [carrier account] that was used to create this label
Example: "se-28529731"
The label charge event.
Enum"carrier_default""on_creation""on_carrier_acceptance"
A [carrier service], such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
Example: "usps_first_class_mail"
A [package type] , such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
Example: "small_flat_rate_box"
voided_atstring or null(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-only
An ISO 8601 string that represents a date and time.
Example: "2018-09-23T15:00:00.000Z"
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.
Enum"refund_assist""manual"
Example: "manual"
Information about the Refund Assist request for this label. This field is null if the label is not eligible for Refund Assist.
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 |
Default "pdf"
Enum"pdf""png""zpl"
The display format that the label should be shown in.
Default "label"
Enum"label""paperless""label_and_paperless"
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.
Default "4x6"
Enum"4x6""letter"
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.
Example: true
The label image resource that was used to create a custom label image.
Example: "img_DtBXupDBxREpHnwEXhTfgK"
A [shipping carrier] , such as fedex, dhl_express, stamps_com, etc.
Example: "dhl_express"
The type of delivery confirmation that is required for this shipment.
Default "none"
Enum"none""delivery""signature""adult_signature""direct_signature""delivery_mailed""verbal_confirmation""delivery_code""age_verification_16_plus"
The current status of the package, such as in_transit or delivered
Enum"unknown""in_transit""error""delivered"
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.
Example: "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
Response
application/json
{ "label_id": "se-123456", "status": "completed", "shipment_id": "se-1234567", "external_shipment_id": "externalId-1234556", "external_order_id": "externalOrderId-1232434", "ship_date": "2018-09-23T00:00:00Z", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "usd", "amount": 12 }, "insurance_cost": { "currency": "usd", "amount": 12 }, "requested_comparison_amount": { "currency": "usd", "amount": 12 }, "tracking_number": "782758401696", "is_return_label": true, "rma_number": "asd12323", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-1234567", "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", "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": { … } }, "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "confirmation": "none", "tracking_status": "unknown", "label_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "pdf": "http://api.shipstation.com/v2/labels/se-28529731", "png": "http://api.shipstation.com/v2/labels/se-28529731", "zpl": "http://api.shipstation.com/v2/labels/se-28529731" }, "form_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "qr_code_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "paperless_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "instructions": "any instructions", "handoff_code": "122334" }, "insurance_claim": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "packages": [ { … } ], "alternative_identifiers": [ { … } ], "rate_details": [ { … } ], "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": "yes", "instructions": "any instruction", "geolocation": [ … ] }, "total_cost": { "currency": "usd", "amount": 12 }, "associated_labels": [ { … } ] }
Bodyapplication/jsonrequired
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
Example: "se-28529731"
A [carrier service], such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
Example: "usps_first_class_mail"
The requested shipment service
Example: "usps_priority_mail"
ID of the shipping rule, which you want to use to automate carrier/carrier service selection for the shipment
Example: "se-28529731"
Date to hold the shipment until
Example: "2025-01-15T00:00:00.000Z"
Date by which the shipment should be shipped
Example: "2025-01-15T00:00:00.000Z"
The store ID associated with the shipment
Example: "se-28529731"
Describe the packages included in this shipment as related to potential metadata that was imported from external order sources
Default []
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.
Example: "1234556"
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.
Example: "10001"
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 ShipStation .
Example: "2018-09-23T00:00:00Z"
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.
Example: "John Doe"
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Example: "+1 204-253-9411 ext. 123"
If this is a business address, then the company name should be specified here.
Example: "The Home Depot"
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
Example: "1999 Bishop Grandin Blvd."
The second line of the street address. For some addresses, this line may not be needed.
Example: "Unit 408"
The third line of the street address. For some addresses, this line may not be needed.
Example: "Building #7"
The name of the city or locality
Example: "Winnipeg"
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
Example: "Manitoba"
A two-letter ISO 3166-1 country code
Example: "CA"
Indicates whether this is a residential address.
Default "unknown"
Enum"unknown""yes""no"
Example: "yes"
Additional text about how to handle the shipment at this address.
Example: "any instruction"
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.
Example: "John Doe"
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Example: "+1 204-253-9411 ext. 123"
If this is a business address, then the company name should be specified here.
Example: "The Home Depot"
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
Example: "1999 Bishop Grandin Blvd."
The second line of the street address. For some addresses, this line may not be needed.
Example: "Unit 408"
The third line of the street address. For some addresses, this line may not be needed.
Example: "Building #7"
The name of the city or locality
Example: "Winnipeg"
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
Example: "Manitoba"
postal code
Example: "78756-3717"
A two-letter ISO 3166-1 country code
Example: "CA"
Indicates whether this is a residential address.
Default "unknown"
Enum"unknown""yes""no"
Example: "yes"
The [warehouse] that the shipment is being shipped from. Either warehouse_id or ship_from must be specified.
Default null
Example: "se-28529731"
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.
Example: "John Doe"
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
Example: "+1 204-253-9411 ext. 123"
If this is a business address, then the company name should be specified here.
Example: "The Home Depot"
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
Example: "1999 Bishop Grandin Blvd."
The second line of the street address. For some addresses, this line may not be needed.
Example: "Unit 408"
The third line of the street address. For some addresses, this line may not be needed.
Example: "Building #7"
The name of the city or locality
Example: "Winnipeg"
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
Example: "Manitoba"
postal code
Example: "78756-3717"
A two-letter ISO 3166-1 country code
Example: "CA"
Indicates whether this is a residential address.
Default "unknown"
Enum"unknown""yes""no"
Example: "yes"
An optional indicator if the shipment is intended to be a return. Defaults to false if not provided.
Default false
Example: true
The type of delivery confirmation that is required for this shipment
Default "none"
Enum"none""delivery""signature""adult_signature""direct_signature""delivery_mailed""verbal_confirmation""delivery_code""age_verification_16_plus"
Customs information. This is usually only needed for international shipments.
Default null
Advanced shipment options. These are entirely optional.
This field is used to [bill shipping costs to a third party]. This field must be used in conjunction with the bill_to_country_code, bill_to_party, and bill_to_postal_code fields.
Default null
Example: "123456789"
Indicates whether to bill shipping costs to the recipient or to a third-party. When billing to a third-party, the bill_to_account, bill_to_country_code, and bill_to_postal_code fields must also be set.
Default null
Enum"recipient""third_party"
Example: "third_party"
The postal code of the third-party that is responsible for shipping costs.
Default null
Example: "28005"
Indicates that the shipment contains alcohol.
Default false
Example: true
Indicates that the shipper is paying the international delivery duties for this shipment. This option is supported by UPS, FedEx, and DHL Express.
Default false
Example: true
Indicates if the shipment contain dry ice
Default false
Example: true
The weight of the dry ice in the shipment
Indicates that the package cannot be processed automatically because it is too large or irregularly shaped. This is primarily for USPS shipments. See Section 1.2 of the USPS parcel standards for details.
Default false
Example: true
Enables Saturday delivery, if supported by the carrier.
Default false
Example: true
Whether to use [UPS Ground Freight pricing] If enabled, then a freight_class must also be specified.
Default null
Example: true
The National Motor Freight Traffic Association freight class, such as "77.5", "110", or "250".
Default null
Example: "77.5"
An arbitrary field that can be used to store information about the shipment.
Default null
Example: "custom field 1"
An arbitrary field that can be used to store information about the shipment.
Default null
Example: "custom field 2"
An arbitrary field that can be used to store information about the shipment.
Default null
Example: "custom field 3"
Indicates if the package will be picked up or dropped off by the carrier
Default null
Enum"pickup""drop_off"
Indicate to the carrier that this shipment requires additional handling.
Default null
Example: true
Defer payment until package is delivered, instead of when it is ordered.
Third Party Consignee option is a value-added service that allows the shipper to supply goods without commercial invoices being attached
Default false
Example: true
Indicates if the Dangerous goods are present in the shipment
Default false
Example: true
The Windsor framework is a new regulation in the UK that simplifies customs procedures for goods moved from the UK mainland to Northern Ireland.
Ancillary endorsements option for the shipment
Example: "forward"
Number of return pickup attempts
Example: 3
Indicates if own document upload is enabled
Default false
Example: false
Indicates if the shipment contains limited quantities
Default false
Example: false
Indicates if event notifications are enabled
Default false
Example: false
Indicates if the shipment contains fragile items
Default false
Example: false
Instructs the carrier to deliver the package only to the exact address provided
Default false
Example: false
Ensures the shipment is immediately flagged for return to the sender if the initial delivery attempt fails
Default false
Example: false
Indicates the category of goods in the shipment that is subject to special regulatory or compliance requirements
Default null
Enum"day_old_poultry""other_live_animal"
The insurance provider to use for any insured packages in the shipment.
Default "none"
Enum"none""shipsurance""carrier""third_party"
Arbitrary tags associated with this shipment. Tags can be used to categorize shipments, and shipments can be queried by their tags. Note: Tags require object structure with name property, not simple strings.
Default []
The order sources that are supported by ShipStation
Enum"amazon_ca""amazon_us""brightpearl""channel_advisor""cratejoy""ebay""etsy""jane""groupon_goods""magento"
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]
Example: "se-28529731"
shipment.packages[].package_codestring(package_code)[ 1 .. 50 ] characters^[a-z0-9]+(_[a-z0-9]+)*$
A [package type] , such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
Example: "small_flat_rate_box"
The name of the of the [package type]
Example: "Flat Rate Envelope"
The package weight
The insured value of the package. Requires the insurance_provider field of the shipment to be set.
Default [{"currency":"usd","amount":0}]
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 |
An external package id.
Example: "se-1234545"
A short description of the package content. Required for shipments moving to, from, and through Mexico.
Example: "Hand knitted wool socks"
The envelope layout to use.
Enum"envelope_9""envelope_10""envelope_11""envelope_12""envelope_personal""envelope_monarch""envelope_greeting""envelope_invitation""envelope_traditional_single""envelope_standard_single"
Example: "envelope_9"
The display format that the label should be shown in.
Default "label"
Enum"label""paperless""label_and_paperless"
Indicate if this label is being used only for testing purposes. If true, then no charge will be added to your account.
Default false
Example: true
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. 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. |
Default "url"
Enum"url""inline"
An optional Return Merchandise Authorization number for return labels.
Example: "asd12323"
The label charge event.
Enum"carrier_default""on_creation""on_carrier_acceptance"
The label_id of the original (outgoing) label that the return label is for.
Example: "se-28529731"
The possible validate address values
Default "no_validation"
Enum"no_validation""validate_only""validate_and_clean"
The label image resource that was used to create a custom label image.
Example: "img_DtBXupDBxREpHnwEXhTfgK"
A unique identifier for a carrier service point where the shipment will be delivered.
Example: "614940"
- Mock serverhttps://docs.shipstation.com/_mock/apis/openapi/v2/mailing/envelopes
- Productionhttps://api.shipstation.com/v2/mailing/envelopes
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/openapi/v2/mailing/envelopes \
-H 'Content-Type: application/json' \
-H 'api-key: YOUR_API_KEY_HERE' \
-d '{
"shipment": {
"carrier_id": "se-1234567",
"service_code": "se_1234567",
"requested_shipment_service": "usps_priority_mail",
"shipping_rule_id": "se-1234",
"external_order_id": "1232434",
"hold_until_date": "2025-01-15T00:00:00.000Z",
"ship_by_date": "2025-01-15T00:00:00.000Z",
"retail_rate": {
"currency": "usd",
"amount": 12
},
"store_id": "se-12345",
"items": [],
"notes_from_buyer": "Please handle with care",
"notes_for_gift": "Happy Birthday!",
"is_gift": true,
"assigned_user": "user@example.com",
"amount_paid": {
"currency": "usd",
"amount": 12
},
"shipping_paid": {
"currency": "usd",
"amount": 12
},
"tax_paid": {
"currency": "usd",
"amount": 12
},
"zone": 1,
"display_scheme": "label",
"tax_identifiers": [
{
"taxable_entity_type": "shipper",
"identifier_type": "vat",
"issuing_authority": "US",
"value": "value"
}
],
"external_shipment_id": "1234556",
"shipment_number": "10001",
"ship_date": "2018-09-23T00:00:00Z",
"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": "yes",
"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",
"address_residential_indicator": "yes",
"instructions": "any instructions"
},
"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": "yes",
"instructions": "any instructions"
},
"is_return": true,
"confirmation": "none",
"customs": null,
"advanced_options": {
"bill_to_account": "123456789",
"bill_to_country_code": "US",
"bill_to_party": "third_party",
"bill_to_postal_code": "28005",
"contains_alcohol": true,
"delivered_duty_paid": true,
"dry_ice": true,
"dry_ice_weight": {
"value": 23,
"unit": "pound"
},
"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",
"origin_type": null,
"additional_handling": true,
"shipper_release": true,
"collect_on_delivery": {
"payment_type": "any",
"payment_amount": {
"currency": "USD",
"amount": 12
}
},
"third_party_consignee": true,
"dangerous_goods": true,
"dangerous_goods_contact": {
"name": "Michael Robinson",
"phone": "123456578789"
},
"windsor_framework_details": {
"movement_indicator": "b2b",
"not_at_risk": true
},
"ancillary_endorsements_option": "forward",
"return_pickup_attempts": 3,
"own_document_upload": false,
"limited_quantity": false,
"event_notification": false,
"fragile": false,
"delivery_as_addressed": false,
"return_after_first_attempt": false,
"regulated_content_type": null,
"netstamps_options": {
"row": 1,
"column": 1
}
},
"insurance_provider": "none",
"tags": [],
"order_source_code": "amazon_ca",
"packages": [
{
"package_id": "se-123456",
"package_code": "thick_envelope",
"package_name": "Flat Rate Envelope",
"weight": {
"value": 23,
"unit": "pound"
},
"dimensions": {
"unit": "inch",
"length": 2,
"width": 2,
"height": 1
},
"insured_value": [
{
"currency": "usd",
"amount": 0
}
],
"label_messages": {
"reference1": "Reference",
"reference2": "Reference 2",
"reference3": "Reference 3"
},
"external_package_id": "se-1234545",
"content_description": "Hand knitted wool socks",
"products": []
}
],
"comparison_rate_type": "retail"
},
"label_layout": "envelope_9",
"label_format": "pdf",
"display_scheme": "label",
"test_label": true,
"label_download_type": "url",
"is_return_label": true,
"rma_number": "asd12323",
"charge_event": "carrier_default",
"outbound_label_id": "se-28529731",
"validate_address": "no_validation",
"label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
"ship_to_service_point_id": "614940",
"ship_from_service_point_id": "614940"
}'The label was created successfully.
A string that uniquely identifies the label. This ID is generated by ShipStation when the label is created.
Example: "se-28529731"
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] |
Enum"processing""completed""error""voided"
Example: "completed"
The shipment that this label is for. ShipStation 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]
Example: "se-28529731"
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.
Example: "externalId-1234556"
ID that the Order Source assigned
Example: "externalOrderId-1232434"
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 ShipStation .
Example: "2018-09-23T00:00:00Z"
created_atstring(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-onlyrequired
An ISO 8601 string that represents a date and time.
Example: "2018-09-23T15:00:00.000Z"
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.
The tracking number for the package. Tracking number formats vary across carriers.
Example: "782758401696"
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
Example: true
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Example: "asd12323"
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
Example: true
If this label was created as part of a [batch], then this is the unique ID of that batch.
Example: "se-28529731"
The unique ID of the [carrier account] that was used to create this label
Example: "se-28529731"
The label charge event.
Enum"carrier_default""on_creation""on_carrier_acceptance"
A [carrier service], such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
Example: "usps_first_class_mail"
A [package type] , such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
Example: "small_flat_rate_box"
voided_atstring or null(date-time)(date_time)^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(...read-onlyrequired
An ISO 8601 string that represents a date and time.
Example: "2018-09-23T15:00:00.000Z"
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.
Enum"refund_assist""manual"
Example: "manual"
Information about the Refund Assist request for this label. This field is null if the label is not eligible for Refund Assist.
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 |
Default "pdf"
Enum"pdf""png""zpl"
The display format that the label should be shown in.
Default "label"
Enum"label""paperless""label_and_paperless"
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.
Default "4x6"
Enum"4x6""letter"
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.
Example: true
The label image resource that was used to create a custom label image.
Example: "img_DtBXupDBxREpHnwEXhTfgK"
A [shipping carrier] , such as fedex, dhl_express, stamps_com, etc.
Example: "dhl_express"
The type of delivery confirmation that is required for this shipment.
Default "none"
Enum"none""delivery""signature""adult_signature""direct_signature""delivery_mailed""verbal_confirmation""delivery_code""age_verification_16_plus"
The current status of the package, such as in_transit or delivered
Enum"unknown""in_transit""error""delivered"
Reference to the various downloadable file formats for the generated label
The URL of the linked resource, if any
Example: "http://api.shipstation.com/v2/labels/se-28529731"
The URL for the pdf generated label
Example: "http://api.shipstation.com/v2/labels/se-28529731"
The URL for the png generated label
Example: "http://api.shipstation.com/v2/labels/se-28529731"
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 URL of the linked resource, if any
Example: "http://api.shipstation.com/v2/labels/se-28529731"
The instructions for the paperless download.
Default null
Example: "any instructions"
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.
Example: "small_flat_rate_box"
The package weight
The insured value of the package. Requires the insurance_provider field of the shipment to be set.
Default {"currency":"usd","amount":0}
The tracking number for the package. The format depends on the carrier.
Example: "1Z932R800392060079"
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.
Example: "Hand knitted wool socks"
Whether the package has label documents available for download
Example: true
Whether the package has form documents available for download
Example: true
Whether the package has QR code documents available for download
Example: true
Whether the package has paperless documents available for download
Example: true
Additional information some carriers may provide by which to identify a given label in their system.
A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.
The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
Example: "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
Response
application/json
{ "label_id": "se-123456", "status": "completed", "shipment_id": "se-1234567", "external_shipment_id": "externalId-1234556", "external_order_id": "externalOrderId-1232434", "ship_date": "2018-09-23T00:00:00Z", "created_at": "2018-09-23T15:00:00.000Z", "shipment_cost": { "currency": "usd", "amount": 12 }, "insurance_cost": { "currency": "usd", "amount": 12 }, "requested_comparison_amount": { "currency": "usd", "amount": 12 }, "tracking_number": "782758401696", "is_return_label": true, "rma_number": "asd12323", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-1234567", "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", "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": { … } }, "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "confirmation": "none", "tracking_status": "unknown", "label_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "pdf": "http://api.shipstation.com/v2/labels/se-28529731", "png": "http://api.shipstation.com/v2/labels/se-28529731", "zpl": "http://api.shipstation.com/v2/labels/se-28529731" }, "form_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "qr_code_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "paperless_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "instructions": "any instructions", "handoff_code": "122334" }, "insurance_claim": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "child" }, "packages": [ { … } ], "alternative_identifiers": [ { … } ], "rate_details": [ { … } ], "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": "yes", "instructions": "any instruction", "geolocation": [ … ] } }
Webhooks
Webhooks are a powerful feature that can save you from sending repeated polling requests to check on the state of something. With webhooks, ShipStation will automatically contact your servers when the stage changes. This can include parcel tracking events, notification when a batch operation completes, and more.
Operations