Sendcloud Php Client Laravel Package

Technical Evaluation

Architecture fit

• picqer/sendcloud-php-client is a framework-agnostic PHP SDK, not a Laravel package. There is no service provider, facade, config stub, or publishable assets. That is the correct trade-off for a vendor SDK (it serves Symfony, plain PHP, and legacy apps), but it means the integration layer is our code, not theirs.
• The client is a thin, resource-oriented wrapper (Parcels, Shipments, Shipping Methods, Labels, Returns, Pickups, Webhooks) over Guzzle. Fit into Laravel is clean provided we treat it as an infrastructure adapter behind our own domain interface rather than calling it from controllers.
• Because Guzzle is already a transitive dependency of most Laravel HTTP stacks, conflict risk is low. The real coupling risk is behavioural, not dependency-based: request/response shapes, pagination semantics, and error typing.

Integration feasibility

• Straightforward: composer require, bind a configured client as a singleton, wrap in an adapter. A mid-level engineer can produce a working label-creation path in 1–2 days.
• Non-trivial work sits outside the SDK: credential/config management, queued label generation, PDF storage and streaming, webhook ingestion and verification, and DTO mapping to our Order/Shipment models.
• Testability is a concern. Since the client owns its Guzzle instance, Laravel's Http::fake() will not intercept calls unless we inject a mock handler or put our own interface in front of it. Plan the interface first, or we will end up with untestable shipping code.

Technical risk

• Adoption signal is weak (44 stars). This is a vendor utility maintained for Picqer's own WMS product, not a community-driven library. Bus factor is effectively one team, and there is no public SLA or deprecation policy we can point procurement at.
• API version exposure is the material risk. SendCloud has moved from v2 to v3 with changes to authentication and resource models. We must confirm which version this client targets, whether both are supported, and what the vendor's sunset timeline is — a version sunset becomes a hard internal deadline.
• Idempotency semantics are undocumented at the SDK level. If label creation is retried after a timeout, do we get a duplicate label and a duplicate carrier charge? This is a direct cost and reconciliation risk.
• Maintenance health is ambiguous: a 2026-01-08 release looks active, but release cadence and backward-compatibility discipline are unverified. Recent tags can also be housekeeping releases rather than API-tracking ones.
• Licence (MIT) is unproblematic.

Key questions for the maintainer / SendCloud

1. Which SendCloud API version(s) does the current release support, and what is the sunset policy for the older one?
2. What is the authentication model (API key/secret Basic vs. bearer/partner keys), and how does rotation work?
3. Are label-creation endpoints idempotent, or must we supply our own idempotency key?
4. Are webhook payloads signed, and is there a documented verification scheme?
5. Is there a sandbox/test environment, and does the SDK expose it via base URI configuration?
6. What are the documented rate limits per endpoint, and does the SDK surface 429/Retry-After in a typed way?
7. What are the PHP and Guzzle version constraints, and is there a stated BC policy across minor releases?
8. Does the SDK support partner/multi-tenant scoping if we ever ship on behalf of sub-accounts?

Integration Approach

Stack fit

• Treat the SDK as a driven adapter. Define ShippingProviderInterface (create label, void label, fetch rates, get tracking) in our domain layer, implement SendCloudProvider using this client. This is what makes the vendor choice reversible.
• Configuration belongs in config/services.php with credentials in the secret manager, never in .env committed to the repo. Bind the client as a scoped or singleton service; scoped is safer if we ever introduce per-tenant credentials.
• Persist provider artefacts explicitly: shipments table carrying provider, provider_reference, tracking_number, label_disk_path, status, carrier, service_point_id. Do not rely on re-querying SendCloud to render customer-facing tracking.

Migration path

• If we currently generate labels manually in the SendCloud dashboard, phase in: (1) read-only rate/shipping-method lookups in staging, (2) label creation for a single carrier in a queued job behind a feature flag, (3) webhook-driven tracking updates, (4) full cutover, (5) dashboard access reduced to break-glass only.
• If we are replacing another provider, run both in parallel for a subset of orders and diff carrier assignment and cost before switching.
• Provide a data backfill path: existing shipments need tracking_number and carrier normalised into the new schema so customer-facing order pages do not regress on day one.

Compatibility

• Pin the SDK to an exact minor version and upgrade deliberately. With this adoption level, do not rely on semver holding.
• Verify PHP constraint against our Laravel version before committing; a PHP 8.1 floor blocks nothing today but does constrain long-term support windows.
• Wrap the client's exception types at the adapter boundary so upstream renames do not leak into application code.

Sequencing

1. Domain interface + DTOs + persistence schema (no vendor code).
2. Adapter implementation with a fake provider for tests.
3. Credential/config plumbing and a smoke test against sandbox.
4. Queued label creation with retry, backoff, and dead-letter handling.
5. Webhook route, verification, queue fan-out.
6. Feature-flagged rollout by carrier and by region.
7. Observability, then decommission manual steps.

Operational Impact

Maintenance

• Budget a standing allowance for vendor tracking: watch releases, read the SendCloud changelog, and run a small weekly contract test against sandbox (fetch shipping methods, create a test label) so we learn about breakage before customers do.
• Our own wrapper is the part that will need real maintenance; keep it thin so there is little to maintain. Resist the temptation to fork the SDK — a fork converts a vendor problem into a staffing problem.

Support

• Two support surfaces with different quality: SendCloud's commercial API support (contractual, responsive) for service issues, and Picqer's GitHub issues (best-effort, no SLA) for client defects.
• Establish internally who owns shipping integrations. This is a single-owner domain today in most organisations and a classic key-person risk.

Scaling

• Per-label HTTP calls dominate. For bulk fulfilment days, use queue workers with a bounded concurrency ceiling matched to SendCloud's rate limits — throwing workers at it will produce 429s and partial batches.
• Cache shipping methods and service points aggressively (they change on the order of days, not seconds); this is the single largest call-volume reduction available.
• Store label PDFs on object storage, not the app server, and stream to customers via signed URLs. Regenerating labels is possible but should be the exception, not the read path.
• Webhook ingestion must be idempotent and queued; tracking updates arrive out of order and can be duplicated.

Failure modes to instrument explicitly

• 401 after credential rotation — alert on auth failures separately from general errors; they are an outage, not a blip.
• 429 throttling — requires backoff and queue depth alerts, otherwise labels silently stop.
• Slow label generation / gateway timeouts — the highest-cost failure, because retries can duplicate labels and carrier spend. Log the provider reference before retry and reconcile.
• SendCloud outage — checkout should degrade to "delivery options unavailable" rather than failing the order; fulfilment should queue, not error out to the user.
• Webhook loss or delivery gaps — run a periodic reconciliation job polling open shipments, otherwise tracking silently stops updating on some fraction of orders.
• API version sunset — treat as a dated risk on the roadmap, not a surprise ticket.

Ramp-up

• The SDK itself is a half-day read. The adapter, queues, storage, and webhooks are one to two weeks for one engineer including tests.
• The real ramp-up cost is domain, not code: carrier service rules, EU/international customs data, HS codes, service points, and returns flows. Budget for someone with logistics context or an external advisor; a technically correct integration that mis-assigns carriers is worse than a manual process.

Recommendation Adopt, with conditions: pin the version, invert the dependency behind our own interface, confirm the API-version sunset timeline and idempotency behaviour before writing retry logic, and accept that this package is a leg up rather than a solution — the durable asset we build is the adapter, not the dependency.