Developer Guide: Integrating Python Integration into Your E-commerce Stack
Build a more robust shipping workflow. A technical deep dive into implementing Python Integration for high-performance logistics.
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
| Task | Library | Why |
|---|---|---|
| HTTP client | httpx | Async support, connection pooling, HTTP/2 |
| Data validation | Pydantic | Type-safe models, JSON schema generation |
| Background jobs | Celery + Redis | Proven at scale for label generation queues |
| PDF handling | reportlab or pikepdf | Label PDF manipulation and merging |
| Testing | pytest + responses | Mock HTTP responses for carrier APIs |
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.
Ship smarter, not harder
Compare USPS, UPS & FedEx rates in seconds — no signup required.
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
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.
Compare USPS, UPS & FedEx rates instantly with atoship — no monthly fees.
Try FreeSave up to 89% on shipping labels
Compare USPS, UPS, and FedEx rates side by side. Get commercial pricing with no monthly fees, no contracts, and no markup.
