Laravel Ups Api Laravel Package

Product Decisions This Supports

• Build vs. buy for shipping/logistics integration. Wrapping the UPS API ourselves means owning auth (OAuth), rate/label/tracking payloads, error mapping, and retry logic. This package is a thin, maintained adapter — the buy-side default unless we have unusual UPS contract requirements (negotiated rates, custom label formats, multi-account routing) that the wrapper won't expose.
• Roadmap sequencing against our framework upgrade. v5.0.0 targets Laravel 13 and PHP 8.5, so adopting it locks shipping work to our platform upgrade timeline. Conversely, if we're staying on Laravel 11/12 for the next two quarters, this major is not adoptable yet — that's a scheduling decision, not a technical one.
• Shipping as a differentiating vs. table-stakes capability. Rates at checkout, label generation, and tracking are table stakes; the real product question is whether we invest in our own fulfillment orchestration layer (multi-carrier abstraction) on top of this, or stop at single-carrier. If multi-carrier is on the 12-month roadmap, treat this package as one adapter behind our own interface rather than calling facades directly from application code.
• Where to place integration risk on the roadmap. The PHPStan level-10 and @mixin facade typing work reduces the cost of our integration work (fewer mixed types, real return types in PhpStorm, static analysis catches misuse in CI before deploy). This shifts effort from "debugging runtime payload errors" toward feature work — a modest but real velocity argument for prioritizing the integration.
• Upgrade-window planning. A major version bump (v4.1.0 → v5.0.0) is the moment to decide pin vs. upgrade. Recommend pinning to v4.x if we're not on Laravel 13, and scheduling the v5 adoption alongside the framework upgrade rather than as a standalone ticket.

When to Consider This Package

Adopt when:

• We're building on Laravel and need UPS rates, labels, or tracking without maintaining our own API client.
• Our stack is (or is about to be) Laravel 13 / PHP 8.5 — v5.0.0 is aligned to that and to current UPS API expectations.
• Engineering uses PhpStorm or runs PHPStan/PHPStan-adjacent CI. The @mixin facade annotations and level-10 analysis mean our static analysis actually understands facade calls instead of degrading to mixed — genuine day-to-day DX and a lower defect rate on integration code.
• We want a single-carrier integration shipped fast, with a facade-based API that keeps the integration surface small.

Look elsewhere (or wrap it) when:

• We need multi-carrier abstraction, rate shopping across carriers, or our own domain model for shipments — this is a UPS adapter, not an orchestration layer.
• Our UPS account uses negotiated contracts, custom label stock, or EDI/manifest flows beyond what the wrapper surfaces — verify coverage before committing.
• We're pinned to Laravel ≤12 / PHP ≤8.4. v5.0.0 is a major and will not install; stay on v4.1.0 and plan the jump.
• We need a vendor SLA or commercial support contract. Open-source, single-maintainer (@ptondereau) — acceptable for most teams, but call it out as a bus-factor risk in the architecture review.
• UPS API behavior changes faster than the release cadence. Mitigate with an internal adapter boundary so a stale wrapper doesn't block us.

How to Pitch It (Stakeholders)

To executives (one paragraph): We need UPS shipping in the product — rates at checkout, labels, tracking. Rather than build and maintain that connection ourselves, we can adopt a small, actively maintained Laravel package that handles it. The new v5.0.0 release keeps it current with our target platform (Laravel 13 / PHP 8.5) and adds strict static analysis, which lowers the chance of shipping broken shipping code to production. Cost is effectively zero in licensing; the real cost is a scheduled upgrade tied to our Laravel 13 migration. Recommendation: pin to v4.x today, adopt v5 as part of the framework upgrade, and put our own thin interface in front of it so we're not locked to one carrier.

To engineering: v5.0.0 is a major — Laravel 13 and PHP 8.5 support, so it's a coordinated upgrade, not a drop-in. The wins are real: PHPStan at level 10 in the package's own CI, and facades now declare @mixin to their Ups\* root classes, so facade calls resolve to concrete return types instead of mixed in PHPStan and PhpStorm. That means our integration code gets real autocomplete and our CI catches misuse before runtime. Action items: (1) confirm the exact supported-version matrix before we commit — "adds Laravel 13 support" may or may not mean older versions were dropped, and that determines whether this is a hard blocker; (2) wrap facade calls behind our own ShippingClient interface so multi-carrier stays possible and a package stall doesn't become our outage; (3) add PHPStan to our own CI at the same time, otherwise we don't capture the typing benefit.