Labels Api

Purchase Labels From Your Stack

Create carrier-generated labels for eligible orders with one authenticated POST. Use the same shipment contract as SyncShip Create Label.

Get API key Read API reference

Overview

The Labels API creates a shipment and returns tracking plus label artifacts when the selected carrier service is available on your account. Pair it with the Rates API to choose a service before purchase.

POST /api/v1/shipments
PDF and carrier-supported label formats
Void and reprint flows where supported
Works with order-based fulfillment workflows

Authentication

Authenticate every request with a Bearer token issued for your SyncShip developer account.

http

Authorization: Bearer YOUR_API_KEY

Endpoint

Send order and package details to create a label. Responses include shipment id, tracking number, and label metadata when generation succeeds.

POST/api/v1/shipments

bash

curl -X POST https://api.sync-ship.com/api/v1/shipments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "orderId": "ord_01HXYZ", "carrier": "usps", "serviceCode": "priority", "serviceName": "Priority Mail", "weightOz": 32, "length": 12, "width": 8, "height": 4, "packageType": "package", "labelSource": "carrier_generated"}'

Request

orderId is required. Carrier, service, weight, and dimensions should match a rate you already shopped when using carrier-generated labels.

Parameter	Type	Required	Description
orderId	string	Yes	SyncShip order id to fulfill.
carrier	string	No	Carrier code such as usps or ups.
serviceCode	string	No	Carrier service code selected from rates.
serviceName	string	No	Human-readable service name.
weightOz	number	No	Total package weight in ounces.
length	number	No	Package length in inches.
width	number	No	Package width in inches.
height	number	No	Package height in inches.
packageType	string	No	Packaging type when required by the carrier.
labelSource	string	No	Usually carrier_generated for purchased labels.

json

{
  "orderId": "ord_01HXYZ",
  "carrier": "usps",
  "serviceCode": "priority",
  "serviceName": "Priority Mail",
  "weightOz": 32,
  "length": 12,
  "width": 8,
  "height": 4,
  "packageType": "package",
  "labelSource": "carrier_generated"
}

Response

Successful responses return the created shipment, including tracking and label format details when available.

Example response

json

{
  "id": "shp_01HABC",
  "orderId": "ord_01HXYZ",
  "status": "label_created",
  "carrier": "usps",
  "serviceName": "Priority Mail",
  "trackingNumber": "9400XXXXXXXXXXXXXXX",
  "labelFormat": "PDF",
  "amount": 9.85,
  "currency": "USD"
}

Errors

Standard HTTP status codes are used. Treat 4xx as client corrections and retry 429 with backoff.

401Missing or invalid API key.
422Validation failed — check order id, service, or package details.
429Too many requests — retry with exponential backoff.

Next steps

After labels, subscribe to tracking events or shop rates before purchase.

Rates API Tracking API Webhooks

Bring Every Order Into One Queue

Start free