Paperless Labels

Paperless shipping (also called labelless shipping) allows you to send a shipment without printing a traditional label. Paperless services are quickly becoming more common and are an excellent way to serve senders that do not have a printer available.

A common use case for paperless services is for returns. Paperless returns help customers by not requiring the printing of a label. Instead, the customer can take their barcode or handoff code to the carrier, who will label the shipment as needed. This also allows merchants to avoid the label-in-a-box strategy where the pre-printed return label might not ever be used.

For details on creating USPS paperless labels, see our Stamps.com (USPS) Carrier Guide

Paperless Methods

When your label request specifies the paperless display schema, the carrier will typically return a handoff code, barcode (for example, a QR code), instructions for next steps, or a mix of all of these.

Handoff code: Depending on the carrier, the handoff code can be written on the package, provided to a member of staff at drop-off point, or entered via pin pad into a dedicated mechine like a package locker or label printer at a drop-off point.
Barcode (ex: QR code): The code is scanned at the drop-off point. This may be by a staff member who will accept the package but can also apply to drop-off lockers using in-built scanners.

Some carriers don't generate a barcode at all. Instead, the carrier generates the label and brings it when they collect the package.

Request a Paperless Label

To request a paperless label, include the display_scheme property in your label request with one of the following values:

Value	Description
`label`	Default. Requests only the traditional label from the carrier.
`paperless`	Requests only the paperless label from the carrier.
`label_and_paperless`	Requests both a traditional label and the paperless label from the carrier.
`qr_code`	Soon to be deprecated. Available to provide backward compatibility with prior paperless implementation in ShipEngine.
`label_and_qr_code`	Soon to be deprecated. Available to provide backward compatibility with prior paperless implementation in ShipEngine.

We recommend only using the updated paperless or label_and_paperless values when requesting a paperless label as these display schemas cover a broader range of use cases than just a QR code.

Example Request & Response

Add the display_scheme property to your purchase label request. This example uses a "dummy" carrier and service and may not include all properties needed for a live shipment.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
    "label_layout":"4x6",
    "display_scheme": "paperless",
    "shipment": {
        "carrier_id": "se-123456",
        "service_code": "dummy_carrier_premium_same_day",
        "ship_from": {
            "name": "Dade Murphy",
            "phone": "512-555-5555",
            "email": "[email protected]",
            "company_name": "Zero Cool",
            "address_line1": "123 Main St",
            "address_line2": "Apt 305",
            "city_locality": "Austin",
            "state_province": "TX",
            "postal_code": "78731",
            "country_code": "US"
        },
        "ship_to": {
            "name": "Kate Libby",
            "phone": "714-444-5555",
            "email": "[email protected]",
            "company_name": "The Garbage file",
            "address_line1": "2321 Grand Ave",
            "address_line2": "",
            "city_locality": "Leander",
            "state_province": "TX",
            "postal_code": "78641",
            "country_code": "US",
            "email": "[email protected]"
        },
        "packages": [
            {
                "weight": {
                    "value": 1,
                    "unit": "pound"
                },
                "dimensions": {
                    "unit": "inch",
                    "length": 1,
                    "width": 2,
                    "height": 3
                },
                "label_messages": {
                    "reference1": "BillingReference1",
                    "reference2": "BillingReference2"
                }
            }
        ]
    }
}

Response

For paperless services, the recommended way to consume the paperless data is via the paperless_download object, which will always be present when one of the paperless schema is set in the request.

