Skip to main content

​
Concepts and Terminology

Throughout this guide we will be using a number of terms that may not be familiar to you. We have provided a glossary of terms to help you understand the concepts and terminology used in this guide.

​
Address Validation

Address validation is necessary to ensure items will be processed correctly by the carrier and not rejected, returned to sender, or cause excess postage fees upon delivery. It is important to validate both the origin and destination addressed. The typical place for this to be done for optimal user experience for the merchants is to create their mailing address in a shipping administration section of the platform. Similarly for the buyers, it is best to validate addresses when they are filling out their shipping address. Otherwise, the merchant could experience a scenario where they attempt to print a label for an order, and the address validation fails at that point, preventing a label from being generated. This causes inefficiencies in the merchant workflow and can be easily avoided by validating the addresses well ahead of time.

​
Rate Shopping

A partner can offer sellers an advantage in the market by providing more accurate shipping rates at the time of checkout. Once an order has been created, merchants are going to want to choose a shipping service and carrier that meets their requirements for speed and cost. Rate shopping is the act of calling the Shippo /shipments endpoint and examining the object in the returned rates array. Each of these objects represents a unique carrier and service level combination and allows the merchant to select which of these options is optimal for an individual order. Once a rate has been selected that rate can be purchased using the /transactions endpoint.

​
Label Purchase

Once a merchant has made a decision on a rate, the next logical step is to print the label. The label is created by passing the rate’s object_id to the /transactions endpoint. A label URL will be returned in the transaction response which can be surfaced to the merchant for download. An important thing to consider here is allowing your merchants full access to the available label formats. These are described in the API reference below for the /transactions endpoint, but partners will need a place for the user to configure their shipping settings. Since label purchase is a call from the partner’s platform to Shippo, and (usually) from Shippo to the chosen carrier who creates the label, there is a negligible latency in the creation of labels. As such, partners should consider using the async:true flag in the POST request to /transactions wherever possible to prevent a block in the workflow. An asynchronous request is acknowledged immediately by Shippo and the transaction_created webhook is triggered once the label has been generated by the carrier and passed to Shippo.

​
Refund a label

Mistakes happen and sometimes you need to generate a new label for a shipment. The /refunds endpoint allows a merchant to have an “oops” button when they need one. This is typically added wherever a user would manage orders.

​
Connect Carrier Accounts

As partners are looking to allow their users to add their own carrier accounts, you will need to implement this endpoint. There will need to be a form built for each carrier as they all require different information to connect an account to Shippo. Our documentation is exceptional on this, and for inspiration on building the carrier connection forms, we recommend you look at your version of the Shippo app to see how we configure the ability to add carrier accounts. The most important part of this process is to capture the returned object_id of the carrier account that has been created. That object id is specific to the merchant who has added their account into a partner’s system and should be stored in your database where you can access it later for rate shopping for this merchant. Details of how to implement this are below in the /transaction endpoints section.

​
Tracking Information

Tracking information can be conveyed in several ways depending on the partner’s desire to build. We recommend using Shippo’s API to create a post-purchase solution in the partner interface where your merchants and buyers can see the status of their orders in the same place the purchase was made. The reality is partners should control the tracking experience, and you don’t want someone to buy on your platform without being able to know where the order is. The simplest way is to pass the tracking information back to the merchant and consumer via the tracking_label_provider field returned in a /transaction POST response. This field returns a URL to the carrier’s tracking page for the tracking number on the label that was generated with the /transaction call. The other common way to handle this is to use webhooks to subscribe to the track_updated event. We will post updates on a shipment’s tracking status to the endpoint you provide us in your webhook configuration (done inside the Shippo app). Documentation on webhooks can be found here.

​
Returns

Returning an object is commonly done in two ways: either a return label is placed inside the box when a merchant ships an order, or a label is provided to the customer on demand. If the former option is desired, a scan-based return label is generated according to the guide here. Note, this is for a USPS scan based return label only, for the other carriers, returns should be handled by creating a standard (known as an outbound label) label with the addresses reversed from the initial merchant shipment. The rest of the information on the shipment can be considered to be the same, however.

​
Manifests

Manifests and USPS SCAN forms allow merchants to create a single piece of paper they can hand to the carrier at pickup time. The Manifest has a list of all the packages the carrier is going to be picking up that day and greatly speeds up the process of the carrier accepting each of the day’s packages.

​
Webhooks

Webhooks can be configured to deliver information on six different event types: all, transaction_created, transaction_updated, track_updated, batch_created, and batch_purchased. The guide for working with webhooks can be found here.

​
Metadata

There is a metadata field on every resource that is part of the Shippo API. This field is limited to text data with a max length of 100 characters. It is useful for helping to cross-link objects like shipments, rates, and transactions to other associated data living in the user’s adjacent systems. For example, an e-commerce platform user may want to tag the transaction object with the order number from their OMS. Or, a 3PL user may want to note which warehouse a shipment is associated with. There are an infinite number of possibilities here, and we encourage you to use this field for whatever you need it for!