Python Shipping Integration: From requests to Production

Python is the second most popular language for shipping integrations (after Node.js). Whether you're building a Django e-commerce backend or a Flask microservice for label generation, here's the practical guide.

Library Choices

Project Structure

Organize your shipping code as a Python package with clear boundaries:

• shipping/carriers/ — one module per carrier (usps.py, fedex.py, ups.py)
• shipping/models/ — Pydantic models for shipments, rates, labels
• shipping/services/ — business logic (rate_shopping.py, label_service.py)
• shipping/adapters/ — e-commerce platform adapters (shopify.py, amazon.py)

Pydantic Models for Shipping

Define your data structures with Pydantic for automatic validation:

Create an Address model with fields like name (str), street1 (str), street2 (optional str), city (str), state (str, 2-char max), zip_code (str matching 5 or 9 digit pattern), and country (str defaulting to "US").

Create a Shipment model referencing the Address model with ship_from, ship_to, and a list of Package objects (each with weight_oz, length, width, height).

Pydantic catches data issues at the boundary — before they cause cryptic carrier API errors.

Async Carrier Calls with httpx

For rate shopping across multiple carriers, async is essential. Use httpx.AsyncClient to make parallel requests to USPS, FedEx, and UPS simultaneously with asyncio.gather. Flatten the results and sort by price.

This runs all three carrier API calls concurrently instead of sequentially — cutting response time from 3-5 seconds to 1-2 seconds.

Celery for Background Label Generation

Label generation can take 2-10 seconds per carrier API call. Don't make users wait. Push to a Celery queue and notify them when the label is ready.

Define a Celery task that calls the carrier API, stores the label PDF in S3/storage, and sends a WebSocket notification to the user. Use autoretry_for with ConnectionError and set max_retries to 3 with exponential backoff.

Error Handling

Carrier APIs return errors in wildly different formats. Create a unified exception hierarchy:

• ShippingError (base)
• AddressError — validation failed
• RateError — no rates available
• LabelError — label generation failed
• AuthError — credentials expired
• CarrierTimeoutError — carrier API didn't respond

Map each carrier's specific error codes to these categories. Your application code catches ShippingError subtypes and doesn't need to know which carrier was involved.

Testing with Recorded Responses

Use the responses library (or respx for async) to record and replay carrier API responses. Record once with real API calls, save the JSON fixtures, and replay in CI. This prevents flaky tests that depend on carrier API availability.

Start building with Atoship's Python SDK →