Skip to main content

Documentation Index

Fetch the complete documentation index at: https://packageretriever.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Quickstart: Python

From zero to a shipping label in 5 minutes.

​
Step 1: Get your API key

  1. Create a free account at packageretriever.com
  2. Open Apps & Tools → Unleashed tab
  3. Click Create Key → choose Sandbox → copy the key

​
Step 2: Install the SDK

pip install packageretriever

​
Step 3: Validate an address

from packageretriever import PackageRetriever

pr = PackageRetriever(api_key="pr_test_YOUR_KEY_HERE")

validated = pr.addresses.validate(
    name="Jane Smith",
    street1="417 Montgomery St",
    city="San Francisco",
    state="CA",
    zip="94104",
    country="US"
)

print(validated.valid)                       # True
print(validated.delivery_type)               # 'commercial'
print(validated.residential_surcharge_applies)  # False

​
Step 4: Get rates

rates = pr.rates.get(
    from_address={
        "name": "Warehouse",
        "street1": "417 Montgomery St",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94105",
        "country": "US"
    },
    to_address={
        "name": "Customer",
        "street1": "123 Main St",
        "city": "Austin",
        "state": "TX",
        "zip": "78701",
        "country": "US"
    },
    parcel={"weight_oz": 16, "length": 9, "width": 6, "height": 2}
)

# Sorted cheapest first
cheapest = rates.rates[0]
print(f"{cheapest.carrier} {cheapest.service}: ${cheapest.rate_cents / 100}")
# USPS Ground Advantage: $5.42

​
Step 5: Buy a label

label = pr.labels.create(rate_id=rates.rates[0].id)

print(label.tracking_number)  # 9999... (sandbox)
print(label.label_url)        # Sample PDF URL
print(label.rate_cents)       # 542

​
Step 6: You’re done

Next steps:

​
Full working example

import os
from packageretriever import PackageRetriever

pr = PackageRetriever(api_key=os.environ["PR_API_KEY"])

def ship_order(address: dict, weight_oz: int) -> dict:
    # 1. Get rates
    rates = pr.rates.get(
        from_address={
            "name": "My Store",
            "street1": "417 Montgomery St",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94105",
            "country": "US"
        },
        to_address=address,
        parcel={"weight_oz": weight_oz}
    )

    if not rates.rates:
        raise Exception("No rates available")

    # 2. Buy cheapest label
    label = pr.labels.create(rate_id=rates.rates[0].id)

    return {
        "tracking": label.tracking_number,
        "label_pdf": label.label_url,
        "cost_cents": label.rate_cents
    }