Create mailing labels
Create one or more mailing labels on a sheet layout. Use mailing_options to control which row and column to start printing from.
Request body
The mail label layout to use.
The file format for the label.
The display format that the label should be shown in.
Indicate if this label is being used only for testing purposes. If true, then no charge will be added to your account.
There are two different ways to download a label:
| Label Download Type | Description |
|---|---|
| url | You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days. |
| inline | You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. |
Indicates whether these are return labels.
An optional Return Merchandise Authorization number for return labels.
Determines when the user's account will be charged for the label.
A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
The possible validate address values
Used to identify an image resource.
A unique identifier for a carrier service point where the shipment will be delivered.
A unique identifier for a carrier drop off point where a merchant plans to deliver packages.
Response
The labels were created successfully.
A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
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 |
A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
A unique user-defined key to identify a shipment. This can be used to retrieve the shipment.
ID that the Order Source assigned
An ISO 8601 string that represents a date, but not a specific time. The value may contain a time component, but it will be set to 00:00:00 UTC by ShipEngine.
An ISO 8601 string that represents a date and time.
The tracking number for the package. Tracking number formats vary across carriers.
Indicates whether this is a return label. You may also want to set the rma_number so you know what is being returned.
An optional Return Merchandise Authorization number. This field is useful for return labels. You can set it to any string value.
Indicates whether this is an international shipment. That is, the originating country and destination country are different.
A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
Determines when the user's account will be charged for the label.
A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
Indicate if this label is being used only for testing purposes. If true, then no charge will be added to your account.
A package type, such as thick_envelope, small_flat_rate_box, large_package, etc. Use the code package for custom or unknown package types.
The possible validate address values
Indicates whether the label has been voided
An ISO 8601 string that represents a date and time.
There are two different ways to download a label:
| Label Download Type | Description |
|---|---|
| url | You will receive a URL, which you can use to download the label in a separate request. The URL will remain valid for 90 days. |
| inline | You will receive the Base64-encoded label as part of the response. No need for a second request to download the label. |
The possible file formats in which shipping labels can be downloaded. We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
| Label Format | Supported Carriers |
|---|---|
| All carriers | |
| png | fedex <br> stamps_com <br> ups <br> usps |
| zpl | access_worldwide <br> apc <br> asendia <br> dhl_global_mail <br> dhl_express <br> dhl_express_australia <br> dhl_express_canada <br> dhl_express_worldwide <br> dhl_express_uk <br> dpd <br> endicia <br> fedex <br> fedex_uk <br> firstmile <br> imex <br> newgistics <br> ontrac <br> rr_donnelley <br> stamps_com <br> ups <br> usps |
The display format that the label should be shown in.
The available layouts (sizes) in which shipping labels can be downloaded. The label format determines which sizes are supported. 4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.
Used to identify an image resource.
A shipping carrier, such as fedex, dhl_express, stamps_com, etc.
The different statuses that can apply to a shipment.
The possible delivery confirmation values
The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
Indicates how the label was voided. This field is null if the label has not been voided.