graystackit/laravel-ship24-api

Laravel package for the Ship24 shipment tracking API, built on Saloon 4.

Requirements

• PHP 8.3+
• Laravel 11, 12, or 13

Installation

composer require graystackit/laravel-ship24-api

Publish the config file:

php artisan vendor:publish --tag=ship24-config

Publish and run the migration (required for local tracking storage):

php artisan vendor:publish --tag=ship24-migrations
php artisan migrate

Add your API key to .env:

SHIP24_API_KEY=your-api-key-here

Configuration

Tracking modes

API Client

Inject or resolve Ship24Client from the container:

use GraystackIT\Ship24\Ship24Client;

$client = app(Ship24Client::class);

Create a tracker

$tracker = $client->createTracker('1Z999AA10123456784', 'ORDER-001');

echo $tracker->trackerId;       // trk_abc123
echo $tracker->trackingNumber;  // 1Z999AA10123456784
echo $tracker->isTracked;       // true

List all trackers (with pagination)

$result = $client->listTrackers(page: 1, limit: 50);

foreach ($result['trackers'] as $tracker) {
    echo $tracker->trackerId . ': ' . $tracker->trackingNumber;
}

echo $result['total']; // total tracker count
echo $result['page'];  // 1
echo $result['limit']; // 50

Parameters:

Bulk create trackers (up to 100)

use GraystackIT\Ship24\Data\BulkCreateResult;

$result = $client->bulkCreateTrackers([
    ['trackingNumber' => '1Z999AA10123456784', 'shipmentReference' => 'ORDER-001'],
    ['trackingNumber' => 'JD014600006228974097'],
    ['trackingNumber' => 'RA123456789DE', 'originCountryCode' => 'DE'],
]);

echo $result->status;       // success | partial | error
echo $result->requested;    // 3
echo $result->successCount; // 3
echo $result->errorCount;   // 0

foreach ($result->items as $item) {
    if ($item->success) {
        echo $item->tracker->trackerId;
    } else {
        echo $item->errorCode . ': ' . $item->errorMessage;
    }
}

Throws \InvalidArgumentException if the array is empty or has more than 100 items.

Create and track (combined — single API call)

Creates a tracker and immediately returns its tracking results without a second request:

$result = $client->createAndTrack(
    trackingNumber:        '1Z999AA10123456784',
    shipmentReference:     'ORDER-001',       // optional
    originCountryCode:     'US',              // optional
    destinationCountryCode: 'DE',             // optional
    destinationPostCode:   '10115',           // optional
    shippingDate:          '2024-06-01',      // optional (YYYY-MM-DD)
    courierCode:           ['ups'],           // optional (max 3)
);

echo $result->tracker->trackerId;
echo $result->shipment->statusMilestone; // delivered, in_transit, etc.
echo $result->latestEvent()?->status;

// Statistics (if returned by the API)
print_r($result->statistics);

Update an existing tracker

$tracker = $client->updateTracker('trk_abc123', [
    'isSubscribed'          => false,
    'originCountryCode'     => 'US',
    'destinationCountryCode'=> 'DE',
    'destinationPostCode'   => '10115',
    'shippingDate'          => '2024-06-01',
    'courierCode'           => ['ups'],
]);

echo $tracker->isSubscribed; // false

Throws \InvalidArgumentException if the updates array is empty.

Get tracking results by tracker ID

$results = $client->getTrackingResults('trk_abc123');

foreach ($results as $result) {
    echo $result->shipment->statusMilestone;
    echo $result->latestEvent()?->status;
}

Get tracking results by tracking number

For when you have the tracking number but not the tracker ID:

$results = $client->getTrackingResultsByTrackingNumber('1Z999AA10123456784');

foreach ($results as $result) {
    echo $result->tracker->trackerId;
    echo $result->shipment->currentCourierName;
    echo $result->shipment->originCountryCode;

    foreach ($result->events as $event) {
        echo $event->datetime . ' — ' . $event->status . ' — ' . $event->location;
    }
}

Search by tracking number (per-call plan)

One-shot search without creating a persistent tracker. No tracker ID required:

$results = $client->searchByTrackingNumber('JD014600006228974097');

foreach ($results as $result) {
    echo $result->shipment->currentCourierName;
    echo $result->shipment->originCountryCode;

    foreach ($result->events as $event) {
        echo $event->datetime . ' - ' . $event->status . ' - ' . $event->location;
    }
}

Note: This uses the /tracking/search per-call endpoint — it does not create a persistent tracker and response time may be up to 1 minute.

Trackable Models

Add the IsTrackableByShip24 trait to any Eloquent model to attach Ship24 tracking data directly to it.

use GraystackIT\Ship24\Traits\IsTrackableByShip24;

class Order extends Model
{
    use IsTrackableByShip24;
}

Start tracking

Creates a Ship24 tracker and immediately stores the initial tracking result in a local ship24_trackings record linked to the model.

$tracking = $order->startTracking('1Z999AA10123456784', 'ORDER-001');

echo $tracking->status_milestone; // in_transit
echo $tracking->carrier_name;     // UPS

Sync tracking

Fetches the latest data from Ship24 and updates (or creates) the local record.

$tracking = $order->syncTracking('1Z999AA10123456784');

Read stored tracking data

// All tracking records linked to this model
foreach ($order->trackings as $t) {
    echo $t->tracking_number . ': ' . $t->status_milestone;
}

// Most recently updated record
$latest = $order->latestTrackingStatus();
echo $latest?->status_milestone;  // delivered
echo $latest?->carrier_name;      // UPS
echo $latest?->latest_event_at;   // 2024-06-10 12:00:00

Webhook

Ship24 can push tracking updates to your application in real-time. The package registers a POST endpoint automatically (disable via SHIP24_WEBHOOK_ENABLED=false).

Default URL: POST /ship24/webhook

Configure this URL in the Ship24 dashboard.

Signature validation

Set SHIP24_WEBHOOK_SECRET to enable HMAC-SHA256 request validation. The package checks the X-Ship24-Signature header.

SHIP24_WEBHOOK_SECRET=your-webhook-secret

The webhook handler automatically:

1. Validates the optional signature
2. Parses the payload (trackingNumber, trackerId, shipment, events)
3. Finds all ship24_trackings records matching the tracking number / tracker ID
4. Updates them according to the configured tracking_mode

Artisan command

Manually refresh tracking data from the API (useful as a fallback when webhooks are unavailable):

# Refresh all ship24_trackings records
php artisan ship24:refresh

# Refresh a single record by its primary key
php artisan ship24:refresh 42

Data objects

ship24_trackings table columns

Error handling

All API errors throw GraystackIT\Ship24\Exceptions\Ship24ApiException:

use GraystackIT\Ship24\Exceptions\Ship24ApiException;

try {
    $results = $client->getTrackingResultsByTrackingNumber('INVALID');
} catch (Ship24ApiException $e) {
    logger()->error('Ship24 error: ' . $e->getMessage());
    // $e->getCode() returns the HTTP status code
}

Input validation errors (empty bulk array, empty update fields, bulk > 100) throw \InvalidArgumentException.

API endpoints reference

Testing

# API client tests (no database required)
vendor/bin/pest tests/Feature

# Integration tests (require pdo_sqlite or pdo_mysql)
vendor/bin/pest tests/Integration

Feature tests use Saloon's MockClient — no real API calls are made.

License

MIT