How to create a shipping label with an API

To create a shipping label with an API, you make two calls: first rate the shipment to pick a service, then buy that shipment, and the API returns a printable label file plus a tracking number. The label comes back as a PDF for laser or inkjet printers, or as a ZPL string for thermal label printers, and the tracking number is your handle for everything that follows. This guide walks through the full flow step by step, including printing formats, voids and refunds, and the errors you should expect to handle.

It is part of our hub on shipping APIs for developers. If you have not rated a shipment yet, read how real-time rates work first, since label creation usually starts from a rate.

The label creation flow in three steps

Nearly every label integration follows the same sequence:

1. Rate the shipment to get available services and prices.
2. Buy the chosen service, which purchases postage and generates the label.
3. Print the returned label file and hand off the tracking number.

The examples below are generic illustrative pseudo-REST to show the pattern, not the exact Expership contract. The real endpoints, field names, and label format options are in the Expership API reference at /developers.

Step 1: rate the shipment

Send origin, destination, weight, and dimensions to the rate endpoint and get back priced services. Accurate dimensions matter here because carriers bill on dimensional weight, and the price you buy at is the price you were quoted.

POST /rates
Authorization: Bearer YOUR_API_KEY

{
  "from": { "postal_code": "60601", "country": "US" },
  "to":   { "postal_code": "30301", "country": "US" },
  "parcel": { "weight_oz": 40, "length_in": 12, "width_in": 9, "height_in": 5 }
}

Step 2: buy the shipment and generate the label

Take the rate you want and buy it. Many APIs let you reference a rate id from step 1, or you can pass the full shipment again along with the chosen service. The response contains the label and tracking number.

POST /labels
Authorization: Bearer YOUR_API_KEY

{
  "rate_id": "rate_abc123",
  "label_format": "pdf"
}

{
  "tracking_number": "TRK123456789",
  "carrier": "CarrierA",
  "service": "Ground",
  "amount": 9.85,
  "label_url": "https://.../label_abc123.pdf",
  "label_format": "pdf"
}

Some APIs return the label as a URL to download, others as a base64-encoded blob inline. Check which one you get so you store or stream it correctly.

Step 3: print the label

How you print depends on your hardware:

For high-volume fulfillment, thermal printing with ZPL at 4x6 inches is the standard because it is fast and needs no ink.

Handling voids and refunds

Labels get bought by mistake, orders get cancelled, and boxes get remeasured. Most carriers allow a label to be voided within a window (often a set number of days) if it has not been used, and the postage is refunded. Wire up the void call early rather than treating it as an afterthought.

POST /labels/label_abc123/void
Authorization: Bearer YOUR_API_KEY

Refund timing and eligibility rules are set by the carrier, so surface the returned status to your team rather than assuming success. Confirm exact behavior in the docs at /developers.

Errors you should expect to handle

Label creation spends real money and touches carrier systems, so build for failure from day one:

• Invalid address. The most common failure. Validate destinations up front with an address validation API so you catch bad addresses before you try to buy.
• Rate expired. If too much time passes between rating and buying, the rate id may no longer be valid. Re-rate and retry.
• Insufficient funds or account issue. Postage accounts can run dry. Handle it gracefully and alert someone.
• Carrier timeout. Retry idempotently. Make sure a retry does not accidentally buy two labels; use an idempotency key if the API supports one.

After the label: tracking

The tracking number from the buy response is the thread you follow to delivery. Rather than polling constantly, subscribe to status updates with webhooks. See the shipping tracking API and webhooks explained for that flow.

Getting started with Expership

Expership offers a multi-carrier shipping API for creating labels across carriers from one integration, aimed at ecommerce sellers and consolidators shipping into the U.S. Explore the reference at /developers, see the full platform, or create an account to get sandbox keys and print a test label. For the broader picture, read what is a shipping API and multi-carrier shipping explained.

Frequently asked questions

How do I create a shipping label with an API?

Rate the shipment to choose a service, then call the buy or labels endpoint with that service. The API charges the postage and returns a printable label file plus a tracking number. Print the file and attach it to the box.

What format does the shipping label come in?

Usually a PDF for standard printers or a ZPL string for thermal label printers, and sometimes PNG for previews. High-volume warehouses generally use ZPL at 4x6 inches on thermal printers because it is fast and inkless.

Can I cancel or void a shipping label?

Yes, within the carrier's void window and if the label has not been scanned into the network. Call the void endpoint and the postage is typically refunded. Timing and eligibility are set by the carrier, so check the returned status.

Why did my label creation fail?

The most common reason is an invalid or undeliverable destination address. Others include an expired rate, an account funding issue, or a carrier timeout. Validate addresses first and build retry and idempotency handling for transient failures.

Do I get a tracking number when I create a label?

Yes. The buy response includes the tracking number for the shipment. Use it to subscribe to tracking updates, ideally via webhooks, so you know when the package moves and delivers.