PDF Label
Generate printable shipping labels in PDF format. This endpoint creates professional shipping labels with barcodes, addresses, and all necessary shipping information.
/API/v2/pdf_label.php
Cost: Depend on vendors price set at your profile
Rate Limit: 60 requests per minute
Format: PDF (base64 encoded)
PDF Label Features
- Professional shipping label layout
- Automatically generated tracking barcode
- Sender and recipient address formatting
- Service and carrier information
- Ready for printing on standard label printers
Authentication
This endpoint requires Bearer token authentication. Include your API key in the Authorization header.
curl -X POST https://developers.labelscheap.com/API/v2/pdf_label.php \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{
"shipping_service": "priority",
"carrier": "USPS",
"vendor": "rollo",
"length": 10,
"width": 8,
"height": 6,
"weight": 1.5,
"from_name": "John Doe",
"from_company": "My Company",
"from_address": "123 Main St",
"from_city": "New York",
"from_state": "NY",
"from_postcode": "10001",
"to_name": "Jane Smith",
"to_address": "456 Oak Ave",
"to_city": "Los Angeles",
"to_state": "CA",
"to_postcode": "90210"
}'
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://developers.labelscheap.com/API/v2/pdf_label.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer YOUR_API_KEY',
'X-Requested-With: XMLHttpRequest'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'shipping_service' => 'priority',
'carrier' => 'USPS',
'vendor' => 'rollo',
'length' => 10,
'width' => 8,
'height' => 6,
'weight' => 1.5,
'from_name' => 'John Doe',
'from_company' => 'My Company',
'from_address' => '123 Main St',
'from_city' => 'New York',
'from_state' => 'NY',
'from_postcode' => '10001',
'to_name' => 'Jane Smith',
'to_address' => '456 Oak Ave',
'to_city' => 'Los Angeles',
'to_state' => 'CA',
'to_postcode' => '90210'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
import requests
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY',
'X-Requested-With': 'XMLHttpRequest'
}
data = {
'shipping_service': 'priority',
'carrier': 'USPS',
'vendor': 'rollo',
'length': 10,
'width': 8,
'height': 6,
'weight': 1.5,
'from_name': 'John Doe',
'from_company': 'My Company',
'from_address': '123 Main St',
'from_city': 'New York',
'from_state': 'NY',
'from_postcode': '10001',
'to_name': 'Jane Smith',
'to_address': '456 Oak Ave',
'to_city': 'Los Angeles',
'to_state': 'CA',
'to_postcode': '90210'
}
response = requests.post(
'https://developers.labelscheap.com/API/v2/pdf_label.php',
headers=headers,
json=data
)
data = response.json()
fetch('https://developers.labelscheap.com/API/v2/pdf_label.php', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY',
'X-Requested-With': 'XMLHttpRequest'
},
body: JSON.stringify({
shipping_service: 'priority',
carrier: 'USPS',
vendor: 'rollo',
length: 10,
width: 8,
height: 6,
weight: 1.5,
from_name: 'John Doe',
from_company: 'My Company',
from_address: '123 Main St',
from_city: 'New York',
from_state: 'NY',
from_postcode: '10001',
to_name: 'Jane Smith',
to_address: '456 Oak Ave',
to_city: 'Los Angeles',
to_state: 'CA',
to_postcode: '90210'
})
})
.then(response => response.json())
.then(data => console.log(data));
Request
This endpoint accepts a POST request with shipping label parameters in the JSON body.
Headers
| Header | Required | Description |
|---|---|---|
Content-Type |
Yes | Must be application/json |
Authorization |
Yes | Bearer token with your API key |
X-Requested-With |
Yes | Must be XMLHttpRequest |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
shipping_service |
string | Yes | Shipping service slug (priority, ground, etc.) |
carrier |
string | Yes | Shipping carrier name (USPS, UPS, etc.) |
vendor |
string | Yes | Label printer vendor (rollo, pitney_bowes, etc.) |
length |
number | Yes | Package length in inches (0.1-1000) |
width |
number | Yes | Package width in inches (0.1-1000) |
height |
number | Yes | Package height in inches (0.1-1000) |
weight |
number | Yes | Package weight in pounds (0.1-1000) |
from_name |
string | Yes | Sender's full name (1-100 characters) |
from_address |
string | Yes | Sender's street address (5-200 characters) |
from_city |
string | Yes | Sender's city (1-100 characters) |
from_state |
string | Yes | Sender's state (2 characters) |
from_postcode |
string | Yes | Sender's ZIP code (5 digits) |
to_name |
string | Yes | Recipient's full name (1-100 characters) |
to_address |
string | Yes | Recipient's street address (5-200 characters) |
to_city |
string | Yes | Recipient's city (1-100 characters) |
to_state |
string | Yes | Recipient's state (2 characters) |
to_postcode |
string | Yes | Recipient's ZIP code (5 digits) |
from_company |
string | No | Sender's company name |
from_phone |
string | No | Sender's phone number |
from_address_2 |
string | No | Sender's address line 2 (apartment, suite, etc.) |
to_company |
string | No | Recipient's company name |
to_phone |
string | No | Recipient's phone number |
to_address_2 |
string | No | Recipient's address line 2 (apartment, suite, etc.) |
notes |
string | No | Additional notes for the shipment |
Field Name Variations
The API accepts the following field name variations:
servicecan be used instead ofshipping_service
Example Request Body
{
"shipping_service": "priority",
"carrier": "USPS",
"vendor": "rollo",
"length": 10,
"width": 8,
"height": 6,
"weight": 1.5,
"from_name": "John Doe",
"from_company": "My Company",
"from_address": "123 Main St",
"from_address_2": "Suite 100",
"from_city": "New York",
"from_state": "NY",
"from_postcode": "10001",
"from_phone": "555-123-4567",
"to_name": "Jane Smith",
"to_company": "Her Company",
"to_address": "456 Oak Ave",
"to_address_2": "Apt 2B",
"to_city": "Los Angeles",
"to_state": "CA",
"to_postcode": "90210",
"to_phone": "555-987-6543",
"notes": "Handle with care"
}
Response
The response includes the generated PDF label as a base64-encoded string and metadata about the label.
Success Response
{
"STATUS": "success",
"MESSAGE": "Label generated successfully",
"CODE": "200",
"DATA": {
"tracking_number": "9205521706900192070306",
"download_pdf": "data:application/pdf;base64,JVBERi0xLjQKMyAwIG9iago8PC9UeXBlIC==",
"shipment_id": 1337335,
"amount_deducted": "0.005",
"carrier": "USPS",
"vendor": "Rollo"
},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Response Fields
| Field | Type | Description |
|---|---|---|
STATUS |
string | Always "success" for successful requests |
MESSAGE |
string | Human-readable success message |
CODE |
string | HTTP status code as string |
DATA.tracking_number |
string | Generated tracking number for the shipment |
DATA.download_pdf |
string | Base64-encoded PDF data with data URL prefix |
DATA.shipment_id |
integer | Unique shipment identifier |
DATA.amount_deducted |
string | Amount deducted from account balance |
DATA.carrier |
string | Shipping carrier used |
DATA.vendor |
string | Vendor used for label generation |
TIMESTAMP |
string | ISO 8601 timestamp of the response |
Code Examples
Here are complete examples for different programming languages:
<?php
class LabelsCheapAPI {
private $apiKey;
private $baseUrl = 'https://developers.labelscheap.com/API/v2/';
public function __construct($apiKey) {
$this->apiKey = $apiKey;
}
public function generatePDFLabel($fromAddress, $toAddress, $package, $service = 'priority', $carrier = 'usps') {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $this->baseUrl . 'pdf_label.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $this->apiKey,
'X-Requested-With: XMLHttpRequest'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'from_address' => $fromAddress,
'to_address' => $toAddress,
'package' => $package,
'service' => $service,
'carrier' => $carrier
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
return json_decode($response, true);
}
public function savePDFLabel($pdfData, $filename) {
// Remove data:application/pdf;base64, prefix
$base64Data = str_replace('data:application/pdf;base64,', '', $pdfData);
$pdfContent = base64_decode($base64Data);
return file_put_contents($filename, $pdfContent);
}
}
// Usage
try {
$api = new LabelsCheapAPI('YOUR_API_KEY');
$fromAddress = [
'name' => 'John Doe',
'company' => 'My Company',
'address1' => '123 Main St',
'city' => 'New York',
'state' => 'NY',
'zip' => '10001',
'country' => 'US'
];
$toAddress = [
'name' => 'Jane Smith',
'address1' => '456 Oak Ave',
'city' => 'Los Angeles',
'state' => 'CA',
'zip' => '90210',
'country' => 'US'
];
$package = [
'weight' => 1.5,
'length' => 10,
'width' => 8,
'height' => 6
];
$result = $api->generatePDFLabel($fromAddress, $toAddress, $package, 'priority', 'usps');
if ($result['STATUS'] === 'success') {
echo "Label generated successfully!\n";
echo "Tracking Number: " . $result['DATA']['tracking_number'] . "\n";
echo "Shipment ID: " . $result['DATA']['shipment_id'] . "\n";
echo "Carrier: " . $result['DATA']['carrier'] . "\n";
echo "Vendor: " . $result['DATA']['vendor'] . "\n";
echo "Amount deducted: $" . $result['DATA']['amount_deducted'] . "\n";
// Save the PDF label
$api->savePDFLabel($result['DATA']['download_pdf'], 'shipping_label.pdf');
echo "Label saved as shipping_label.pdf\n";
} else {
echo "Error: " . $result['MESSAGE'] . "\n";
}
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}
?>
import requests
import base64
import json
class LabelsCheapAPI:
def __init__(self, api_key):
self.api_key = api_key
self.base_url = 'https://developers.labelscheap.com/API/v2/'
self.headers = {
'Content-Type': 'application/json',
'Authorization': f'Bearer {api_key}',
'X-Requested-With': 'XMLHttpRequest'
}
def generate_pdf_label(self, from_address, to_address, package, service='priority', carrier='usps'):
try:
response = requests.post(
f'{self.base_url}pdf_label.php',
headers=self.headers,
json={
'shipping_service': service,
'carrier': carrier,
'vendor': 'rollo',
'length': package['length'],
'width': package['width'],
'height': package['height'],
'weight': package['weight'],
'from_name': from_address['name'],
'from_company': from_address['company'],
'from_address': from_address['address1'],
'from_city': from_address['city'],
'from_state': from_address['state'],
'from_postcode': from_address['zip'],
'to_name': to_address['name'],
'to_address': to_address['address1'],
'to_city': to_address['city'],
'to_state': to_address['state'],
'to_postcode': to_address['zip']
},
timeout=30
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
raise Exception(f'Request failed: {str(e)}')
except json.JSONDecodeError as e:
raise Exception(f'Invalid JSON response: {str(e)}')
def save_pdf_label(self, pdf_data, filename):
# Remove data:application/pdf;base64, prefix
base64_data = pdf_data.replace('data:application/pdf;base64,', '')
pdf_content = base64.b64decode(base64_data)
with open(filename, 'wb') as f:
f.write(pdf_content)
# Usage
try:
api = LabelsCheapAPI('YOUR_API_KEY')
from_address = {
'name': 'John Doe',
'company': 'My Company',
'address1': '123 Main St',
'city': 'New York',
'state': 'NY',
'zip': '10001',
'country': 'US'
}
to_address = {
'name': 'Jane Smith',
'address1': '456 Oak Ave',
'city': 'Los Angeles',
'state': 'CA',
'zip': '90210',
'country': 'US'
}
package = {
'weight': 1.5,
'length': 10,
'width': 8,
'height': 6
}
result = api.generate_pdf_label(from_address, to_address, package, 'priority', 'usps')
if result['STATUS'] == 'success':
print("Label generated successfully!")
print(f"Tracking Number: {result['DATA']['tracking_number']}")
print(f"Shipment ID: {result['DATA']['shipment_id']}")
print(f"Carrier: {result['DATA']['carrier']}")
print(f"Vendor: {result['DATA']['vendor']}")
print(f"Amount deducted: ${result['DATA']['amount_deducted']}")
# Save the PDF label
api.save_pdf_label(result['DATA']['download_pdf'], 'shipping_label.pdf')
print("Label saved as shipping_label.pdf")
else:
print(f"Error: {result['MESSAGE']}")
except Exception as e:
print(f"Error: {str(e)}")
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using System.IO;
using Newtonsoft.Json;
public class LabelsCheapAPI
{
private readonly string _apiKey;
private readonly string _baseUrl = "https://developers.labelscheap.com/API/v2/";
private readonly HttpClient _httpClient;
public LabelsCheapAPI(string apiKey)
{
_apiKey = apiKey;
_httpClient = new HttpClient();
_httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
_httpClient.DefaultRequestHeaders.Add("X-Requested-With", "XMLHttpRequest");
}
public async Task<dynamic> GeneratePDFLabelAsync(dynamic fromAddress, dynamic toAddress, dynamic package, string service = "priority", string carrier = "usps")
{
try
{
var requestData = new {
shipping_service = service,
carrier = carrier,
vendor = "rollo",
length = package.length,
width = package.width,
height = package.height,
weight = package.weight,
from_name = fromAddress.name,
from_company = fromAddress.company,
from_address = fromAddress.address1,
from_city = fromAddress.city,
from_state = fromAddress.state,
from_postcode = fromAddress.zip,
to_name = toAddress.name,
to_address = toAddress.address1,
to_city = toAddress.city,
to_state = toAddress.state,
to_postcode = toAddress.zip
};
var json = JsonConvert.SerializeObject(requestData);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await _httpClient.PostAsync($"{_baseUrl}pdf_label.php", content);
response.EnsureSuccessStatusCode();
var responseContent = await response.Content.ReadAsStringAsync();
return JsonConvert.DeserializeObject(responseContent);
}
catch (HttpRequestException ex)
{
throw new Exception($"Request failed: {ex.Message}");
}
catch (JsonException ex)
{
throw new Exception($"Invalid JSON response: {ex.Message}");
}
}
public void SavePDFLabel(string pdfData, string filename)
{
// Remove data:application/pdf;base64, prefix
var base64Data = pdfData.Replace("data:application/pdf;base64,", "");
var pdfContent = Convert.FromBase64String(base64Data);
File.WriteAllBytes(filename, pdfContent);
}
}
// Usage
public class Program
{
public static async Task Main()
{
try
{
var api = new LabelsCheapAPI("YOUR_API_KEY");
var fromAddress = new {
name = "John Doe",
company = "My Company",
address1 = "123 Main St",
city = "New York",
state = "NY",
zip = "10001",
country = "US"
};
var toAddress = new {
name = "Jane Smith",
address1 = "456 Oak Ave",
city = "Los Angeles",
state = "CA",
zip = "90210",
country = "US"
};
var package = new {
weight = 1.5,
length = 10,
width = 8,
height = 6
};
var result = await api.GeneratePDFLabelAsync(fromAddress, toAddress, package, "priority", "usps");
if (result.STATUS == "success")
{
Console.WriteLine("Label generated successfully!");
Console.WriteLine($"Tracking Number: {result.DATA.tracking_number}");
Console.WriteLine($"Shipment ID: {result.DATA.shipment_id}");
Console.WriteLine($"Carrier: {result.DATA.carrier}");
Console.WriteLine($"Vendor: {result.DATA.vendor}");
Console.WriteLine($"Amount deducted: ${result.DATA.amount_deducted}");
// Save the PDF label
api.SavePDFLabel(result.DATA.download_pdf.ToString(), "shipping_label.pdf");
Console.WriteLine("Label saved as shipping_label.pdf");
}
else
{
Console.WriteLine($"Error: {result.MESSAGE}");
}
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
}
}
class LabelsCheapAPI {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseUrl = 'https://developers.labelscheap.com/API/v2/';
this.headers = {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`,
'X-Requested-With': 'XMLHttpRequest'
};
}
async generatePDFLabel(fromAddress, toAddress, package, service = 'priority', carrier = 'usps') {
try {
const response = await fetch(`${this.baseUrl}pdf_label.php`, {
method: 'POST',
headers: this.headers,
body: JSON.stringify({
shipping_service: service,
carrier: carrier,
vendor: 'rollo',
length: package.length,
width: package.width,
height: package.height,
weight: package.weight,
from_name: fromAddress.name,
from_company: fromAddress.company,
from_address: fromAddress.address1,
from_city: fromAddress.city,
from_state: fromAddress.state,
from_postcode: fromAddress.zip,
to_name: toAddress.name,
to_address: toAddress.address1,
to_city: toAddress.city,
to_state: toAddress.state,
to_postcode: toAddress.zip
})
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return await response.json();
} catch (error) {
throw new Error(`Request failed: ${error.message}`);
}
}
savePDFLabel(pdfData, filename) {
// Remove data:application/pdf;base64, prefix
const base64Data = pdfData.replace('data:application/pdf;base64,', '');
// Convert base64 to blob and download
const byteCharacters = atob(base64Data);
const byteNumbers = new Array(byteCharacters.length);
for (let i = 0; i < byteCharacters.length; i++) {
byteNumbers[i] = byteCharacters.charCodeAt(i);
}
const byteArray = new Uint8Array(byteNumbers);
const blob = new Blob([byteArray], { type: 'application/pdf' });
// Create download link
const url = window.URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = filename;
document.body.appendChild(a);
a.click();
document.body.removeChild(a);
window.URL.revokeObjectURL(url);
}
}
// Usage
async function main() {
try {
const api = new LabelsCheapAPI('YOUR_API_KEY');
const fromAddress = {
name: 'John Doe',
company: 'My Company',
address1: '123 Main St',
city: 'New York',
state: 'NY',
zip: '10001',
country: 'US'
};
const toAddress = {
name: 'Jane Smith',
address1: '456 Oak Ave',
city: 'Los Angeles',
state: 'CA',
zip: '90210',
country: 'US'
};
const package = {
weight: 1.5,
length: 10,
width: 8,
height: 6
};
const result = await api.generatePDFLabel(fromAddress, toAddress, package, 'priority', 'usps');
if (result.STATUS === 'success') {
console.log('Label generated successfully!');
console.log(`Tracking Number: ${result.DATA.tracking_number}`);
console.log(`Shipment ID: ${result.DATA.shipment_id}`);
console.log(`Carrier: ${result.DATA.carrier}`);
console.log(`Vendor: ${result.DATA.vendor}`);
console.log(`Amount deducted: $${result.DATA.amount_deducted}`);
// Save the PDF label
api.savePDFLabel(result.DATA.download_pdf, 'shipping_label.pdf');
} else {
console.log(`Error: ${result.MESSAGE}`);
}
} catch (error) {
console.error(`Error: ${error.message}`);
}
}
main();
Request Tester
Test the PDF label generation endpoint with your API key:
Common Error Responses
Here are the most common error responses you might encounter:
Invalid Address (422)
{
"STATUS": "error",
"MESSAGE": "Invalid address format",
"CODE": "2018",
"HTTP_STATUS": 422,
"DATA": {},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Invalid Package Dimensions (422)
{
"STATUS": "error",
"MESSAGE": "Invalid package dimensions",
"CODE": "2016",
"HTTP_STATUS": 422,
"DATA": {},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Insufficient Balance (402)
{
"STATUS": "error",
"MESSAGE": "Insufficient balance for this operation",
"CODE": "3001",
"HTTP_STATUS": 402,
"DATA": {},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Label Service Unavailable (503)
{
"STATUS": "error",
"MESSAGE": "Label generation service is unavailable",
"CODE": "5016",
"HTTP_STATUS": 503,
"DATA": {},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Error Handling Best Practices
- Validate all address fields before sending requests
- Check package dimensions and weight limits
- Handle rate limiting by implementing exponential backoff
- Implement retry logic for transient errors (5xx status codes)
- Check account balance before making label generation requests
- Display user-friendly error messages based on the error code
- Log error details for debugging and monitoring