Purchase a shipping label
Purchases a shipping label and immediately returns tracking number and label URL.
Recommended workflow:
1. First call `POST /v1/rates` to get available rates
2. Select a rate and use its `rate_id` to purchase the label
Alternative workflow:
- Specify `carrier` and `service` directly (cheapest matching rate will be used)
The label cost is automatically deducted from your account balance.
Parameters
Request Body
rate_id
string
Rate ID from `POST /v1/rates` response (recommended).
If provided, carrier and service are derived from the rate.
from_address
object
Required
Sender address
to_address
object
Required
Recipient address
parcel
object
Required
Package dimensions and weight
carrier
string (USPS | FEDEX | UPS | DHL)
Carrier code. Required if `rate_id` not provided.
service
string
Service name (human-readable). Required if `rate_id` and `service_code` not provided.
Use either `service` OR `service_code`, not both.
service_code
string
Service code (machine-readable). Alternative to `service`.
Get this from the `service_code` field in `/v1/rates` response.
carrier_account_id
string
Your BYOCA carrier account ID (for negotiated rates)
label_format
string (pdf | png | zpl)
Label file format
label_size
string (4x6 | 4x8)
Label dimensions
reference
string
Your internal reference (e.g., order ID)
label_custom_fields
object
Custom fields to print on the shipping label. Support varies by carrier:
- USPS: Fields appear in content description
- EasyPost: Uses print_custom_1/2/3 fields (up to 35 chars each)
- ShipEngine: Uses label_messages reference1/2/3 (up to 35 chars each)
- Shippo: Stored in metadata for API reference
- Pitney Bowes: Uses references array with name/value pairs
options
object
Shipping options including insurance, signature, and hazmat
Returns
201
Label purchased successfully
400
Invalid request data
401
Authentication required
402
Insufficient funds
404
Rate not found
Related
Labels
POST/api/v1/labels