Shop Client Laravel Package

Product Decisions This Supports

• Build vs. buy for the commerce integration layer. Adopting paloma/shop-client is effectively a decision to buy into Paloma as your shop/commerce backend and let a vendor-maintained SDK own the transport, auth, and DTO layer. The alternative — a hand-rolled Guzzle client or a direct integration to the underlying commerce platform — should be priced against this at the same time, not after.
• Roadmap sequencing for a new commerce channel. The client's exposed surface (catalog, cart/checkout, order lifecycle, inventory, webhooks, and now customer records with custom data) defines the realistic MVP boundary. If the package covers catalog read plus order create, your first release can be a catalog-and-orders slice. The v3.5.4 addition of customer custom data moves basic customer-profile sync into the "probably already covered" bucket — relevant if your roadmap includes CRM/CDP sync, B2B account attributes, or personalisation fields, but verify how much of that is typed versus pass-through before you commit scope to it.
• Data-model ownership for customer attributes. A free-form custom-data field is a product decision, not just an API one: someone has to own the schema, validation, and lifecycle of those keys. Decide whether customer custom data is a first-class part of your domain (validated, versioned, migrated) or an opaque blob you forward to a downstream system. The package will let you do either; only one of them stays cheap.
• Time-to-first-transaction as the primary bet. For a thin client like this, the value proposition is almost entirely speed: days of integration work compressed into a Composer install plus configuration. That makes it a fit for a validation phase, a pilot merchant, or a partner integration where the commercial question is still open.
• Vendor and coupling risk on the architecture roadmap. A client library is the narrowest point of coupling to a vendor. Deciding now whether it sits behind an internal interface (an anti-corruption layer) or is called directly from domain code is a decision you make once and pay for later — this package's existence forces that conversation earlier than usual.
• Internal tooling and ops scope. Back-office sync jobs, reconciliation reports, order re-drive scripts, customer-data backfills, and sandbox/test-data seeding are all natural consumers of a shop client. These are low-risk places to prove the integration before customer-facing traffic touches it.
• Vendor due diligence input. The SDK is a proxy signal for the vendor's engineering maturity: naming, typing, error handling, release cadence, and docs quality tell you more about the platform's operational discipline than a sales deck does.

When to Consider This Package

Adopt or spike when:

• Paloma is already a committed or shortlisted dependency. The package is a client for a specific backend; it has no standalone value. If the vendor decision is live, the client is a legitimate, cheap way to run a two-day integration spike and pressure-test the API.
• You are on PHP/Laravel and want idiomatic configuration and container bindings rather than bespoke HTTP plumbing. Outside PHP, this is irrelevant regardless of merit.
• The integration is narrow and reversible. Prototypes, internal tools, partner pilots, and data-sync jobs are the right first consumers. Isolate the dependency behind your own interface so the cost of removing it stays low.
• You need customer records in your integration. v3.5.4 adds customer custom data, which is the first release in this series to materially widen the DTO surface rather than patch it. If customer profiles or attributes were a gap in your scope, re-check coverage now — but confirm whether custom fields are typed or free-form before designing around them.
• You can absorb the maintenance risk. Still near-zero public adoption and no evident community backstop. A steady patch cadence (v3.5.4 on top of a v3.x line) is mildly reassuring on maintenance intent, but it is not evidence of production usage elsewhere. Acceptable for a spike; not a maturity signal.

Look elsewhere when:

• Paloma is not on your stack. There is no generic commerce abstraction here — no multi-vendor portability, no fallback to another provider.
• The client is the only interface to the platform. If Paloma publishes a documented REST/GraphQL API, calling it directly may carry less long-term risk than depending on a single-maintainer wrapper whose release cadence you don't control.
• You need contractual guarantees. No stars, no dependents, and patch-level releases do not add up to a support relationship. If the integration is revenue-critical or customer-facing at scale, you need an SLA, a named owner, or the option to fork — and you should confirm in writing whether the vendor treats this client as a supported product or a reference implementation.
• You are comparing against mature, well-adopted SDKs. Official clients for larger commerce platforms come with a decade of edge-case handling and community answers; this one very likely does not yet.
• You need functionality the wrapper doesn't expose. Escape hatches matter: check whether the client allows raw requests or custom endpoints, or you will be blocked by the wrapper's coverage. The custom-data pattern suggests the vendor is willing to expose pass-through fields, but that is not the same as a general escape hatch.

Before committing, gate on: published documentation, a test suite, semantic versioning, a visible issue tracker, and a named maintainer. Treat any missing item as a cost you will fund internally. The v3.5.4 release is a useful probe on two of these — it demonstrates the project can ship incremental, additive changes; it says nothing about test coverage or support obligations.

How to Pitch It (Stakeholders)

To executives: This is a small, single-purpose library that lets us talk to Paloma's shop backend without building the plumbing ourselves. It buys speed to a working integration — likely days instead of weeks — and it is cheap to remove because it is a thin wrapper, not a platform commitment. The latest release adds customer custom-data support, which extends the useful surface from orders and catalog into customer profiles; that is an incremental improvement, not a change in maturity. The caveat stands: near-zero public adoption, so we treat it as an accelerator for a time-boxed pilot, not as a foundation for revenue-critical checkout until we've validated it. Recommendation: fund a short spike with a defined kill criterion, and defer the production decision until we see the API and the vendor's support posture.

To engineering: Composer-installable, PHP-idiomatic, and a fast path to a working client. Its value is entirely in the surface it exposes and the DTOs it saves you from writing. v3.5.4 is additive and appears non-breaking, so a version bump within the 3.x line should be low-risk — but pin the version anyway and read the diff, because a patch-level change to the customer payload can still shift serialisation behaviour. Two asks: first, put it behind our own repository interface so the vendor type never appears in domain code; second, verify error handling, retries, and timeout behaviour before anything customer-facing depends on it, and decide explicitly whether customer custom data lands in a typed domain object or an opaque passthrough. Assume single-maintainer risk — if the pilot succeeds, decide explicitly between forking, contributing upstream, or replacing it with direct API calls.

Bottom line: the package is a time-to-market lever, not a strategic asset. Recent releases show steady, additive maintenance, which slightly improves confidence in the vendor's engineering discipline without changing the risk profile. Use it to learn fast and keep the exit cheap.