Product Decisions This Supports
- Market entry / expansion into Ukraine: Nova Poshta is the de facto national carrier for Ukrainian e-commerce (parcel lockers, branch pickup, courier). Any checkout targeting Ukrainian buyers needs a delivery-method integration; this package is a candidate building block for that decision.
- Checkout & delivery-method roadmap: Enables features like city/branch search, warehouse selection at checkout, shipping cost estimation, and delivery-type choice (branch vs. courier vs. parcel locker).
- Post-purchase roadmap: Order tracking, express waybill (ТТН) generation, label printing, and delivery status updates to customers.
- Payment/delivery bundling: Cash-on-delivery ("nalozhenyi platizh") and returns/refusals are core to Ukrainian commerce; an API client is a prerequisite for those flows.
- Build vs. buy: MIT-licensed, free PHP client for API v2 — a candidate "buy" (or rather "adopt") vs. an estimated 2–4 engineer-weeks to build and test a first-party client from scratch for the same endpoints.
- Pilot scoping: Useful as a low-cost spike to validate API coverage (which methods exist, what payloads look like) before committing roadmap capacity to a full integration.
When to Consider This Package
Consider it when:
- Ukraine is a confirmed or actively validated target market and Nova Poshta is on the carrier shortlist.
- Your stack is PHP/Laravel and you can vendor or wrap the package behind your own
ShippingProvider interface rather than calling it directly from domain code.
- You need a fast proof-of-concept to confirm API v2 coverage against a sandbox before funding a full integration.
- You are comfortable owning the code: with 1 star, 0 dependents, and a single release stream, this is effectively an unsupported library — treat it as a reference implementation, not a dependency of record.
- Your volume is modest at launch and you can add caching of the city/branch directory, retries, and rate limiting yourself.
Look elsewhere (or build in-house) when:
- You need Laravel-native ergonomics (service provider, publishable config, facades, queued jobs, HTTP client integration). If the package is a plain PHP client, you will write that glue anyway — decide if that's cheaper than an existing Laravel-specific package.
- You need endpoints or behaviors beyond what's implemented (newer API versions, webhooks/callbacks, bulk waybill creation, returns processing).
- You require vendor support, a security review, published test coverage, or proven production usage at scale.
- You are not on PHP, or your platform team mandates official SDKs.
- You expect high shipment volume and need resilience, observability, and idempotency guarantees out of the box.
Due-diligence checklist before adoption: inspect actual endpoint coverage, confirm test suite and CI, check maintainer responsiveness and release cadence, review API-key handling and logging of PII (recipient names, phone numbers, addresses), and confirm the license and dependency tree are clean.
How to Pitch It (Stakeholders)
For executives (one paragraph): Entering the Ukrainian market requires Nova Poshta, and this MIT-licensed PHP client gives us a free head start on the API integration — potentially saving 2–4 engineer-weeks versus building from scratch. The trade-off is maturity: it has negligible community adoption and no support, so we should treat it as a vetted starting point we own, not a vendor dependency. Recommendation: fund a short spike plus a one-engineer-week hardening pass (tests, abstraction layer, error handling), and launch behind a feature flag with a measured pilot.
For engineering (summary): Thin PHP wrapper over Nova Poshta API v2. Low adoption (1 star, 0 dependents) means we assume maintenance. Plan: fork/vendor the code, wrap it behind an internal DeliveryProvider interface so we can swap clients, add contract tests against the sandbox, centralize API-key config, add retry/caching for the city and branch directories, and avoid leaking recipient PII into logs. Do not call it directly from controllers or domain services.
Success signals to track post-launch: share of orders selecting Nova Poshta delivery, checkout conversion for Ukrainian traffic, API error/timeout rate, waybill creation latency, and support-ticket volume tied to delivery selection or tracking.