Athenian USPS Shipping Integration

Developer starting point

This baseline documents the USPS integration architecture. It does not claim that a carrier request, rate, label, tracking update, or shipment has been exercised.

What Athenian USPS Integration does

1. Brings live USPS rates into WooCommerce checkout

Athenian USPS Integration connects directly to USPS APIs to request real-time rates during checkout. Merchants can:

• Surface live USPS services dynamically
• Restrict checkout to selected mail classes
• Choose commercial or retail pricing behavior
• Apply fixed and percentage-based handling adjustments
• Use a fallback flat rate if live USPS services are unavailable
• Keep USPS rate logic inside WooCommerce shipping zones and instance settings

This gives merchants carrier-backed pricing without abandoning WooCommerce's native shipping architecture.

2. Converts catalog data into shipment-ready package logic

The plugin builds shipment packages from WooCommerce product data, including:

• Weight
• Length, width, and height
• Quantity
• Store unit settings
• Fallback values when product data is incomplete

It supports multiple packaging strategies:

• Configured 3D box packing with merchant-defined box definitions
• Single aggregate package mode
• One-package-per-item mode
• Optional bundling of identical items into stacked groups before packing
• Parcel padding for dimensional and dunnage adjustments

This matters because USPS pricing accuracy depends on how items are actually grouped and packed, not just on line-item totals.

3. Supports practical USPS service control

The plugin is built around a clear USPS service set instead of generic carrier abstraction. It can expose and manage supported classes such as:

• USPS Ground Advantage
• Priority Mail
• Priority Mail Express
• First-Class Package Service
• Parcel Select
• Media Mail
• Library Mail
• Bound Printed Matter

That gives merchants a USPS-specific shipping layer rather than a vague one-size-fits-all carrier setup.

4. Connects checkout shipping selections to fulfillment actions

When a shopper selects a USPS rate, the plugin captures and persists:

• USPS mail class
• Service name
• Price type
• Active environment
• Package count
• Package summary
• Base shipping cost metadata

That data is written into WooCommerce order context so the shipping decision made at checkout can drive fulfillment and reporting later.

5. Generates USPS shipping labels from the order

After purchase, Athenian USPS Integration can generate USPS labels directly from WooCommerce order data. It:

• Builds shipment requests from order addresses and packed item data
• Requests USPS payment authorization and creates labels through USPS APIs
• Stores tracking numbers on the order
• Persists generated label PDFs to the WordPress uploads directory
• Supports admin-triggered label generation from the WooCommerce order screen

This reduces manual handoff between checkout and fulfillment while keeping shipment records attached to the transaction.

6. Fits Athenian operational shipping workflows

The plugin is not limited to a single checkout use case. It also integrates with Athenian shipment-management flows by:

• Registering USPS as a carrier in the Athenian shipment manager layer
• Exposing callbacks for label generation and previously generated label reads
• Supporting vendor-specific dropship label generation
• Participating in purchase-order label generation for routed fulfillment workflows

That makes it useful as both a storefront shipping method and an operational shipping service inside the Athenian ecosystem.

Ecosystem integration story

WooCommerce

Athenian USPS Integration is implemented as a native WooCommerce shipping method. It uses shipping zones, instance settings, order metadata, admin order tools, and logger support so merchants can manage USPS shipping inside the operating model WooCommerce already uses.

Athenian shipment workflows

The plugin extends beyond checkout rating by integrating with Athenian shipment-manager and dropship flows. That makes it viable for stores that need shipping execution to continue after checkout, not stop at rate display.

Order and fulfillment continuity

Because selected mail classes, package summaries, label files, and tracking numbers are persisted on the order, shipping context stays available to admins, fulfillment processes, and later operational tooling.