Please note that, for backward compatibility reasons, ShipEngine will also populate the label_download object with links to a document that contains a rasterized representation of the paperless_download where all parameters are merged together into a single document (for example, a barcode, handoff code, or instructions).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
{
  "label_id": "se-012345",
  "status": "completed",
  "shipment_id": "se-1111111",
  "ship_date": "2024-04-10T07:00:00Z",
  "created_at": "2024-04-10T09:58:34.7964037Z",
  "shipment_cost": {
      "currency": "usd",
      "amount": 34.0
  },
  "insurance_cost": {
      "currency": "usd",
      "amount": 0.0
  },
  "tracking_number": "US.US.20240410.1712743114912.1",
  "is_return_label": false,
  "is_international": false,
  "batch_id": "",
  "carrier_id": "se-123456",
  "service_code": "dummy_carrier_premium_same_day",
  "package_code": "package",
  "voided": false,
  "label_format": "pdf",
  "display_scheme": "paperless",
  "label_layout": "4x6",
  "trackable": true,
  "carrier_code": "apicode-dummy-carrier",
  "tracking_status": "in_transit",
  "label_download": {
      "pdf": "https://api.shipengine.com/v1/downloads/8/9FCweYLJK0mEabBvlOBRIQ/label-107205664.pdf",
      "png": "https://api.shipengine.com/v1/downloads/8/9FCweYLJK0mEabBvlOBRIQ/label-107205664.png",
      "zpl": "https://api.shipengine.com/v1/downloads/8/9FCweYLJK0mEabBvlOBRIQ/label-107205664.zpl",
      "href": "https://api.shipengine.com/v1/downloads/8/9FCweYLJK0mEabBvlOBRIQ/label-107205664.pdf"
  },
  "paperless_download": {
      "href": "https://api.shipengine.com/v1/downloads/8/EXyUADSveUiaOqTMekdPrw/paperlesslabel-107205664.png",
      "instructions": "Leave with front desk",
      "handoff_code": "1234"
  },
  "packages": [
      {
          "package_id": 68764917,
          "package_code": "package",
          "weight": {
              "value": 1.00,
              "unit": "pound"
          },
          "dimensions": {
              "unit": "inch",
              "length": 1.00,
              "width": 2.00,
              "height": 3.00
          },
          "insured_value": {
              "currency": "usd",
              "amount": 0.00
          },
          "tracking_number": "US.US.20240410.1712743114912.1",
          "label_download": {
              "pdf": "https://api.shipengine.com/v1/downloads/8/OoTqlqXKxUu1fM0lNlmPwg/labelpackage-68764917.pdf",
              "png": "https://api.shipengine.com/v1/downloads/8/OoTqlqXKxUu1fM0lNlmPwg/labelpackage-68764917.png",
              "zpl": "https://api.shipengine.com/v1/downloads/8/OoTqlqXKxUu1fM0lNlmPwg/labelpackage-68764917.zpl"
          },
          "paperless_download": {
              "href": "https://api.shipengine.com/v1/downloads/8/_HkHkeoORkqih1MVIHx5cQ/paperlesslabelpackage-68764917.png",
              "instructions": "Leave with front desk",
              "handoff_code": "1234"
          },
          "label_messages": {
              "reference1": "BillingReference1",
              "reference2": "BillingReference2"
          },
          "sequence": 1,
          "alternative_identifiers": [],
          "has_label_documents": true,
          "has_form_documents": false,
          "has_qr_code_documents": true,
          "has_paperless_label_documents": true
      }
  ],
  "charge_event": "carrier_default",
  "alternative_identifiers": []
}

There are a few things to note about the response:

The paperless_download object includes three parameters:
- href: a link to the document returned by the carrier (typically a barcode).
- instructions: the instructions provided by the carrier to describe what to do with the output. For example, "Scan the QR code at the carrier locker" or "Use the pin pad to enter the handoff code".
- handoff_code: the code used to hand off the package to the carrier (often entered via pin pad on a package locker, but can also be a code to provide staff when picked up from a location or at a drop off point).
Certain carriers may not include all of these parameters. If a carrier does not include the parameter, it will not be present in the response.
The paperless_download object is shown at both the shipment level and the package level. Where this object is returned for your specific use case will depend on which carrier you are using.

Example Barcode

Here is an example of the rasterized representation from the label_download object.

Customer Communication

Using paperless labels might be a new experience for your cusomters. You may want to send email with the barcode image to help educate your customer on what they need to do to ship their package, including locating drop-off locations or how to use the barcode to hand over the package to the carrier.