Novaposhta Laravel Package

Product Decisions This Supports

• Cash-on-delivery (COD) as a checkout option. Release 1.4 adds setAfterpaymentOnGoodsCost to InternetDocument, letting us mark a waybill so the recipient pays for the goods on delivery rather than prepaying. This is the single most requested payment pattern for Ukrainian e-commerce, so it directly unblocks a checkout/payment roadmap item we could not previously express through this integration.
• Shipment status visibility. PR #49 ("Додав статус") extends status handling. Supports building tracking notifications, "where is my parcel" support flows, and delivery-SLA reporting without a separate tracking integration.
• Build vs. buy for Nova Poshta integration. The package is a thin wrapper over the Nova Poshta API (InternetDocument, statuses, etc.). It's a "buy" (well, "adopt") for standard waybill creation and COD; only worth building in-house if we need heavy customization or dedicated support terms.
• Roadmap sequencing. Because the change is additive and non-breaking, we can slot COD enablement into the current cycle without a migration or regression-test project.
• Feature scope for international vs. domestic. Nova Poshta is Ukraine-specific; this supports domestic/UA-market features only. Any multi-country logistics roadmap should treat this as one regional adapter, not a global solution.

When to Consider This Package

• Adopt when: you're a Laravel/PHP shop shipping via Nova Poshta, need programmatic waybill creation, and want COD/afterpayment configuration without hand-rolling HTTP calls and payload mapping. Version 1.4 is a safe upgrade from 1.3 — StyleCI cleanup, an added status value, and one new setter; no breaking changes identified.
• Prefer it when: your team is already on Laravel, your logistics needs are the standard Nova Poshta flows, and you want to move fast at low cost.
• Look elsewhere (or wrap it) when: you need guaranteed API coverage across all Nova Poshta endpoints (a single new setter per release suggests coverage grows reactively), you require vendor support/SLA, you need strong test coverage and typed contracts, or you operate outside Ukraine. Also consider a maintained alternative or an in-house adapter if the single-maintainer bus factor is a business risk and shipping is mission-critical.
• Keep an eye on: version numbering — 1.3 → 1.4 with a new method and a small behavior/status addition reads as a minor bump; confirm the project's semver discipline before pinning with a caret constraint in production.

How to Pitch It (Stakeholders)

For executives: Nova Poshta, our Ukrainian carrier, just shipped an update to the Laravel integration we evaluated. The one commercially meaningful item is support for cash-on-delivery — customers paying for goods when the parcel arrives — which is a standard expectation in that market and something we couldn't configure before. The change is small and low-risk: no breaking changes, no migration, no new infrastructure. Cost of adoption is essentially engineering hours already budgeted for the logistics integration. Recommendation: adopt, and schedule COD checkout as a near-term roadmap item.

For engineering: Upgrade 1.3 → 1.4 is non-breaking. New: InternetDocument::setAfterpaymentOnGoodsCost(...), an added status value, and StyleCI formatting fixes; plus a new contributor. Validate behavior in staging against a real Nova Poshta test account (particularly how the new status value maps into our order state machine, and that the COD setter serializes correctly in waybill payloads) before relying on it in production. Note the package is community-maintained by a single primary author — treat it as a dependency to pin and monitor, and isolate it behind our own logistics interface so we can swap or extend it without touching checkout code.