README

A modern PHP SDK for the Shipday API.

The SDK requires PHP 8.3+ and uses a resource-based API:

use Victorycodedev\Shipday\Shipday;
use Victorycodedev\Shipday\Enums\OrderStatus;

$shipday = Shipday::make('your-shipday-api-key');

$order = $shipday->orders()->create([
    'orderNumber' => 'A-1001',
    'customerName' => 'Ada Lovelace',
    'customerAddress' => '556 Crestlake Dr, San Francisco, CA 94132, USA',
    'customerPhoneNumber' => '+14152392212',
    'restaurantName' => 'Popeyes Louisiana Kitchen',
    'restaurantAddress' => '890 Geneva Ave, San Francisco, CA 94112, United States',
]);

Installation

composer require victorycodedev/shipday

Requirements

• PHP 8.3+
• Shipday API key

Some generated Shipday examples also show an x-api-key header. The SDK does not send a literal x-api-key: null header, but you can include an x-api-key value when needed:

$shipday = Shipday::make(
    apiKey: 'your-shipday-api-key',
    xApiKey: 'your-x-api-key',
);

Delivery Orders

$shipday = Shipday::make('your-shipday-api-key');

$shipday->orders()->active();
$shipday->orders()->find('ORDER_NUMBER');
$shipday->orders()->create([...]);
$shipday->orders()->update($orderId, [...]);
$shipday->orders()->delete($orderId);
$shipday->orders()->query([...]);
$shipday->orders()->assignDriver($orderId, $carrierId);
$shipday->orders()->unassignDriver($orderId);
$shipday->orders()->readyToPickup($orderId); // sends ["readyToPickup" => true]
$shipday->orders()->updateStatus($orderId, OrderStatus::Started);
// Raw strings are also accepted for forward compatibility:
$shipday->orders()->updateStatus($orderId, 'STARTED');

Pickup Orders

$shipday->pickupOrders()->create([...]);
$shipday->pickupOrders()->find($orderId);
$shipday->pickupOrders()->update($orderId, [...]);
$shipday->pickupOrders()->delete($orderId);

Carriers

$shipday->carriers()->all();

$shipday->carriers()->create([
    'name' => 'Jane Driver',
    'email' => 'jane@example.com',
    'phoneNumber' => '+11234567890',
]);

$shipday->carriers()->delete($carrierId);

Delivery Tracking

$shipday->tracking()->progress(
    trackingId: 'tracking-id',
    includeStaticData: true,
);

On-Demand Delivery

$shipday->onDemand()->services();
$shipday->onDemand()->estimate($orderId);

$shipday->onDemand()->assign([
    'name' => 'DoorDash',
    'orderId' => $orderId,
    'tip' => 6.50,
    'estimateReference' => 'estimate-reference',
    'contactlessDelivery' => false,
    'podType' => 'PHOTO',
]);

$shipday->onDemand()->details($orderId);
$shipday->onDemand()->cancel($orderId);

$shipday->onDemand()->availability([
    'pickupAddress' => '1 Wall St, New York, NY 10005, USA',
    'deliveryAddress' => '1000 5th Ave, New York, NY 10028, USA',
]);

Partner API

Partner endpoints use a separate client because Shipday requires PARTNER-API-KEY.

use Victorycodedev\Shipday\PartnerShipday;
use Victorycodedev\Shipday\Enums\PartnerOrderStatus;

$partner = PartnerShipday::make('your-partner-api-key');

$partner->orders()->query([
    'companyId' => '1234',
    'orderStatus' => PartnerOrderStatus::Active,
    'startCursor' => 1,
    'endCursor' => 25,
]);
$partner->orders()->completed($companyId);
$partner->members()->details();

Exceptions

The SDK uses one exception class:

use Victorycodedev\Shipday\Exceptions\ShipdayException;

try {
    $shipday->orders()->active();
} catch (ShipdayException $exception) {
    $exception->statusCode();
    $exception->response();
    $exception->headers();
    $exception->errorId();
    $exception->errorName();
    $exception->details();
    $exception->retryAfter();
}

Enums

The SDK includes enums for documented Shipday values while still accepting raw strings where forward compatibility matters.

Order Status

Use OrderStatus when updating a delivery order status:

use Victorycodedev\Shipday\Enums\OrderStatus;

$shipday->orders()->updateStatus($orderId, OrderStatus::Started);

Available cases:

