UPS Connector

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €24/mo; credential: we hold your UPS API key, negotiate volume discounts

Generated from docs/plan/paid/ups-connector/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid carrier plugin providing real-time UPS shipping rates and label generation, integrated into the carrier-integrations module.

The problem

Merchants using UPS need live rate quotes and label generation; without this, they resort to manual rate lookups or flat-rate shipping.

What it does

• Register UPS API credentials (account number, authentication)
• Query live rates for weight, destination, service level (ground, express, next-day, etc.)
• Generate shipping labels (return PDF and ZPL)
• Track shipments (query UPS by tracking number, receive webhook updates)
• Handle rate caching (24h cache to reduce API calls)
• Support multiple UPS accounts (primary + backup)
• Error handling: if UPS API unavailable, fall back to shipping-rules-engine
• Audit all rate queries, label generations, tracking lookups

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• UPS pickup scheduling — not included. Reason: requires carrier SLA negotiation.
• Customs form generation — not included. Reason: separate per-country compliance feature.
• UPS billing integration — we don’t reconcile UPS invoices. Reason: financial reconciliation outside scope.

Data model

Handled by carrier-integrations module; UPS plugin adds CarrierAccount entry with carrierId=‘ups’.

API

• POST /api/carriers/ups/accounts
• POST /api/carriers/ups/quote
• POST /api/carriers/ups/label

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Via carrier-integrations admin UI; UPS-specific: account number, auth method, preferred service level.

The seam — why this is paid

Core owns: shipping interface. Paid owns: UPS API key, credential management, rate caching, label storage, tracking integration.

Credential: UPS API key management, rate caching, label storage

Dependencies

• carrier-integrations (parent module)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Rate query with weight=2kg, destination=‘GR’, serviceLevel=‘ground’ returns rate within ±5% of UPS’s live rate
• Label generated and stored as artifact; format is valid PDF (magic bytes %PDF)
• Tracking webhook updates order status in real-time

Risks

Stale cache: UPS rates change, customer sees outdated rate; mitigation: cache TTL is transparent, merchant can lower TTL. API downtime: UPS API unavailable; mitigation: fallback to shipping-rules-engine.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.