Create Label

You'll use the /v1/labels/ endpoint to purchase a label from your desired carrier. The response returns a label for the specified carrier and service class and includes the tracking number you'll use to track the shipment.

If you are new to ShipStation API, make sure you read the Create a Shipping Label documentation first. It provides a step-by-step guide on creating your first label with ShipStation API.

Example Request & Response

POST /v1/labels/

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
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
	"shipment": {
        "validate_address": "validate_and_clean",
        "service_code": "usps_priority_mail",
		"ship_from": {
			"name": "John Doe",
			"company_name": "Example Corp.",
			"address_line1": "4009 Marathon Blvd",
			"city_locality": "Austin",
			"state_province": "TX",
			"postal_code": "78756",
			"country_code": "US",
			"phone": "512-555-5555",
            "email": "[email protected]"
		},
		"ship_to": {
			"name": "Amanda Miller",
			"address_line1": "525 S Winchester Blvd",
			"city_locality": "San Jose",
			"state_province": "CA",
			"postal_code": "95128",
			"country_code": "US",
            "email": "[email protected]"
		},
		"packages": [
			{
				"weight": {
					"value": 17,
					"unit": "pound"
				},
				"dimensions": {
					"length": 36,
					"width": 12,
					"height": 24,
					"unit": "inch"
				}
			}
		]
	}
}'

Response

{
    "label_id": "se-392157963",
    "status": "completed",
    "shipment_id": "se-1053748895",
    "ship_date": "2023-12-20T08:00:00Z",
    "created_at": "2023-12-20T18:02:07.7650796Z",
    "shipment_cost": {
        "currency": "usd",
        "amount": 175.0400
    },
    "insurance_cost": {
        "currency": "usd",
        "amount": 0.0
    },
    "requested_comparison_amount": {
        "currency": "usd",
        "amount": 0.0
    },
    "rate_details": [
        {
            "rate_detail_type": "shipping",
            "carrier_description": null,
            "carrier_billing_code": "Base Rate",
            "carrier_memo": null,
            "amount": {
                "currency": "usd",
                "amount": 175.04
            },
            "billing_source": "Carrier"
        }
    ],
    "tracking_number": "9405511899562082413495",
    "is_return_label": false,
    "rma_number": null,
    "is_international": false,
    "batch_id": "",
    "carrier_id": "se-4712287",
    "service_code": "usps_priority_mail",
    "package_code": "package",
    "voided": false,
    "voided_at": null,
    "label_format": "pdf",
    "display_scheme": "label",
    "label_layout": "4x6",
    "trackable": true,
    "label_image_id": null,
    "carrier_code": "stamps_com",
    "tracking_status": "in_transit",
    "label_download": {
        "pdf": "https://api.shipengine.com/v1/downloads/10/wpTzhiFW9ke8L-_6rJHmEA/label-392157963.pdf",
        "png": "https://api.shipengine.com/v1/downloads/10/wpTzhiFW9ke8L-_6rJHmEA/label-392157963.png",
        "zpl": "https://api.shipengine.com/v1/downloads/10/wpTzhiFW9ke8L-_6rJHmEA/label-392157963.zpl",
        "href": "https://api.shipengine.com/v1/downloads/10/wpTzhiFW9ke8L-_6rJHmEA/label-392157963.pdf"
    },
    "form_download": null,
    "qr_code_download": null,
    "insurance_claim": null,
    "packages": [
        {
            "package_id": 410478985,
            "package_code": "package",
            "weight": {
                "value": 17.00,
                "unit": "pound"
            },
            "dimensions": {
                "unit": "inch",
                "length": 36.00,
                "width": 12.00,
                "height": 24.00
            },
            "insured_value": {
                "currency": "usd",
                "amount": 0.00
            },
            "tracking_number": "9405511899562082413495",
            "qr_code_download": null,
            "label_messages": {
                "reference1": null,
                "reference2": null,
                "reference3": null
            },
            "external_package_id": null,
            "content_description": null,
            "sequence": 1,
            "alternative_identifiers": []
        }
    ],
    "charge_event": "carrier_default",
    "alternative_identifiers": []
}

NOTE: This example request and response includes the validate_address property, which customers on the Free plan can use to access the address validation functionality. The Advanced plan and above also have access to the validate address endpoint that allows you to validate addresses separately from purchasing a label.