OrderStatus::Started;
OrderStatus::PickedUp;
OrderStatus::ReadyToDeliver;
OrderStatus::AlreadyDelivered;
OrderStatus::Incomplete;
OrderStatus::FailedDelivery;

Partner Order Status

Use PartnerOrderStatus when querying partner orders:

use Victorycodedev\Shipday\Enums\PartnerOrderStatus;

$partner->orders()->query([
    'companyId' => '1234',
    'orderStatus' => PartnerOrderStatus::Active,
]);

Available cases:

PartnerOrderStatus::Active;
PartnerOrderStatus::NotAssigned;
PartnerOrderStatus::NotAccepted;
PartnerOrderStatus::NotStartedYet;
PartnerOrderStatus::Started;
PartnerOrderStatus::PickedUp;
PartnerOrderStatus::ReadyToDeliver;
PartnerOrderStatus::AlreadyDelivered;
PartnerOrderStatus::FailedDelivery;
PartnerOrderStatus::Incomplete;

Webhook Events

Webhook events expose both raw strings and enum helpers:

$event->event();
$event->eventType();

Known event enum cases include:

WebhookEventType::OrderAssigned;
WebhookEventType::OrderAcceptedAndStarted;
WebhookEventType::OrderOnTheWay;
WebhookEventType::OrderCompleted;
WebhookEventType::OrderFailed;
WebhookEventType::OrderIncomplete;
WebhookEventType::OrderDeleted;
WebhookEventType::OrderInserted;
WebhookEventType::OrderPickedUp;
WebhookEventType::OrderUnassigned;
WebhookEventType::OrderPickedUpRemoved;
WebhookEventType::OrderOnTheWayRemoved;
WebhookEventType::OrderPodUpload;
WebhookEventType::LocationUpdate;

Webhook order statuses expose:

$event->status();
$event->statusType();

Known status enum cases include:

WebhookOrderStatus::NotAssigned;
WebhookOrderStatus::NotAccepted;
WebhookOrderStatus::NotStartedYet;
WebhookOrderStatus::Started;
WebhookOrderStatus::PickedUp;
WebhookOrderStatus::ReadyToDeliver;
WebhookOrderStatus::AlreadyDelivered;
WebhookOrderStatus::Incomplete;
WebhookOrderStatus::FailedDelivery;

Webhooks

Your application still receives the HTTP webhook request. The SDK helps validate the optional Shipday webhook token, decode the payload, detect the event type, and expose useful values.

Shipday sends the validation token in a header named token.

Laravel Example

use Illuminate\Http\Request;
use Victorycodedev\Shipday\Enums\WebhookEventType;
use Victorycodedev\Shipday\Enums\WebhookOrderStatus;
use Victorycodedev\Shipday\Webhooks\DriverLocationUpdated;
use Victorycodedev\Shipday\Webhooks\OrderStatusUpdated;
use Victorycodedev\Shipday\Webhooks\ShipdayWebhook;

Route::post('/webhooks/shipday', function (Request $request) {
    $event = ShipdayWebhook::fromRequest(
        payload: $request->getContent(),
        headers: $request->headers->all(),
        token: config('services.shipday.webhook_token'),
    );

    if ($event instanceof OrderStatusUpdated) {
        $event->event();
        $event->eventType(); // WebhookEventType::OrderCompleted
        $event->status();
        $event->statusType(); // WebhookOrderStatus::AlreadyDelivered
        $event->orderId();
        $event->orderNumber();
        $event->order();
        $event->carrier();
    }

    if ($event instanceof DriverLocationUpdated) {
        $event->orderId();
        $event->companyId();
        $event->latitude();
        $event->longitude();
        $event->timestamp();
    }

    return response()->json(['received' => true]);
});

Plain PHP Example

use Victorycodedev\Shipday\Webhooks\ShipdayWebhook;

$event = ShipdayWebhook::fromGlobals(
    token: $_ENV['SHIPDAY_WEBHOOK_TOKEN'] ?? null,
);

http_response_code(200);

The beta driver location webhook is supported through DriverLocationUpdated.

Testing

This package uses Pest.

composer test

Upgrade Notes From v1

The old Delivery and OnDemandDelivery classes are deprecated compatibility wrappers. New applications should use:

$shipday = Shipday::make('your-shipday-api-key');

Method names changed to a resource style. For example:

// v1
$delivery->insertOrder($payload);

// resource API
$shipday->orders()->create($payload);

License

MIT