PHPackages                             soerbv/shipsgo - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. soerbv/shipsgo

ActiveLibrary[API Development](/categories/api)

soerbv/shipsgo
==============

A PHP client for the ShipsGo v2 API.

v2.0.1(2w ago)12.6kMITPHPPHP ^8.1

Since Feb 9Pushed 1mo agoCompare

[ Source](https://github.com/Soer-BV/ShipsGo)[ Packagist](https://packagist.org/packages/soerbv/shipsgo)[ Docs](https://www.soer.nl)[ RSS](/packages/soerbv-shipsgo/feed)WikiDiscussions main Synced today

READMEChangelog (3)DependenciesVersions (6)Used By (0)

ShipsGo
=======

[](#shipsgo)

A PHP client for the [ShipsGo v2 API](https://api.shipsgo.com/v2). Tracks ocean and air shipments, manages tags and followers.

Requirements
------------

[](#requirements)

- PHP 8.1+
- ext-curl, ext-json

Install
-------

[](#install)

```
composer require soerbv/shipsgo
```

Quick start
-----------

[](#quick-start)

```
use SoerBV\Shipsgo\Shipsgo;

$shipsgo = new Shipsgo('YOUR_SHIPSGO_TOKEN');

$shipment = $shipsgo->ocean->shipments->create(
    containerNumber: 'MSCU1234567',
    carrier: 'MSCU',
    reference: 'PO-12345',
);

echo $shipment->status->value;   // e.g. "SAILING"
echo $shipment->carrier?->name;  // "MSC"
```

Authentication
--------------

[](#authentication)

The constructor accepts either a token string or a `Config`:

```
use SoerBV\Shipsgo\{Config, Shipsgo};

$shipsgo = new Shipsgo('TOKEN');

// Or for full control:
$shipsgo = new Shipsgo(new Config(
    token: 'TOKEN',
    baseUri: 'https://api.shipsgo.com/v2',
    timeoutSeconds: 30,
));
```

Ocean
-----

[](#ocean)

```
// Create
$shipment = $shipsgo->ocean->shipments->create(
    containerNumber: 'MSCU1234567',  // or bookingNumber
    carrier: 'MSCU',
    reference: 'PO-12345',
    followers: ['ops@example.com'],
    tags: ['IMPORT'],
);

// Get one by id
$shipment = $shipsgo->ocean->shipments->get(123);
foreach ($shipment->containers as $container) {
    echo $container->number . ' — ' . $container->status->value . PHP_EOL;
}

// Or look up by container / booking number (returns ?Shipment, 2 API calls)
$shipment = $shipsgo->ocean->shipments->findByContainerNumber('MSCU1234567');
$shipment = $shipsgo->ocean->shipments->findByBookingNumber('MEDUQY000000');

// List with pagination + filters
$page = $shipsgo->ocean->shipments->list(
    filters: ['status' => 'eq:SAILING'],
    orderBy: '-created_at',
    skip: 0,
    take: 50,
);
foreach ($page as $summary) {
    echo $summary->reference . PHP_EOL;
}
if ($page->meta->more) {
    // fetch next page with skip: 50
}

// Update reference
$shipsgo->ocean->shipments->update(123, 'PO-12345-updated');

// Tags / followers
$tag = $shipsgo->ocean->shipments->addTag(123, 'URGENT');
$shipsgo->ocean->shipments->removeTag(123, $tag->id);
$shipsgo->ocean->shipments->addFollower(123, 'ops@example.com');

// Route as GeoJSON
$geo = $shipsgo->ocean->shipments->geojson(123);

// Delete
$shipsgo->ocean->shipments->delete(123);

// Carriers
$carriers = $shipsgo->ocean->carriers->list();
```

Air
---

[](#air)

```
$shipment = $shipsgo->air->shipments->create(
    awbNumber: '333-88888888',
    reference: 'AWB-REF',
);

$shipment = $shipsgo->air->shipments->get(456);
echo $shipment->airline?->name;

// Or look up by AWB number (returns ?Shipment, 2 API calls)
$shipment = $shipsgo->air->shipments->findByAwbNumber('333-88888888');

$page = $shipsgo->air->shipments->list(take: 50);
$airlines = $shipsgo->air->airlines->list();
```

All `->shipments` methods mirror the Ocean shape: `get`, `update`, `delete`, `geojson`, `addTag`, `removeTag`, `addFollower`, `removeFollower`.

Credits
-------

[](#credits)

The API returns credit cost and remaining balance on each call. They are surfaced both on list responses (`$page->credits`) and via the client:

```
$shipsgo->air->shipments->get(456);
echo $shipsgo->lastCredits()?->remaining;
```

Error handling
--------------

[](#error-handling)

All API errors extend `SoerBV\Shipsgo\Exceptions\ApiException`. Status-specific subclasses are thrown so you can catch only what you care about:

HTTPException401`AuthenticationException`402`InsufficientCreditsException`403`PermissionException`404`NotFoundException`409`ConflictException`422`ValidationException`429`RateLimitException` (use `->retryAfterSeconds()`)5xx`ServerException`Network/transport failures throw `TransportException`. Everything inherits from `ShipsgoException` if you want a single catch-all.

Laravel
-------

[](#laravel)

The package is framework-neutral. To use it in Laravel, bind it in a service provider:

```
$this->app->singleton(Shipsgo::class, fn () => new Shipsgo(config('services.shipsgo.token')));
```

Upgrading from 1.x
------------------

[](#upgrading-from-1x)

The 1.x client (`SoerBV\Shipsgo\Client`) targeted the legacy v1.1 `ContainerService` API and is **removed** in 2.0. The v2 API uses a different authentication scheme (header-based token), JSON payloads, and a different endpoint layout, so there is no in-place upgrade. Replace any `new Client($authCode)` usage with `new Shipsgo($token)` and the resource methods above.

###  Health Score

49

—

FairBetter than 94% of packages

Maintenance95

Actively maintained with recent releases

Popularity21

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 93.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~408 days

Total

4

Last Release

15d ago

Major Versions

v1.0.0 → 2.x-dev2026-05-31

PHP version history (2 changes)v1.0.0PHP >=8.0.0

2.x-devPHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/42b3abb3d7bf16207585359e1c7e2e752272126406a787070646eefb6a0f5001?d=identicon)[ThijmenKort](/maintainers/ThijmenKort)

---

Top Contributors

[![ThijmenKort](https://avatars.githubusercontent.com/u/101055765?v=4)](https://github.com/ThijmenKort "ThijmenKort (15 commits)")[![RickDBCN](https://avatars.githubusercontent.com/u/9408120?v=4)](https://github.com/RickDBCN "RickDBCN (1 commits)")

---

Tags

composerphpshipsgophpapitrackingairoceanshipsgo

### Embed Badge

![Health badge](/badges/soerbv-shipsgo/health.svg)

```
[![Health](https://phpackages.com/badges/soerbv-shipsgo/health.svg)](https://phpackages.com/packages/soerbv-shipsgo)
```

###  Alternatives

[jstolpe/instagram-graph-api-php-sdk

Instagram Graph API PHP SDK

138110.7k2](/packages/jstolpe-instagram-graph-api-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)