Athenian UPS Shipping Integration

Developer starting point

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

What Athenian UPS Integration does

1. Brings live UPS rates into WooCommerce checkout

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

• Shop available UPS services dynamically
• Restrict rates to selected UPS services
• Apply handling fees and percentage-based adjustments
• Control whether residential or commercial delivery assumptions are automatic or fixed
• Keep UPS rate logic inside WooCommerce shipping zones and instance settings

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

2. Converts catalog data into shippable 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:

• 3D box packing using merchant-defined box definitions
• Single combined package mode
• One-package-per-item mode

This matters because shipping accuracy depends on package construction, not just product totals.

3. Adds resilience when UPS rejects a shipment assumption

UPS rating can fail when package type or destination assumptions do not match what the API expects. Athenian UPS Integration is built to recover from those situations by:

• Retrying alternate UPS package type codes when enabled
• Falling back from service-shopping requests to per-service rating requests
• Re-evaluating residential versus commercial assumptions when needed
• Logging request and response summaries for debugging when merchants enable diagnostics

That resilience helps stores keep shipping options visible instead of silently failing during checkout.

4. Connects checkout shipping selections to fulfillment actions

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

• UPS service code
• UPS package type code
• Packed shipment metadata
• Environment context used for the request

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

5. Generates UPS shipping labels from the order

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

• Builds shipment requests from order addresses and packed item data
• Creates UPS shipments through the UPS shipping API
• Stores tracking numbers and tracking URLs on the order
• Persists generated label PDFs to the WordPress uploads directory
• Supports admin-triggered label generation from WooCommerce order actions

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 order-screen action. It also integrates with Athenian shipment-management flows by:

• Registering UPS as a carrier in the Athenian shipment manager layer
• Exposing callbacks for label generation and previously generated label reads
• Supporting packed meta handoff for downstream shipping workflows
• Participating in purchase-order label generation where vendor or fulfillment routing requires it

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

Ecosystem integration story

WooCommerce

Athenian UPS Integration is implemented as a native WooCommerce shipping method. It uses shipping zones, instance settings, order actions, shipping-item metadata, logger support, and checkout hooks so merchants can manage UPS shipping inside the operating model WooCommerce already uses.

Athenian shipment workflows

The plugin extends beyond checkout rating by integrating with Athenian shipment-manager style flows and purchase-order label hooks. 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 service codes, package codes, package payloads, labels, and tracking identifiers are persisted on the order, shipping context stays available to admins, fulfillment processes, and later operational tooling.