README

A PHP client for the ShipsGo v2 API. Tracks ocean and air shipments, manages tags and followers.

Requirements

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

Install

composer require soerbv/shipsgo

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

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

// 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

$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

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

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

Network/transport failures throw TransportException. Everything inherits from ShipsgoException if you want a single catch-all.

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

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.