{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/labels/create-a-label","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/labels/create-a-label","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/labels/create-a-label","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Create a Shipping Label","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"create-a-shipping-label","__idx":0},"children":["Create a Shipping Label"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide will walk you through how to create your first shipping label using ShipStation API and provides the details and context you need to understand how this process works."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you begin:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sign up for a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://www.shipengine.com/signup/"},"children":["ShipStation API"]}," account, if you haven't already."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate an ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/guides/auth#api-keys"},"children":["API key"]},". A ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/guides/auth#types-of-api-keys"},"children":["sandbox API key"]}," will work for this tutorial."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You'll need a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/getting-started/tools"},"children":["tool to make an API call"]},", like ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/guides/curl"},"children":["curl"]}," or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/postman"},"children":["Postman"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you create a shipping label with ShipStation API, you'll generally follow these basic steps (described in detail below):"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#step-1-prepare-your-request"},"children":["Prepare your request"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#step-2-sending-the-request"},"children":["Send the request"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#step-3-download-the-label"},"children":["Download the label"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this tutorial, you'll request a label using the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/carriers/setup"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["UPS"]}," services that are included with your ShipStation API account"]},". However, the general steps are the same no matter which carrier you use."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["TIP:"]}," ","To access your API key directly in this tutorial, ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://dashboard.shipengine.com"},"children":["sign into your ShipStation API account"]}," first. Your API key will then populate into the example requests so you can easily copy and paste into your own tools."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-prepare-your-request","__idx":1},"children":["Step 1: Prepare Your Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create a label, you'll send an ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/getting-started/rest#methods"},"children":["HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.shipengine.com/v1/labels"]},". From now on we'll refer to this as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/labels"]}," endpoint."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"headers","__idx":2},"children":["Headers"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are two ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/getting-started/rest#headers"},"children":["HTTP headers"]}," that you need to set in your request:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Header"},"children":["HTTP Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Desription"},"children":["Desription"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Content-Type header specifies the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://en.wikipedia.org/wiki/Media_type"},"children":["media type"]}," of your API request. ShipStation API requires all requests to be in ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/getting-started/rest#json"},"children":["JSON format"]},", so this header should always be set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["API-Key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["For this header you'll need to pass your ShipStation API key. This is how the ShipStation API knows who you are."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-body","__idx":3},"children":["Request Body"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The body of your request is where you'll specify all the information about the shipping label you want to create, such as the \"from\" and \"to\" addresses, the package weight and dimensions, etc."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For this tutorial, we'll create a label with the following details:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Value"},"children":["Value"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delivery Service"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UPS Ground"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ship from address"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["John Doe",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," 4301 Bull Creek Rd ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Austin, TX 78731",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"+1 555-555-5555"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ship to address"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Jane Doe",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"525 S Winchester Blvd",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"San Jose, CA 95128",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"+1 444-444-4444"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Package weight"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["20 ounces"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Package dimensions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["12 x 24 x 6 inches"]}]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["TIP:"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"phone-number-formatting","__idx":4},"children":["Phone Number Formatting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phone"]}," property in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_to"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ship_from"]}," objects is a string and is not validated based on format. However, some carriers may return an error if the format is not valid for the countries they deliver to. Best practice is to use the phone number format specific to the Ship To and Ship From country, including the calling-code prefix."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's what our label request body will look like using the above shipment details. There are additional optional fields that are left out of this request, but it does include the minimum fields recommended for shipping a package."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"shipment\": {\n    \"carrier_id\": \"se-123456\",\n    \"service_code\": \"ups_ground\",\n    \"ship_to\": {\n      \"name\": \"Jane Doe\",\n      \"phone\": \"+1 444-444-4444\",\n      \"address_line1\": \"525 S Winchester Blvd\",\n      \"city_locality\": \"San Jose\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95128\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"yes\"\n    },\n    \"ship_from\": {\n      \"name\": \"John Doe\",\n      \"company_name\": \"Example Corp\",\n      \"phone\": \"+1 555-555-5555\",\n      \"address_line1\": \"4301 Bull Creek Rd\",\n      \"city_locality\": \"Austin\",\n      \"state_province\": \"TX\",\n      \"postal_code\": \"78731\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"no\"\n    },\n    \"packages\": [\n      {\n        \"weight\": {\n          \"value\": 20,\n          \"unit\": \"ounce\"\n        },\n        \"dimensions\": {\n          \"height\": 6,\n          \"width\": 12,\n          \"length\": 24,\n          \"unit\": \"inch\"\n        }\n      }\n    ]\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-send-the-request","__idx":5},"children":["Step 2: Send the Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now, we'll take the request body from Step 1 for the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v1/labels"]}," call and put it all together using ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/guides/curl"},"children":["curl"]},". When you use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v1/labels"]}," to create labels with your production API key, you are purchasing the label from the selected carrier. For ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/carriers/setup"},"children":["ShipStation Carriers"]},", the label cost will be deducated from your account balance. For your own carriers you've connected to ShipStation API, you'll be invoiced according to that carrier's usual method."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["TIP:"]}," You can copy/paste the following curl example into your Terminal, or you can change the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["programming language"]}," of this code sample using the dropdown list in the top right corner. We suggest selecting \"curl\" for this tutorial."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request--response","__idx":6},"children":["Example Request & Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/labels HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"shipment\": {\n    \"carrier_id\": \"se-123456\",\n    \"service_code\": \"ups_ground\",\n    \"ship_to\": {\n      \"name\": \"Jane Doe\",\n      \"phone\": \"+1 444-444-4444\",\n      \"email\": \"recipient@example.com\",\n      \"address_line1\": \"525 S Winchester Blvd\",\n      \"city_locality\": \"San Jose\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95128\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"yes\"\n    },\n    \"ship_from\": {\n      \"name\": \"John Doe\",\n      \"company_name\": \"Example Corp\",\n      \"phone\": \"+1 555-555-5555\",\n      \"email\": \"sender@example.com\",\n      \"address_line1\": \"4301 Bull Creek Rd\",\n      \"city_locality\": \"Austin\",\n      \"state_province\": \"TX\",\n      \"postal_code\": \"78731\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"no\"\n    },\n    \"packages\": [\n      {\n        \"weight\": {\n          \"value\": 20,\n          \"unit\": \"ounce\"\n        },\n        \"dimensions\": {\n          \"height\": 6,\n          \"width\": 12,\n          \"length\": 24,\n          \"unit\": \"inch\"\n        }\n      }\n    ]\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your request was successful, you'll receive an ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/getting-started/rest#status-codes"},"children":["HTTP 200 response"]},". The response payload includes all the details you need about the label, including (but not limited to):"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Status: completed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Label and shipment IDs"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Label cost"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Link to download the label in different formats (PNG, PDF, ZPL)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Service type"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Package type"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Label size"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tracking number"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"label_id\": \"se-396884371\",\n    \"status\": \"completed\",\n    \"shipment_id\": \"se-1080108982\",\n    \"ship_date\": \"2024-01-03T08:00:00Z\",\n    \"created_at\": \"2024-01-03T17:37:21.6482315Z\",\n    \"shipment_cost\": {\n        \"currency\": \"usd\",\n        \"amount\": 17.58\n    },\n    \"insurance_cost\": {\n        \"currency\": \"usd\",\n        \"amount\": 0.0\n    },\n    \"requested_comparison_amount\": null,\n    \"rate_details\": [],\n    \"tracking_number\": \"1ZYF85760394283643\",\n    \"is_return_label\": false,\n    \"rma_number\": null,\n    \"is_international\": false,\n    \"batch_id\": \"\",\n    \"carrier_id\": \"se-123456\",\n    \"service_code\": \"ups_ground\",\n    \"package_code\": \"package\",\n    \"voided\": false,\n    \"voided_at\": null,\n    \"label_format\": \"pdf\",\n    \"display_scheme\": \"label\",\n    \"label_layout\": \"4x6\",\n    \"trackable\": true,\n    \"label_image_id\": null,\n    \"carrier_code\": \"ups\",\n    \"tracking_status\": \"in_transit\",\n    \"label_download\": {\n        \"pdf\": \"https://api.shipengine.com/v1/downloads/10/N7a1AuQIwk2PjYM2H2KVrA/label-396884371.pdf\",\n        \"png\": \"https://api.shipengine.com/v1/downloads/10/N7a1AuQIwk2PjYM2H2KVrA/label-396884371.png\",\n        \"zpl\": \"https://api.shipengine.com/v1/downloads/10/N7a1AuQIwk2PjYM2H2KVrA/label-396884371.zpl\",\n        \"href\": \"https://api.shipengine.com/v1/downloads/10/N7a1AuQIwk2PjYM2H2KVrA/label-396884371.pdf\"\n    },\n    \"form_download\": null,\n    \"qr_code_download\": null,\n    \"insurance_claim\": null,\n    \"packages\": [\n        {\n            \"package_id\": 415397454,\n            \"package_code\": \"package\",\n            \"weight\": {\n                \"value\": 20.00,\n                \"unit\": \"ounce\"\n            },\n            \"dimensions\": {\n                \"unit\": \"inch\",\n                \"length\": 24.00,\n                \"width\": 12.00,\n                \"height\": 6.00\n            },\n            \"insured_value\": {\n                \"currency\": \"usd\",\n                \"amount\": 0.00\n            },\n            \"tracking_number\": \"1ZYF85760394283643\",\n            \"label_download\": {\n                \"pdf\": \"https://api.shipengine.com/v1/downloads/10/HKNTqQS9yEq7rWuATnCSqQ/labelpackage-415397454.pdf\",\n                \"png\": \"https://api.shipengine.com/v1/downloads/10/HKNTqQS9yEq7rWuATnCSqQ/labelpackage-415397454.png\",\n                \"zpl\": \"https://api.shipengine.com/v1/downloads/10/HKNTqQS9yEq7rWuATnCSqQ/labelpackage-415397454.zpl\"\n            },\n            \"qr_code_download\": null,\n            \"label_messages\": {\n                \"reference1\": null,\n                \"reference2\": null,\n                \"reference3\": null\n            },\n            \"external_package_id\": null,\n            \"content_description\": null,\n            \"sequence\": 1,\n            \"alternative_identifiers\": []\n        }\n    ],\n    \"charge_event\": \"carrier_default\",\n    \"alternative_identifiers\": []\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-download-the-label","__idx":7},"children":["Step 3: Download the Label"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In your response, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_download"]}," object includes the URLs you can use to download the label in various formats."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"label_download\": {\n    \"pdf\": \"https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.pdf\",\n    \"png\": \"https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.png\",\n    \"zpl\": \"https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.zpl\",\n    \"href\": \"https://api.shipengine.com/v1/downloads/10/XNGDhq7uZ0CAEt5LOnCxIg/label-7764944.pdf\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The label ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/formats"},"children":["download formats"]}," include:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Format"},"children":["Format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Uses"},"children":["Uses"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pdf"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Adobe PDF file"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A common format that's supported by most printers. Also a good format for email attachments when sending shipping labels to customers."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["png"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PNG image file"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PNG images are great for embedding in emails, web pages, or mobile apps."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["zpl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://en.wikipedia.org/wiki/Zebra_(programming_language)"},"children":["Zebra Printer"]}," file"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["If you print labels using a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://www.zebra.com/us/en/products/printers.html"},"children":["Zebra Printer"]},", then ZPL is probably the best file format to use. However, please note that not all carriers support the ZPL format."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These URLs are just like any other URLs in that you can paste them into a browser to download the file. You can also download the label using curl."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Copy the curl request below and replace the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["__YOUR_LABEL_URL_HERE__"]}," placeholder with the URL of the label format you wish to download."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -iOX GET __YOUR_LABEL_URL_HERE__\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Congratulations! You've downloaded your first label!"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"automated-carrier-selection-with-rate-shopper","__idx":8},"children":["Automated Carrier Selection with Rate Shopper"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you don't want to manually select a carrier and service for each label, you can use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rate Shopper"]}," endpoint to automate this decision based on cost, speed, or value optimization."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"when-to-use-rate-shopper","__idx":9},"children":["When to Use Rate Shopper"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rate Shopper is ideal for:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Automated fulfillment systems"]}," where human review isn't needed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["High-volume operations"]}," with consistent shipping priorities"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Standardized workflows"]}," where you always choose the cheapest or fastest option"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-it-works","__idx":10},"children":["How It Works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instead of specifying ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_code"]}," in your shipment, you provide a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate_shopper_id"]}," in the URL path. ShipStation API will:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retrieve rates from all your connected wallet carriers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select the best rate according to your strategy"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create and return the label in one step"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-request","__idx":11},"children":["Example Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v1/labels/rate_shopper_id/{rate_shopper_id}"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This example uses the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cheapest"]}," strategy to automatically select the lowest-cost carrier and service:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/labels/rate_shopper_id/cheapest HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"shipment\": {\n    \"ship_to\": {\n      \"name\": \"Jane Doe\",\n      \"phone\": \"+1 444-444-4444\",\n      \"address_line1\": \"525 S Winchester Blvd\",\n      \"city_locality\": \"San Jose\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95128\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"yes\"\n    },\n    \"ship_from\": {\n      \"name\": \"John Doe\",\n      \"company_name\": \"Example Corp\",\n      \"phone\": \"+1 555-555-5555\",\n      \"address_line1\": \"4301 Bull Creek Rd\",\n      \"city_locality\": \"Austin\",\n      \"state_province\": \"TX\",\n      \"postal_code\": \"78731\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"no\"\n    },\n    \"packages\": [\n      {\n        \"weight\": {\n          \"value\": 20,\n          \"unit\": \"ounce\"\n        },\n        \"dimensions\": {\n          \"height\": 6,\n          \"width\": 12,\n          \"length\": 24,\n          \"unit\": \"inch\"\n        }\n      }\n    ]\n  },\n  \"label_format\": \"pdf\",\n  \"label_layout\": \"4x6\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response includes which carrier and service were automatically selected:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"label_id\": \"se-396884371\",\n  \"status\": \"completed\",\n  \"shipment_id\": \"se-1080108982\",\n  \"ship_date\": \"2026-02-27T08:00:00Z\",\n  \"created_at\": \"2026-02-27T17:37:21.648Z\",\n  \"shipment_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 17.58\n  },\n  \"insurance_cost\": {\n    \"currency\": \"usd\",\n    \"amount\": 0.0\n  },\n  \"tracking_number\": \"1ZYF85760394283643\",\n  \"is_return_label\": false,\n  \"is_international\": false,\n  \"batch_id\": \"\",\n  \"carrier_id\": \"se-5904054\",\n  \"service_code\": \"ups_ground\",\n  \"carrier_code\": \"ups\",\n  \"package_code\": \"package\",\n  \"voided\": false,\n  \"label_format\": \"pdf\",\n  \"label_layout\": \"4x6\",\n  \"trackable\": true,\n  \"tracking_status\": \"in_transit\",\n  \"rate_shopper_id\": \"cheapest\",\n  \"label_download\": {\n    \"pdf\": \"https://api.shipengine.com/v1/downloads/10/xxx/label-396884371.pdf\",\n    \"png\": \"https://api.shipengine.com/v1/downloads/10/xxx/label-396884371.png\",\n    \"zpl\": \"https://api.shipengine.com/v1/downloads/10/xxx/label-396884371.zpl\",\n    \"href\": \"https://api.shipengine.com/v1/downloads/10/xxx/label-396884371.pdf\"\n  },\n  \"form_download\": null,\n  \"insurance_claim\": null,\n  \"packages\": [\n    {\n      \"package_id\": 415397454,\n      \"package_code\": \"package\",\n      \"weight\": {\n        \"value\": 20.00,\n        \"unit\": \"ounce\"\n      },\n      \"dimensions\": {\n        \"unit\": \"inch\",\n        \"length\": 24.00,\n        \"width\": 12.00,\n        \"height\": 6.00\n      },\n      \"insured_value\": {\n        \"currency\": \"usd\",\n        \"amount\": 0.00\n      },\n      \"tracking_number\": \"1ZYF85760394283643\",\n      \"label_messages\": {\n        \"reference1\": null,\n        \"reference2\": null,\n        \"reference3\": null\n      },\n      \"external_package_id\": null,\n      \"sequence\": 1\n    }\n  ],\n  \"charge_event\": \"carrier_default\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notice the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rate_shopper_id"]}," field in the response, which confirms the strategy used, and the automatically selected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_code"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_code"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"important-requirements","__idx":12},"children":["Important Requirements"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["⚠️ Critical"]},": When using Rate Shopper, you ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must NOT"]}," include any of these fields in your shipment object:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_code"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipping_rule_id"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If any of these fields are present, the API will return a validation error. Rate Shopper determines these values automatically."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"rate-shopper-strategies","__idx":13},"children":["Rate Shopper Strategies"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Strategy"},"children":["Strategy"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Path Parameter"},"children":["Path Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use Case"},"children":["Use Case"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cheapest"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/cheapest"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Minimize shipping costs for non-urgent deliveries"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fastest"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/fastest"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Time-critical shipments where speed is paramount"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Best Value"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/best_value"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Balance cost and speed (arrives within 4 days)"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"troubleshooting","__idx":14},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No rates available"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you receive a 404 error with message \"No rates found\", verify:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have wallet carriers connected to your account"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your shipment parameters are valid (addresses, package dimensions)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The destination is supported by your connected carriers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Package dimensions and weight are within carrier limits"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you need to ship to a specific carrier, use the standard label creation endpoint (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v1/labels"]},") with explicit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_code"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cancel-a-label","__idx":15},"children":["Cancel a Label"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you need to cancel a label due to a mistake or because something about the package changed after you created the label, you can do so! Check out ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/voiding"},"children":["our guide on voiding a label"]}," to learn more."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-next","__idx":16},"children":["What's Next?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are multiple ways to create labels with ShipStation API, each suited for different workflows:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"#automated-carrier-selection-with-rate-shopper"},"children":["Automated carrier selection with Rate Shopper"]}]}," - Let ShipStation API automatically choose the best carrier and service based on cost, speed, or value"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/create-from-rate"},"children":["Create a label from a rate"]}]}," - Display rates to customers or review options before purchasing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/create-from-shipment"},"children":["Create a label from a shipment"]}]}," - Create multiple labels from a single shipment"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/bulk"},"children":["Create labels in bulk"]}]}," - Process large batches of labels efficiently"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Finally, explore the following options to customize or make your workflow more efficient:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request and download in one call"]},": In the example above, two requests were necessary... one to create the label, and another to download the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".pdf"]}," file. You can accomplish both steps in a single request by setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_download_type: \"inline\""]},". See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/downloading"},"children":["Download a Label"]}," for more details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create a return label with an outgoing label"]},": You can create return labels by setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_return_label"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},". See our ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/shipping/returns"},"children":["Return Shipping Labels page"]}," for more details."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create branded labels"]},": Learn how to customize your labels so they print with your brand's logo or other images and see which carriers support this feature on the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/branding"},"children":["Create Custom Shipping Labels page"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Add messages to labels"]},": Show your customers an additional level of care and detail by adding a personal or customized message. See the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/messages"},"children":["Custom Label Messages page"]}," for details."]}]}]},"headings":[{"value":"Create a Shipping Label","id":"create-a-shipping-label","depth":1},{"value":"Step 1: Prepare Your Request","id":"step-1-prepare-your-request","depth":2},{"value":"Headers","id":"headers","depth":3},{"value":"Request Body","id":"request-body","depth":3},{"value":"Phone Number Formatting","id":"phone-number-formatting","depth":3},{"value":"Step 2: Send the Request","id":"step-2-send-the-request","depth":2},{"value":"Example Request & Response","id":"example-request--response","depth":3},{"value":"Step 3: Download the Label","id":"step-3-download-the-label","depth":2},{"value":"Automated Carrier Selection with Rate Shopper","id":"automated-carrier-selection-with-rate-shopper","depth":2},{"value":"When to Use Rate Shopper","id":"when-to-use-rate-shopper","depth":3},{"value":"How It Works","id":"how-it-works","depth":3},{"value":"Example Request","id":"example-request","depth":3},{"value":"Important Requirements","id":"important-requirements","depth":3},{"value":"Rate Shopper Strategies","id":"rate-shopper-strategies","depth":3},{"value":"Troubleshooting","id":"troubleshooting","depth":3},{"value":"Cancel a Label","id":"cancel-a-label","depth":2},{"value":"What's Next?","id":"whats-next","depth":2}],"frontmatter":{"seo":{"title":"Create a Shipping Label"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/labels/create-a-label","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}