PDF Label

Generate printable shipping labels in PDF format. This endpoint creates professional shipping labels with barcodes, addresses, and all necessary shipping information.

POST /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:

  • service can be used instead of shipping_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