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
truerequests are logged. Whenfalseor nonexistent requests are not logged. - SHIPTHEORY_PHP_SSL_VERIFY_PEER - (Boolean) When set to
trueSSL verification is enabled. Whenfalseor 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.
"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.
$client = new ShiptheoryClient('test@test.com', 'Password123!');
$result = $client->viewShipment('Test1234')$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();
$client->listShipment($params);$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();
$client->searchShipment($params);$client = new ShiptheoryClient('test@test.com', 'Password123!');
//Start new shipment data object
$shipment = new Shipment();
$shipment->setReference('Test1234');
$shipment->setReference2('Test5678');
// Set Shipment Details
$shipment_detail = new ShipmentDetail();
$shipment_detail->setWeight(1);
$shipment_detail->setParcels(1);
$shipment_detail->setValue(1);
$shipment_detail->setShippingPrice(2.99);
$shipment_detail->setReference3('ORDERREF3');
$shipment_detail->setSalesSource('My Store');
$shipment_detail->setShipDate('2022-04-30');
$shipment_detail->setCurrencyCode('GBP');
// Set Recipient
$reciever = new Recipient();
$reciever->setCompany('Shiptheory');
$reciever->setFirstname('Test');
$reciever->setLastname('Customer');
$reciever->setAddressLine1('Unit 4.1 Paintworks');
$reciever->setAddressLine2('Bath Road');
$reciever->setCity('Bristol');
$reciever->setCountry('GB');
$reciever->setPostcode('BS4 3EH');
$reciever->setEmail('recipient@test.com');
$reciever->setTelephone('01234567890');
$reciever->setWhat3Words('///what.three.words');
$eori = new TaxNumber('GB205672212000', AddressTaxNumberTypes::EORI);
$vat = new TaxNumber('GB123456789', AddressTaxNumberTypes::VAT);
$reciever->setTaxNumbers([$eori, $vat]);
// Set sender
$sender = new Sender();
$sender->setCompany('Shiptheory');
$sender->setFirstname('Test');
$sender->setLastname('Shipper');
$sender->setAddressLine1('Bristol Old Vic');
$sender->setAddressLine2('King Street');
$sender->setCity('Bristol');
$sender->setCountry('GB');
$sender->setPostcode('BS1 4ED');
$sender->setEmail('sender@test.com');
$sender->setTelephone('01234567890');
// Set Product
$product = new Product();
$product->setName('My Test Product');
$product->setSku('TestProd1');
$product->setQty(1);
$product->setValue(1);
$product->setWeight(1);
$product->setCommodityCode('8443991000');
$product->setCommodityManucountry('PL');
// Add all elements to the shipment
$shipment->setShipmentDetail($shipment_detail);
$shipment->setRecipient($reciever);
$shipment->setSender($sender);
$shipment->setProducts([$product]);
// Send shipment to Shiptheory
$data = $shipment->toJson(true);
$result = $client->bookShipment($data);