Laravel Paddle Laravel Package

Product Decisions This Supports

• Build vs. buy on billing infrastructure. This package is a thin Laravel client over Paddle Billing's API, so it makes "buy the billing layer" a viable decision for a Laravel SaaS: you inherit Paddle as merchant of record (sales tax, VAT, invoicing, compliance) and only own the integration glue, not the ledger, tax engine, or dunning logic.
• Merchant-of-record vs. payment-facilitator. Choosing Paddle over Stripe-style processing is a pricing/ops decision (who carries tax liability, who handles chargebacks). Having a first-class Laravel client lowers the switching cost of that decision and de-risks the MoR path.
• Monetization roadmap sequencing. Coverage of products, prices, customers, subscriptions, transactions, discounts, and adjustments means roadmap items like coupon campaigns, plan changes, trials, proration, and one-off charges are reachable without new infrastructure — useful for quarterly pricing/packaging experiments.
• Lifecycle automation via webhooks. Signature verification with a replay window means subscription state changes (renewals, payment failures, cancellations) can be treated as a trustworthy event source, enabling decisions around involuntary churn handling, grace periods, and entitlement revocation.
• Scope discipline for the first billing release. A resource-mapped client (not a full opinionated subscription abstraction) implies the product team owns the domain model; it supports a decision to ship an MVP billing flow and defer a richer subscription-state layer.
• Compliance and auditability as a gating requirement. Typed exceptions carrying Paddle's error body and machine-readable error codes make failure handling observable, which supports decisions about support tooling, refund workflows, and incident response expectations.
• Vendor risk posture. Sandbox support (PADDLE_SANDBOX) enables safe pre-production validation, which affects the decision to commit to Paddle before signing commercial terms and setting go-live criteria.

When to Consider This Package

Adopt when most of the following hold:

• You are building a Laravel 12 or 13 application on PHP 8.2+ and want billing inside the existing codebase rather than a separate service.
• Your revenue model is recurring subscriptions sold globally, and the tax/compliance burden of being merchant of record is a cost you would rather outsource to Paddle.
• You need a direct, predictable mapping to Paddle Billing API v1 — you are comfortable owning your own subscription/entitlement model and webhook handlers rather than inheriting a framework's opinion.
• You need discounts, adjustments, and transaction-level data for pricing experiments, revenue reporting, or reconciliation.
• You can commit engineering time to webhook ingestion and state synchronization; the package verifies signatures but the surrounding idempotency and reconciliation work is yours.

Look elsewhere when:

• You want a Cashier-equivalent. This is a resource client, not a batteries-included subscription abstraction with migrations, billable traits, or built-in lifecycle handlers. If your team does not want to build subscription state modeling, an opinionated layer (or Paddle's own Checkout/inline flows) will be cheaper than assembling one here.
• You need hosted checkout UX out of the box. The release notes describe API resources and webhook verification only; nothing indicates checkout overlay/inline helper support. Plan for frontend work or a different integration path.
• You are on Paddle Classic. This targets Billing API v1 specifically — do not assume drop-in parity.
• You are pre-1.x risk-averse on a very young package. v1.0.0 is the initial release: API surface is declared stable by semver, but real-world hardening (retries, rate limiting, idempotency keys, pagination ergonomics) is unproven. Evaluate with a timeboxed sandbox spike before making it load-bearing.
• You need marketplace payouts, usage-based metering at high volume, or complex multi-entity billing — validate against Paddle's own product limits first; the client will faithfully expose whatever the API does or doesn't do.
• Your platform is not Laravel or is Laravel ≤11 / PHP <8.2.

How to Pitch It (Stakeholders)

For executives: Paddle handles the parts of billing we least want to own — global sales tax, invoicing, and merchant-of-record compliance. This package is the Laravel-side connector that lets us sell subscriptions through Paddle without building a billing subsystem or standing up a separate service. It is scoped to integration, not to business logic, so cost and risk stay small: no proprietary data store, no migration off our stack, and the ability to run entirely in Paddle's sandbox before we commit commercially. It reaches 1.0.0 at initial release — genuinely early — so the recommendation is to validate it in a sandbox spike and pilot on one plan before it becomes revenue-critical.

For engineering: A thin, dependency-light client mapping Paddle Billing API v1 resources (products, prices, customers, subscriptions, transactions, discounts, adjustments, events, notifications) onto Laravel 12/13 and PHP 8.2+. Two things are already solved for us: Paddle-Signature webhook verification with HMAC-SHA256 and a replay window, and a PaddleException that surfaces Paddle's error body plus machine-readable error code for precise failure handling. Sandbox is a config flag. What it deliberately does not give us: an opinionated billable model, migrations, retry/backoff, idempotency helpers, or checkout UI. We own subscription state, webhook idempotency, and reconciliation. That is the trade — a smaller, more legible surface we control, in exchange for building the domain layer ourselves. Ask: one engineer-week sandbox spike covering subscribe, upgrade with proration, failed payment, and refund, plus a webhook replay test, before we adopt.