Connecting to the EasyPost API

EasyPost is a logistics platform that provides unique tools and a convenient API for automating and optimizing the shipping and tracking processes of shipments. Its history began in 2012, and today EasyPost holds a leading position among providers of efficient logistics solutions, serving numerous business industries.

One of the key advantages of the EasyPost API is the ability for companies to access a diverse range of carriers and choose the best delivery options for their shipments. EasyPost offers comprehensive functionality with a multitude of features, which we will describe below.

The primary advantages of using EasyPost include:

• EasyPost's API is a convenient way to obtain accurate shipping cost calculations on your website. Customers or managers can easily view the shipping cost and choose the best option immediately.
• With EasyPost, you can easily create and print labels for your shipments, saving time and simplifying the process of preparing your packages for shipping. This leads to increased operational efficiency.
• EasyPost's integration with various popular carriers like FedEx, DHL, USPS, UPS, APC, and others ensures flexibility and reliability in shipping by providing access to multiple delivery options.
• Utilizing EasyPost's tracking API, you and your customers can receive real-time updates on the delivery status, ensuring transparency and building trust in your business, ultimately enhancing customer satisfaction.
• EasyPost offers the option to insure shipments to protect them from losses or damages during delivery. This feature ensures the safety of shipping and gives customers peace of mind.

Example of EasyPost API integration

For the most widely used programming languages, EasyPost provides SDKs. So, if you are using PHP, you can install the corresponding package with the following command:

composer require EasyPost/EasyPost-php

EasyPost uses only one parameter — the API key — to sign requests. Before starting to work with the client code, you need to first import EasyPost:

use EasyPost;

All classes are located within the name space EasyPost, so to set up the API key for signing requests, you need to do the following:

EasyPost\EasyPost::setApiKey($apiKey);

Now you can perform various requests, for example, to create an address. Some systems, like ShipStation, may dynamically accept only the recipient's address, while the sender's address is taken from the account settings. In the case of EasyPost, you need to provide both addresses. Let's assume that your system already has an entity called "order" with fields responsible for the delivery address. In this case, the code for saving the address in EasyPost will look like this:

$receiverAddress = EasyPost\Address::create([
   'verify' => ['delivery'],
   'company' => $order->getCompany(),
   'street1' => $order->getStreet(),
   'street2' => $order->getHouseNumber(),
   'city' => $order->getCity(),
    'state' => $order->getUserState(),
   'zip' => $order->getZip(),
    'phone' => $order->getUserPhone(),
    'email' => $order->getEmail(),
    'country' => $order->getCountryCode(),
]);

As a result, in the response, we will receive the same array with additional fields, including "id" - the address identifier in the EasyPost system, "verifications" - an array of address verification results, and others. Similarly, you need to specify and save the sender's address in the variable $senderAddress.

Now, let's take a look at how to create the shipment itself:

$parcel = EasyPost\Parcel::create([
    'weight' => $order->getWeight(),
    'height' => $order->getHeight(),
   'width' => $order->getWidth(),
   'length' => $order->getLength(),
]);

We have three variables: $receiverAddress, $senderAddress, and $parcel. They represent instances of the EasyPost\Address and EasyPost\Parcel classes, respectively. The EasyPost package automatically encodes and decodes data into JSON format, so objects can be passed in arrays. For example, when we are ready to create a shipment, we need to pass all the retrieved objects to the method for its creation:

$shipment = EasyPost\Shipment::create([
    "to_address" => $fromAddress,
    "from_address" => $toAddress,
    "parcel" => $parcel,
    "options" => [
    "label_format" => 'PDF'
    ],
]);

If everything is fine, then in the "rates" field of the $shipment object, there will be an array of objects containing information about various delivery services. Let's assume that one of the carriers suits us, for example, USPS with the lowest shipping cost, and we want to purchase a label for this service and obtain a PDF file for printing. In this case, we need to pass the following value to the "buy" method of the $shipment object:

$shipment->buy($shipment->lowest_rate(['USPS']));

The "lowest_rate" method will find the cheapest delivery method among all the available ones. By default, the system provides a list of delivery methods for USPS until you connect the corresponding service. However, to create labels, you need to activate this service. Even if you are trying to get a USPS label, you must connect it beforehand.

Since all our objects have unique identifiers in the EasyPost system, we can save these identifiers and later retrieve information about the objects directly from EasyPost using the "retrieve" method for each of the mentioned classes: EasyPost\Shipment, EasyPost\Address, and EasyPost\Parcel. Additionally, EasyPost provides the option to create all four entities in one request by passing a multidimensional array to the create method of the EasyPost\Shipment class. For example, the "to_address" key will contain an array of recipient address data, and so on. However, the method described above allows for more flexible handling of validation errors that may arise.

Regarding validation, the EasyPost SDK handles errors automatically and generates exceptions that the client code developer will need to handle. However, error messages returned by the EasyPost server may not always be clear and may only contain information about invalid data for the entity being saved.