PHPackages                             sanmai/shipandco-sdk - 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. sanmai/shipandco-sdk

ActiveLibrary

sanmai/shipandco-sdk
====================

Ship&co API SDK

0.1.23(1mo ago)021.0k—8.7%2[1 PRs](https://github.com/sanmai/shipandco-sdk/pulls)MITPHPPHP ^8.2CI passing

Since Oct 12Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/sanmai/shipandco-sdk)[ Packagist](https://packagist.org/packages/sanmai/shipandco-sdk)[ GitHub Sponsors](https://github.com/sanmai)[ RSS](/packages/sanmai-shipandco-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (40)Versions (29)Used By (0)

Ship&co API integration SDK
===============================

[](#shipco-api-integration-sdk)

[![Latest Stable Version](https://camo.githubusercontent.com/6dbf02633e3d48839e1433cb2c6db3ed4ad135ce58eea3f9d956f4d2038cf836/68747470733a2f2f706f7365722e707567782e6f72672f73616e6d61692f73686970616e64636f2d73646b2f762f737461626c65)](https://packagist.org/packages/sanmai/shipandco-sdk)[![Coverage Status](https://camo.githubusercontent.com/83cd2dc3326782c1841d4142fa84ee36e9aec37c3bc954ebd28ad6e863c2c154/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f73616e6d61692f73686970616e64636f2d73646b2f62616467652e7376673f6272616e63683d6d61696e)](https://coveralls.io/github/sanmai/shipandco-sdk?branch=main)

Features:

- Shipments
    - [Create Shipment](#create-shipment)
    - List Shipments
    - Get Shipment
    - Delete Shipment
- Rate
    - [List Rates](#list-rates)
- Carrier
    - [Register Carrier](#register-carrier)
    - [List Carriers](#list-carriers)
    - Update Carrier
    - Delete Carrier
- Tracking
- Address
    - Register Address
    - [List Addresses](#list-addresses)
- Warehouse
    - Register Warehouse
    - [List Warehouses](#list-warehouses)
- Sub User
    - Register Sub User
    - List Sub User
    - Get Sub User
    - Refresh Sub User
    - Delete Sub User

This library is far from offering a complete set of API methods, but it should do the most important bits.

**Something is amiss?** [Let us know](https://github.com/sanmai/shipandco-sdk/issues/new/choose), or, even better, send a PR!

[Ship&co API documentation](https://developer.shipandco.com/en/) for your reference. Please note this is *not* in any way an official SDK of Ship&co, therefore most likely they won't be able to answer any questions about this SDK.

Installation
------------

[](#installation)

```
composer require sanmai/shipandco-sdk
```

This SDK requires at least PHP 8.2.

Overview
--------

[](#overview)

Major parts are:

- Client. Client is the object you send all requests through.
- Requests. There are several request objects for most requests the API offers. They follow a fluent interface paradigm, where if the original request has a certain property, a request here will have it too. More on this below.
- Responses. After sending a request you'll have a response object, which could be an actual response, or an error response. All responses follow the same fluent paradigm.

Usage
-----

[](#usage)

First, you need to acquire an access token [as outlined in the documentation](https://developer.shipandco.com/en/#t-auth).

Next, instantiate a client using a convenient builder:

```
$builder = new \ShipAndCoSDK\ClientBuilder();
$builder->setToken($token);

$client = $builder->build();
```

The builder has several more convenience methods to set timeouts and enable caching. Check with the source code.

### Error handling

[](#error-handling)

Error handling is built upon error responses. Exceptions are almost never thrown. If there's an exception, this has to be a truly exceptional situation, even a bug.

```
$request = new \ShipAndCoSDK\Requests\RatesRequest();

// This requests requires several properties to be set, therefore we'll have an error here.
$response = $client->sendRatesRequest($request);

if (\count($response) > 0) {
    // Will not be printed because count() is zero here.
    echo 'Rates received: ', \count($response), "\n";
}

if ($response->hasErrors()) {
    // Check for exact errors
    foreach ($response->getMessages() as $message) {
        if ($message->getErrorCode() !== '') {
            // That's the error:
            echo "{$message->getErrorCode()}: {$message->getMessage()}\n";
        }
    }

    /** @var \ShipAndCoSDK\Responses\Bad\ErrorResponse $response */

    // To get more specific error details use response-specific fields. E.g.:
    foreach ($response->details as $detail) {
        echo "Error code: {$detail->code}\n\tMessage: {$detail->message}\n\tField: {$detail->field}\n";
    }
}
```

### Requests

[](#requests)

For every implemented request [there's a runnable example](examples). E.g. running this:

```
export SHIPANDCO_ACCESS_TOKEN=... (your token)
php examples/030_CarriersRequest.php
```

...Will output your registered carriers.

Examples come with a debugging output enabled so that you can experiment freely.

Obviously, to run examples you'll need to have the library checked out:

```
git clone https://github.com/sanmai/shipandco-sdk.git
cd shipandco-sdk
composer install
```

#### List Carriers

[](#list-carriers)

```
$request = new \ShipAndCoSDK\Requests\CarriersRequest();

$response = $client->sendCarriersRequest($request);

\var_dump(\count($response)); // Should print the number of configured carriers

foreach ($response as $value) {
    echo "{$value->id}\t{$value->type}\t{$value->state}\t{$value->created_at->format('Y-m-d')}\n";

    foreach ($value->credentials as $key => $value) {
        echo "\t$key =\t$value\n";
    }
}
```

#### Register Carrier

[](#register-carrier)

```
$request = new \ShipAndCoSDK\Requests\RegisterCarrierRequest();

// Example: Register DHL carrier
$request->type = 'dhl';
$request->credentials->account_number = '123456789';
$request->credentials->site_id = 'YOUR_DHL_SITE_ID';
$request->credentials->password = 'YOUR_DHL_PASSWORD';
$request->credentials->address->company = 'Your Company Name';
$request->credentials->address->phone = '08012345678';
$request->credentials->address->email = 'your@email.com';
$request->credentials->address->address1 = 'Your Address';
$request->credentials->address->zip = '1234567';
$request->credentials->address->city = 'Your City';
$request->credentials->address->country = 'JP';

$request->settings->print->size = 'PDF_A4';

$response = $client->sendRegisterCarrierRequest($request);

if ($response->hasErrors()) {
    foreach ($response->getMessages() as $message) {
        if ($message->getErrorCode() !== '') {
            echo "{$message->getErrorCode()}: {$message->getMessage()}\n";
        }
    }
    return;
}

echo "Carrier registered: {$response->id}\n";
echo "Type: {$response->type}, State: {$response->state}\n";
```

Different carriers require different credentials. For FedEx, you'll need to set `invoice_2fa` and provide all address fields. See the [runnable example](examples/035_RegisterCarrierRequest.php) for more details.

#### List Addresses

[](#list-addresses)

```
$request = new \ShipAndCoSDK\Requests\AddressesRequest();

$response = $client->sendAddressesRequest($request);

\var_dump(\count($response)); // Should print the number of addresses returned

foreach ($response as $value) {
    echo "{$value->id}\t{$value->created_at->format('Y-m-d')}\n";

    foreach ($value->address as $key => $value) {
        echo "\t$key =\t$value\n";
    }
}
```

#### List Warehouses

[](#list-warehouses)

```
$request = new \ShipAndCoSDK\Requests\WarehousesRequest();

$response = $client->sendWarehousesRequest($request);

\var_dump(\count($response)); // Should print the number of warehouses returned

foreach ($response as $value) {
    echo "{$value->id}\t{$value->created_at->format('Y-m-d')}\t{$value->company}\n";

    foreach ($value->address as $key => $value) {
        echo "\t$key =\t$value\n";
    }
}
```

#### List Rates

[](#list-rates)

```
$request = new \ShipAndCoSDK\Requests\RatesRequest();

$request->from_address->country = 'JP';
$request->from_address->full_name = 'Yamada Taro';
$request->from_address->company = 'World Company';
$request->from_address->email = 'ytaro@example.com';
$request->from_address->phone = '08012341234';
$request->from_address->country = 'JP';
$request->from_address->address1 = 'OSAKAFU';
$request->from_address->address2 = 'OTECHO';
$request->from_address->province = 'OSAKA';
$request->from_address->zip = '5670883';
$request->from_address->city = 'IBARAKI SHI';

$request->to_address->full_name = 'John Doe';
$request->to_address->company = 'ACME';
$request->to_address->email = 'john@example.net';
$request->to_address->phone = '0901231234';
$request->to_address->country = 'PT';
$request->to_address->address1 = 'Rua Maria Matos, 32';
$request->to_address->address2 = '';
$request->to_address->province = 'SETUBAL';
$request->to_address->zip = '2820-344';
$request->to_address->city = 'CHARNECA DA CAPARICA';

$product = $request->addProduct();
$product->quantity = 1;
$product->name = 'Example';
$product->price = 1000;

$parcel = $request->addParcel();
$parcel->weight = 200;
$parcel->width = 10;
$parcel->height = 10;
$parcel->depth = 10;

$request->customs->duty_paid = false;
$request->customs->content_type = 'MERCHANDISE';

$request->setup->date = new DateTime('+1 week');

$response = $client->sendRatesRequest($request);

\var_dump(\count($response));

foreach ($response as $rate) {
    echo "{$rate->carrier}\t{$rate->service}\t{$rate->price} {$rate->currency}\n";

    foreach ($rate->surcharges as $surcharge) {
        echo "\t{$surcharge->type}\t{$surcharge->price}\n";
    }
}
```

#### Create Shipment

[](#create-shipment)

As far as shipments go, it's important to understand that requests for domestic shipments over Japan (Sagawa, Yamato, YuPack) are a bit different from an International shipments:

- For domestic shipments addresses (to and from) should be in Japanese. The opposite is true for International shipments.
- No city field is needed for domestic shipments (city goes to `address_1`).
- No need for most details about product: on the contrary, for International shipments, details about products are used for customs clearance purpose.
- For domestic shipments, if it's not a cash on delivery shipment, product name only should work (just to show on the label whats inside the box).

This SDK poses no restrictions on the number of fields specified in a request (other than that they should exist), thus it is a user responsibility (yours) to set correct fields for each type of request.

```
$request = new \ShipAndCoSDK\Requests\CreateShipmentRequest();

$request->to_address->country = 'JP';
$request->to_address->full_name = 'TEST TARO';
$request->to_address->phone = '1111111111';
$request->to_address->country = 'JP';
$request->to_address->address1 = '京都市中京区八百屋町117';
$request->to_address->zip = '604-8072';
$request->to_address->city = '京都府';

$request->from_address->full_name = 'テスト';
$request->from_address->phone = '08012341234';
$request->from_address->country = 'JP';
$request->from_address->address1 = 'OSAKAFU';
$request->from_address->province = 'OSAKA';
$request->from_address->zip = '1234567';
$request->from_address->city = 'IBARAKI SHI';

$product = $request->addProduct();
$product->name = 'Blue Basketball';
$product->quantity = 2;
$product->price = 4850;
$product->origin_country = 'JP';

$product = $request->addProduct();
$product->name = 'Orange Basketball';
$product->quantity = 1;
$product->price = 7850;
$product->origin_country = 'JP';

$parcel = $request->addParcel();
$parcel->amount = 1; // That's the default.
$parcel->weight = 2000;
$parcel->width = 10;
$parcel->height = 10;
$parcel->depth = 10;
// $parcel->package = 'fedex_envelope';

$request->customs->duty_paid = false;
$request->customs->content_type = 'MERCHANDISE';

$request->setup->carrier = 'sagawa';
$request->setup->service = 'sagawa_regular';
$request->setup->currency = 'JPY';
$request->setup->shipment_date = new DateTime('+1 day');
$request->setup->date = new DateTime('+2 day');
$request->setup->time = '16-18';
$request->setup->insurance = 0;
$request->setup->ref_number = '';
$request->setup->delivery_note = '';
$request->setup->signature = false;
$request->setup->care->fragile = false;
$request->setup->care->side_up = false;
$request->setup->care->valuable_goods = false;
$request->setup->pack_size = '0';
$request->setup->pack_amount = 3;
$request->setup->cash_on_delivery->amount = 1000;
$request->setup->cash_on_delivery->tax = 100;
$request->setup->return_label = false;
$request->setup->print_start_location = 1;
$request->setup->test = true;

$response = $client->sendCreateShipmentRequest($request);

if ($response->hasErrors()) {
    // Check for exact errors
    foreach ($response->getMessages() as $message) {
        if ($message->getErrorCode() !== '') {
            // That's the error
            echo "{$message->getErrorCode()}: {$message->getMessage()}\n";
        }
    }

    return; // This is a failure.
}

/** @var $response \ShipAndCoSDK\Responses\ShipmentResponse */
echo "{$response->id}\t{$response->state}\n";

echo "Shipping Label: {$response->delivery->label}\n";

foreach ($response->delivery->tracking_numbers as $trackingNumber) {
    echo "Tracking Number: {$trackingNumber}\n";
}
```

To safeguard you against unexpected billing charges, shipment requests are [using the test environment](https://developer.shipandco.com/en/#t-ship_post) *by default* (thus creating dummy labels). Make sure to set `test` to `false` in `setup` section to receive live labels.

Just like so:

```
$request->setup->test = false;
```

License
-------

[](#license)

This project is licensed [under the terms of the MIT license](LICENSE).

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance87

Actively maintained with recent releases

Popularity28

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 71% 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 ~90 days

Recently: every ~36 days

Total

23

Last Release

54d ago

PHP version history (3 changes)0.1PHP ^7.3 || ^8.0

0.1.9PHP ^7.4 || ^8.0

0.1.17PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/edcb8dde95c71b1c97c3c91e57d3548795fa2014c657744fb878e2be3b5949fc?d=identicon)[sanmai](/maintainers/sanmai)

---

Top Contributors

[![sanmai](https://avatars.githubusercontent.com/u/139488?v=4)](https://github.com/sanmai "sanmai (66 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (22 commits)")[![gtrbunny](https://avatars.githubusercontent.com/u/779284?v=4)](https://github.com/gtrbunny "gtrbunny (5 commits)")

---

Tags

carrierfedexphpphp-libraryregistered-carrierssagawasdkshipshipmentsyamatoyupackphp-sdkdeliveryshipping provider

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/sanmai-shipandco-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/sanmai-shipandco-sdk/health.svg)](https://phpackages.com/packages/sanmai-shipandco-sdk)
```

###  Alternatives

[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[concrete5/core

Concrete core subtree split

19159.3k48](/packages/concrete5-core)[open-dxp/opendxp

Content & Product Management Framework (CMS/PIM)

7310.3k29](/packages/open-dxp-opendxp)[cdek-it/sdk2.0

PHP SDK для API v2.0 от сервиса интеграции компании СДЭК

3992.9k](/packages/cdek-it-sdk20)[appwilio/cdek-sdk

CDEK API SDK (cdek.ru)

406.5k](/packages/appwilio-cdek-sdk)[mapado/rest-client-sdk

Rest Client SDK for hydra API

1125.9k2](/packages/mapado-rest-client-sdk)

PHPackages © 2026

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