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.
weight (number, required): Package weight
length (number, optional): Package length
width (number, optional): Package width
height (number, optional): Package height
weight_unit (string, optional, default
dimension_unit (string, optional, default
Imperial example:
Metric example:
weight (number, required): Package weight
length (number, optional): Package length
width (number, optional): Package width
height (number, optional): Package height
weight_unit (string, optional, default
oz): oz | lb | g | kgdimension_unit (string, optional, default
in): in | cmImperial example:
{ "weight": 16, "length": 10, "width": 8, "height": 4, "weight_unit": "oz", "dimension_unit": "in" }Metric example:
{ "weight": 0.5, "length": 25, "width": 20, "height": 10, "weight_unit": "kg", "dimension_unit": "cm" }
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
billing
object
Billing party for BYOCA carrier accounts (e.g. your own UPS account). Requires
payer (required):
accountNumber: Required for
countryCode: 2-letter ISO. Required for
postalCode: Required for
carrier_account_id to be set.payer (required):
shipper (default — your BYOCA account is billed) | recipient | third_partyaccountNumber: Required for
recipient and third_partycountryCode: 2-letter ISO. Required for
third_partypostalCode: Required for
third_party
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