An API client to communicate with the Shiptheory API

v2.2.1 2023-01-26 16:16 UTC

This package is auto-updated.

Last update: 2024-07-07 16:21:45 UTC


Shiptheory API library for PHP

A Python version exists: Shiptheory API library for Python

  • To create pull requests fork this repository (Please adhere to the guidelines in the pull request template).
  • Use GitHub issues to detail any problems encountered.


  • Build Shiptheory request bodies and queries with ease.
  • Dedicated methods to query each Shiptheory endpoint.
  • Automatic token authentication. Just provide your credentials and the library will keep your tokens valid for as long as you need.
  • Standardised error messaging.
  • Configuration via .env


Require with composer:

composer require dan-rogers/shiptheory-php


The library currently utilises a .env file to configure certain aspects of the library.

IMPORTANT: It does not use any version of phpdotenv and instead uses its own custom implementation to keep it lightweight.

Copy values from .env.example into a new or existing .env file in the root of your project.

Currently supported configuration options:

  • SHIPTHEORY_PHP_LOG_REQUESTS - (Boolean) When set to true requests are logged. When false or nonexistent requests are not logged.
  • SHIPTHEORY_PHP_SSL_VERIFY_PEER - (Boolean) When set to true SSL verification is enabled. When false or nonexistent requests do not use SSL verification.
  • SHIPTHEORY_PHP_LOG_PATH - (String) When a string is set it is used as the path to the folder where log files are generated.

Using a Shiptheory Partner Tag

"If you are developing an application that will be used by more than 1 company, or an application that you intend to distribute in anyway, you must include the Shiptheory-Partner-Tag http request header in all of your requests. Please contact Shiptheory support to obtain a partner tag. There is no charge for this, tags are used to provide better support to customers and partners." - API Docs

In order to add a partner tag to your API requests add it as the third argument when instantiating a new ShiptheoryClient.

$client = new ShiptheoryClient('test@test.com', 'Password123!', 'my_partner_tag');


The workflow is similar for all endpoints, queries and bookings. Examples exist in the file Examples. If you want to see all endpoint methods, then look in src/Http/ShiptheoryClient.php.

It is recommended that you use the objects provied to build your requests as they will result with a perfect request body every time. However, if you wish you can just provide the query parameters or the JSON body (depending on request type) as a string to the method you are calling.

Example of viewing a shipment

$client = new ShiptheoryClient('test@test.com', 'Password123!');
$result = $client->viewShipment('Test1234')

Example of listing shipments

$client = new ShiptheoryClient('test@test.com', 'Password123!');
$list_fields = [
    'channel_name' => 'Api',
    'status' => 'Ignored',
    'limit' => 1
$list_query = new ListShipmentQuery($list_fields);
$params = $list_query->toQueryParams();

Example of searching for shipments

$client = new ShiptheoryClient('test@test.com', 'Password123!');
$search_fields = [
    'created_from' => '2022-04-01',
    'created_to' => '2022-04-30',
    'include_products' => 1,
$search_query = new SearchShipmentQuery($search_fields);
$params = $search_query->toQueryParams();

Example of booking a shipment

$client = new ShiptheoryClient('test@test.com', 'Password123!');
//Start new shipment data object
$shipment = new Shipment();

// Set Shipment Details
$shipment_detail = new ShipmentDetail();
$shipment_detail->setSalesSource('My Store');

// Set Recipient
$reciever = new Recipient();
$reciever->setAddressLine1('Unit 4.1 Paintworks');
$reciever->setAddressLine2('Bath Road');
$reciever->setPostcode('BS4 3EH');
$eori = new TaxNumber('GB205672212000', AddressTaxNumberTypes::EORI);
$vat = new TaxNumber('GB123456789', AddressTaxNumberTypes::VAT);
$reciever->setTaxNumbers([$eori, $vat]);

// Set sender
$sender = new Sender();
$sender->setAddressLine1('Bristol Old Vic');
$sender->setAddressLine2('King Street');
$sender->setPostcode('BS1 4ED');

// Set Product
$product = new Product();
$product->setName('My Test Product');

// Add all elements to the shipment

// Send shipment to Shiptheory
$data = $shipment->toJson(true);
$result = $client->bookShipment($data);