Create a Shipping Label

ShipEngine allows users to manage almost every facet possible for shipping. In this example, we'll show you how easy it is to generate a label

Step 1: Get Your Request Ready

For our example, we're going to request a label using USPS with the builtin provider that's included in your account (for free).

Note Normally USPS charges for labels immediately when they're generated. So to avoid incurring charges, we'll set "test_label": true to generate a USPS test label instead of a real one.

POST /v1/labels

At a minimum, you need four pieces of information to create a shipping label.

  1. A carrier service code (e.g. usps_priority_mail).
  2. Any address that you're shipping from (e.g. our offices at ShipEngine).
  3. Any address that you're shipping to (e.g. Mickey Mouse).
  4. The weight of the package you're sending (e.g. 20oz).

Open up a terminal window and use cURL and get a label to send a small package to Mickey and Minnie Mouse.

curl -iX POST \
-H 'Content-Type: application/json' \
-d '
  "test_label": true,
  "shipment": {
    "service_code": "usps_priority_mail",
    "ship_to": {
      "name": "Mickey and Minnie Mouse",
      "phone": "+1 (714) 781-4565",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US",
      "address_residential_indicator": "No"
    "ship_from": {
      "name": "Shippy",
      "phone": "512-485-4282",
      "company_name": "ShipEngine",
      "address_line1": "3800 N. Lamar Blvd.",
      "address_line2": "Suite 220",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78756",
      "country_code": "US",
      "address_residential_indicator": "No"
    "packages": [
        "weight": {
          "value": 20,
          "unit": "ounce"

You'll be greeted with a JSON payload with all sorts of data about your label, including the cost, tracking number, and a link to download the label.


Need a return label?

Return labels can be easily created by setting is_return_label to true. See this page for more details.

  "label_id": "se-202887313",
  "status": "completed",
  "shipment_id": "se-202887313",
  "ship_date": "2019-07-26T05:00:00.000Z",
  "created_at": "2019-07-26T22:10:50.286Z",
  "shipment_cost": {
    "currency": "USD",
    "amount": 6.86
  "insurance_cost": {
    "currency": "USD",
    "amount": 0.0
  "tracking_number": "9405511899560441854156",
  "is_return_label": false,
  "is_international": false,
  "batch_id": "",
  "carrier_id": "se-123890",
  "service_code": "usps_priority_mail",
  "package_code": "package",
  "voided": false,
  "label_format": "pdf",
  "label_layout": "4x6",
  "trackable": false,
  "carrier_code": "stamps_com",
  "tracking_status": "unknown",
  "label_download": {
    "pdf": "",
    "png": "",
    "zpl": "",
    "href": ""
  "form_download": null,
  "insurance_claim": null,
  "packages": [
      "package_code": "package",
      "weight": {
        "value": 1.00,
        "unit": "ounce"
      "dimensions": {
        "unit": "inch",
        "length": 0.0,
        "width": 0.0,
        "height": 0.0
      "insured_value": {
        "currency": "usd",
        "amount": 0.00
      "tracking_number": null,
      "label_messages": {
        "reference1": null,
        "reference2": null,
        "reference3": null

Step 2: Download it!

The label_download object in the response contains URLs to download the label in various formats. See Label Formats & Sizes for more details. For now, we'll just download the label in PDF format, like this:

curl -O -X GET


You can download a label in one step

In the example above, two API requests were necessary: one to create the label, and another to download the .pdf file. You can accomplish both steps in a single request by setting label_download_type: "inline". See Download a Label for more details.