# Quickstart: Print a label by API
URL: https://support.starshipit.com/articles/14700000001015-quickstart-print-a-label-by-api
Canonical: https://support.starshipit.com/articles/14700000001015-quickstart-print-a-label-by-api
Markdown: https://support.starshipit.com/articles/14700000001015-quickstart-print-a-label-by-api.md
Updated: 2026-06-18

> For the complete documentation index, see [llms.txt](https://support.starshipit.com/llms.txt).

> Generate a label through the API and confirm the label response.

Use this quickstart to call `POST /api/orders/shipment` for an order and confirm Starshipit returns tracking and label data.

Use the [Print Label endpoint reference](/developers/api-reference/starshipit#endpoint-shipments-post-api-orders-shipment-print-label) when you need the full request and response model.

## Before you begin

- Create or identify a test order in Starshipit.
- Confirm the order has a valid destination address and package data.
- Confirm the order has a carrier. An order can get a carrier from Starshipit rules, the account's default courier setting, or the `carrier` and `carrier_service_code` values you send in the request.
- Decide where your integration will store the returned label and tracking number.
- Set up [Plain Label](/articles/couriers/plain-label/how-to-use-plain-labels) if you want to test label generation without using a real carrier.

To print an order, Starshipit needs to know which carrier and service should be used. You can let rules assign this when the order is created, use your default courier setting, or send the carrier details in the label request. Plain Label is useful during testing when you want to see the label generation flow without booking a shipment with a live courier.

## Request example

Use the `order_id` returned from the import quickstart, or use a known test order number. Replace the carrier and service values with the carrier you want Starshipit to use. If you are testing with Plain Label, use the values from your Plain Label setup.

```bash
curl --request POST \
  --url https://api.starshipit.com/api/orders/shipment \
  --header "StarShipIT-Api-Key: YOUR_API_KEY" \
  --header "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "order_number": "API-TEST-1001",
    "carrier": "YOUR_CARRIER",
    "carrier_service_code": "YOUR_CARRIER_SERVICE",
    "packages": [
      {
        "weight": 0.5,
        "height": 0.1,
        "width": 0.1,
        "length": 0.1
      }
    ],
    "reprint": false
  }'
```

## Send the label request

1. Send the request for one test order.
2. Confirm the response includes `"success": true`.
3. Store the returned `tracking_numbers`.
4. Save the `labels` value in the system that will print or display the label.

The `labels` field is returned as a base64 string. Decode the base64 value into the file type returned by your carrier label response before you pass it to a printer or document store.

## Verify the label

Confirm:

- The label belongs to the expected order.
- The tracking number is stored against the source order.
- The carrier and service match the request or Starshipit rule result.
- The shipment is visible in Starshipit.
- Your integration does not create a second label if the same job is retried.

## Handle failures

| Failure | What to do |
| --- | --- |
| Address validation error | Correct the order address, then retry once the data has changed. |
| Carrier service unavailable | Confirm the courier account, destination, and service code. |
| Missing package details | Add weight and dimensions before printing. |
| Duplicate print risk | Check order shipment status before calling the endpoint again. |

## Next steps

- [Use webhooks and tracking updates](/articles/developer-center/starshipit-api/use-webhooks-and-tracking-updates)
- [How to use plain labels](/articles/couriers/plain-label/how-to-use-plain-labels)
- [Troubleshoot API integrations](/articles/developer-center/getting-started/troubleshooting-api-integrations)
- [Orders API reference](/developers/api-reference/starshipit#orders)