PHPackages                             tigusigalpa/shippo-php - 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. tigusigalpa/shippo-php

ActiveLibrary[API Development](/categories/api)

tigusigalpa/shippo-php
======================

Modern PHP SDK for the Shippo API with Laravel integration

v1.0.0(3mo ago)92MITPHPPHP ^8.1CI failing

Since Feb 16Pushed 3mo agoCompare

[ Source](https://github.com/tigusigalpa/shippo-php)[ Packagist](https://packagist.org/packages/tigusigalpa/shippo-php)[ RSS](/packages/tigusigalpa-shippo-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (8)Versions (2)Used By (0)

Shippo PHP SDK
==============

[](#shippo-php-sdk)

[![Shippo PHP SDK](https://private-user-images.githubusercontent.com/2721390/550465267-2a878c70-a364-42ee-a67e-dc20d8a2f7c2.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzIwNTQyNTUsIm5iZiI6MTc3MjA1Mzk1NSwicGF0aCI6Ii8yNzIxMzkwLzU1MDQ2NTI2Ny0yYTg3OGM3MC1hMzY0LTQyZWUtYTY3ZS1kYzIwZDhhMmY3YzIuanBnP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDIyNSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjAyMjVUMjExMjM1WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9NGYxZTJhY2U2MzdmNjFhMjRmOGVjZGMxOWUyMGM2MmJlZjlmMzBiNjgwNTA4OTk4NGNkMWI0ZDI4MDYxNWMwMSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.Xf2TSG8o4tmEvL62m2Hb-J-uAajHFQgszqMDhf3cXNY)](https://private-user-images.githubusercontent.com/2721390/550465267-2a878c70-a364-42ee-a67e-dc20d8a2f7c2.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzIwNTQyNTUsIm5iZiI6MTc3MjA1Mzk1NSwicGF0aCI6Ii8yNzIxMzkwLzU1MDQ2NTI2Ny0yYTg3OGM3MC1hMzY0LTQyZWUtYTY3ZS1kYzIwZDhhMmY3YzIuanBnP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDIyNSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjAyMjVUMjExMjM1WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9NGYxZTJhY2U2MzdmNjFhMjRmOGVjZGMxOWUyMGM2MmJlZjlmMzBiNjgwNTA4OTk4NGNkMWI0ZDI4MDYxNWMwMSZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.Xf2TSG8o4tmEvL62m2Hb-J-uAajHFQgszqMDhf3cXNY)

[![Latest Version on Packagist](https://camo.githubusercontent.com/aa89eb37694de9ca53bdb9ec4570ec91c52794f7131efb371b6a16bc8b81ebd7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74696775736967616c70612f73686970706f2d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tigusigalpa/shippo-php)[![Tests](https://camo.githubusercontent.com/f0a43718da7366b7c699c4c7d946013c2bacd4a588ba3d4f1f9a63e7eb778a1c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f74696775736967616c70612f73686970706f2d7068702f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/tigusigalpa/shippo-php/actions/workflows/tests.yml)[![Total Downloads](https://camo.githubusercontent.com/6bc13b13c2e58641595741b7275ec9be6aad3b7cd9f3641a37c454236bdd7d02/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f74696775736967616c70612f73686970706f2d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tigusigalpa/shippo-php)[![License](https://camo.githubusercontent.com/058e8997dfef492fc4ea05547a56e657a0c5992f0887e6f5c3fa4e60f05b7d66/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f74696775736967616c70612f73686970706f2d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tigusigalpa/shippo-php)

A modern, PSR-compliant PHP SDK for the [Shippo API](https://goshippo.com/) with seamless Laravel integration. This library provides a developer-friendly interface for managing shipping labels, tracking, rates, and all Shippo API functionality.

Features
--------

[](#features)

- 🚀 **Modern PHP 8.1+** with strict types and readonly properties
- 📦 **PSR Compliant** - PSR-4, PSR-7, PSR-17, PSR-18
- 🎯 **Type-Safe DTOs** - Strongly-typed Data Transfer Objects for all API responses
- 🔄 **Automatic Retry Logic** - Built-in exponential backoff for rate limits
- 🎨 **Laravel Integration** - Service Provider, Facade, and auto-discovery
- ✅ **Comprehensive Tests** - Full test coverage with Pest PHP
- 📚 **Excellent Documentation** - Clear examples and PHPDoc annotations
- 🔌 **HTTP Client Agnostic** - Use any PSR-18 compatible HTTP client

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

[](#requirements)

- PHP 8.1 or higher
- Laravel 9, 10, 11, or 12 (for Laravel integration)

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

[](#installation)

Install the package via Composer:

```
composer require tigusigalpa/shippo-php
```

### Laravel Installation

[](#laravel-installation)

The package will automatically register itself via Laravel's package auto-discovery.

Publish the configuration file:

```
php artisan vendor:publish --tag=shippo-config
```

Add your Shippo API token to your `.env` file:

```
SHIPPO_API_TOKEN=your_shippo_api_token_here
SHIPPO_IS_TEST=true
```

Quick Start
-----------

[](#quick-start)

### Standalone Usage

[](#standalone-usage)

```
use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\HttpFactory;
use Tigusigalpa\Shippo\Shippo;
use Tigusigalpa\Shippo\Config;

$httpFactory = new HttpFactory();
$config = Config::make('your_api_token');

$shippo = new Shippo(
    httpClient: new GuzzleClient(),
    requestFactory: $httpFactory,
    streamFactory: $httpFactory,
    config: $config
);

// Create an address
$address = $shippo->addresses()->create([
    'name' => 'John Doe',
    'street1' => '215 Clayton St.',
    'city' => 'San Francisco',
    'state' => 'CA',
    'zip' => '94117',
    'country' => 'US',
    'phone' => '+1 555 341 9393',
    'email' => 'john@example.com',
]);

echo $address->objectId;
```

### Laravel Usage

[](#laravel-usage)

```
use Tigusigalpa\Shippo\Laravel\Facades\Shippo;

// Create a shipment and get rates
$shipment = Shippo::shipments()->create([
    'address_from' => [
        'name' => 'Sender Name',
        'street1' => '123 Main St',
        'city' => 'San Francisco',
        'state' => 'CA',
        'zip' => '94103',
        'country' => 'US',
    ],
    'address_to' => [
        'name' => 'Recipient Name',
        'street1' => '456 Oak Ave',
        'city' => 'Los Angeles',
        'state' => 'CA',
        'zip' => '90001',
        'country' => 'US',
    ],
    'parcels' => [
        [
            'length' => '5',
            'width' => '5',
            'height' => '5',
            'distance_unit' => 'in',
            'weight' => '2',
            'mass_unit' => 'lb',
        ],
    ],
]);

// Get available rates
foreach ($shipment->rates as $rate) {
    echo "{$rate['provider']} - {$rate['servicelevel_name']}: \${$rate['amount']}\n";
}
```

Usage Examples
--------------

[](#usage-examples)

### Address Validation

[](#address-validation)

```
$validatedAddress = $shippo->addresses()->validate([
    'name' => 'John Doe',
    'street1' => '215 Clayton St.',
    'city' => 'San Francisco',
    'state' => 'CA',
    'zip' => '94117',
    'country' => 'US',
]);

if ($validatedAddress->validationStatus === ValidationStatus::VALID) {
    echo "Address is valid!";
}
```

### Creating a Shipping Label

[](#creating-a-shipping-label)

```
// 1. Create a shipment
$shipment = $shippo->shipments()->create([
    'address_from' => [
        'name' => 'Your Store',
        'street1' => '123 Business St',
        'city' => 'San Francisco',
        'state' => 'CA',
        'zip' => '94103',
        'country' => 'US',
    ],
    'address_to' => [
        'name' => 'Customer Name',
        'street1' => '456 Customer Ave',
        'city' => 'Los Angeles',
        'state' => 'CA',
        'zip' => '90001',
        'country' => 'US',
    ],
    'parcels' => [
        [
            'length' => '10',
            'width' => '8',
            'height' => '4',
            'distance_unit' => 'in',
            'weight' => '5',
            'mass_unit' => 'lb',
        ],
    ],
]);

// 2. Select a rate (e.g., the cheapest one)
$rateId = $shipment->rates[0]['object_id'];

// 3. Purchase the label
$transaction = $shippo->transactions()->create([
    'rate' => $rateId,
    'label_file_type' => 'PDF',
    'async' => false,
]);

// 4. Get the label URL
echo "Label URL: {$transaction->labelUrl}\n";
echo "Tracking Number: {$transaction->trackingNumber}\n";
```

### Tracking a Package

[](#tracking-a-package)

```
$tracking = $shippo->tracking()->retrieve('usps', '9205590164917312751089');

echo "Status: {$tracking->trackingStatus}\n";
echo "ETA: {$tracking->eta}\n";

foreach ($tracking->trackingHistory as $event) {
    echo "{$event['status_date']} - {$event['status_details']}\n";
}
```

### International Shipments with Customs

[](#international-shipments-with-customs)

```
// Create customs items
$customsItem = $shippo->customs()->createItem([
    'description' => 'T-Shirt',
    'quantity' => 2,
    'net_weight' => '0.5',
    'mass_unit' => 'lb',
    'value_amount' => '20.00',
    'value_currency' => 'USD',
    'origin_country' => 'US',
]);

// Create customs declaration
$customsDeclaration = $shippo->customs()->createDeclaration([
    'contents_type' => 'MERCHANDISE',
    'contents_explanation' => 'T-Shirts',
    'non_delivery_option' => 'RETURN',
    'certify' => true,
    'certify_signer' => 'John Doe',
    'items' => [$customsItem['object_id']],
]);

// Create shipment with customs
$shipment = $shippo->shipments()->create([
    'address_from' => [...],
    'address_to' => [...],
    'parcels' => [...],
    'customs_declaration' => $customsDeclaration['object_id'],
]);
```

### Listing Addresses with Pagination

[](#listing-addresses-with-pagination)

```
$addresses = $shippo->addresses()->list([
    'results' => 25,
    'page' => 1,
]);

foreach ($addresses as $address) {
    echo "{$address->name} - {$address->city}, {$address->state}\n";
}

if ($addresses->hasMorePages()) {
    echo "More addresses available!";
}
```

### Refunding a Label

[](#refunding-a-label)

```
$refund = $shippo->refunds()->create('transaction_id_here');

echo "Refund status: {$refund['status']}\n";
```

### Batch Label Creation

[](#batch-label-creation)

```
// Create a batch
$batch = $shippo->batches()->create([
    'default_carrier_account' => 'carrier_account_id',
    'default_servicelevel_token' => 'usps_priority',
    'label_filetype' => 'PDF_4x6',
]);

// Add shipments to batch
$shippo->batches()->addShipments($batch['object_id'], [
    'shipment_id_1',
    'shipment_id_2',
    'shipment_id_3',
]);

// Purchase all labels in batch
$result = $shippo->batches()->purchase($batch['object_id']);
```

Error Handling
--------------

[](#error-handling)

The SDK provides a comprehensive exception hierarchy for granular error handling:

```
use Tigusigalpa\Shippo\Exceptions\AuthenticationException;
use Tigusigalpa\Shippo\Exceptions\RateLimitException;
use Tigusigalpa\Shippo\Exceptions\ValidationException;
use Tigusigalpa\Shippo\Exceptions\NotFoundException;
use Tigusigalpa\Shippo\Exceptions\ServerException;
use Tigusigalpa\Shippo\Exceptions\ShippoException;

try {
    $address = $shippo->addresses()->create([...]);
} catch (AuthenticationException $e) {
    // Invalid API token
    echo "Authentication failed: {$e->getMessage()}";
} catch (ValidationException $e) {
    // Invalid data provided
    echo "Validation error: {$e->getMessage()}";
    print_r($e->getResponse());
} catch (RateLimitException $e) {
    // Rate limit exceeded (automatically retried)
    echo "Rate limited. Retry after: {$e->getRetryAfter()} seconds";
} catch (NotFoundException $e) {
    // Resource not found
    echo "Not found: {$e->getMessage()}";
} catch (ServerException $e) {
    // Shippo server error
    echo "Server error: {$e->getMessage()}";
} catch (ShippoException $e) {
    // Any other Shippo error
    echo "Error: {$e->getMessage()}";
}
```

Configuration
-------------

[](#configuration)

### Standalone Configuration

[](#standalone-configuration)

```
$config = Config::make('your_api_token', [
    'api_version' => '2018-02-08',
    'base_url' => 'https://api.goshippo.com',
    'is_test' => true,
    'timeout' => 30,
    'retry_attempts' => 3,
    'retry_delay' => 1000, // milliseconds
]);
```

### Laravel Configuration

[](#laravel-configuration)

Edit `config/shippo.php`:

```
return [
    'api_token' => env('SHIPPO_API_TOKEN'),
    'api_version' => env('SHIPPO_API_VERSION', '2018-02-08'),
    'base_url' => env('SHIPPO_BASE_URL', 'https://api.goshippo.com'),
    'is_test' => env('SHIPPO_IS_TEST', false),
    'timeout' => env('SHIPPO_TIMEOUT', 30),
    'retry_attempts' => env('SHIPPO_RETRY_ATTEMPTS', 3),
    'retry_delay' => env('SHIPPO_RETRY_DELAY', 1000),
];
```

Testing
-------

[](#testing)

Run the test suite:

```
composer test
```

Run tests with coverage:

```
composer test-coverage
```

Run static analysis:

```
composer analyse
```

API Resources
-------------

[](#api-resources)

The SDK provides access to all Shippo API resources:

- **Addresses** - Create, validate, and manage addresses
- **Shipments** - Create shipments and get rates
- **Rates** - Retrieve and compare shipping rates
- **Transactions** - Purchase shipping labels
- **Tracking** - Track packages and register webhooks
- **Parcels** - Manage parcel templates
- **Customs** - Handle international shipping customs
- **Refunds** - Request label refunds
- **Manifests** - Create end-of-day manifests
- **Carrier Accounts** - Manage carrier account connections
- **Batches** - Bulk label creation
- **Orders** - Manage orders for fulfillment

Contributing
------------

[](#contributing)

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Security
--------

[](#security)

If you discover any security-related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Igor Sazonov](https://github.com/tigusigalpa)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

Resources
---------

[](#resources)

- [Shippo API Documentation](https://docs.goshippo.com/)
- [Shippo Dashboard](https://apps.goshippo.com/)
- [Package Documentation](https://github.com/tigusigalpa/shippo-php)

Changelog
---------

[](#changelog)

Please see [CHANGELOG.md](CHANGELOG.md) for recent changes.

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance82

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

91d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2721390?v=4)[Igor Sazonov](/maintainers/tigusigalpa)[@tigusigalpa](https://github.com/tigusigalpa)

---

Top Contributors

[![tigusigalpa](https://avatars.githubusercontent.com/u/2721390?v=4)](https://github.com/tigusigalpa "tigusigalpa (2 commits)")

---

Tags

apifulfillmentfulfilment-managerlaravelphpshipposhippo-apiphpapilaravelsdktrackingratesshippinglabelsshippo

###  Code Quality

TestsPest

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tigusigalpa-shippo-php/health.svg)

```
[![Health](https://phpackages.com/badges/tigusigalpa-shippo-php/health.svg)](https://phpackages.com/packages/tigusigalpa-shippo-php)
```

###  Alternatives

[openai-php/client

OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API

5.8k22.6M232](/packages/openai-php-client)[getbrevo/brevo-php

Official Brevo provided RESTFul API V3 php library

963.1M35](/packages/getbrevo-brevo-php)[gemini-api-php/client

API client for Google's Gemini API

216221.4k5](/packages/gemini-api-php-client)[mozex/anthropic-php

Anthropic PHP is a supercharged community-maintained PHP API client that allows you to interact with Anthropic API.

46365.1k13](/packages/mozex-anthropic-php)[gemini-api-php/laravel

Gemini API client for Laravel

8915.7k](/packages/gemini-api-php-laravel)[bushlanov-dev/max-bot-api-client-php

Max Bot API Client library

281.6k](/packages/bushlanov-dev-max-bot-api-client-php)

PHPackages © 2026

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