In order for your application to consume all the data available from one of these endpoints, it’s important to understand what pagination is, why we use it in some of ShipEngine’s API endpoints, and what you need to do in order for your application to consume all the data.

What is Pagination?

Pagination is simply a way to break up the results from an API call into smaller chunks that your application can request individually. ShipEngine API uses page-based pagination, and the marker used to request the next batch of results is referred to as a page. You can think of it as a book with multiple numbered pages where each page of the book contains a portion of the book as a whole.  

So how does a book with multiple pages relate to an application consuming a paginated API? Think of a time when you’ve shopped online and flipped through pages and pages of a particular category. We’ll use this screenshot to jog your memory.

You may recall seeing something similar to the drop-down box in green in the screenshot above. This box allows you to either select a specific page from the drop-down or click the right-hand arrow to simply advance to the next page. Once you land on any page other than the first page, an arrow will also appear on the left that allows you to navigate backward. 

This is pagination. You can bet that the websites you use for online shopping are calling an API to populate their inventory. When you select a specific page or click the arrow to advance to the next page, the website makes an API request in real-time to gather data for that page. 

Another aspect of pagination is the page size. You can see an example of this in the red box in the screenshot above. In this case, there are 60 items per page. But we could change the value to 120 to see double the number of items per page. This is known as the page size. A larger page size means fewer calls to the API endpoint, but it also means twice the amount of data will be returned from a single API call. 

The Importance of Paginating API Calls

Using the example above, we would have received 7,980 products without the use of pagination (133 pages times 60 items per page). Now, imagine that you have created hundreds of thousands of labels using ShipEngine API. Without pagination, your request to list labels will return a large amount of data, some of which may not even be useful to you in that particular moment. 

Not only is this an unmanageable amount of data for your application, but it can also slow the API and decrease performance for all users. Executing a query against ShipEngine API’s database that returns hundreds of thousands of labels requires more processing time than requesting a single page of labels. 

Paginating results for endpoints that return a list or collection of items makes it easier for your application to work with the data as well as to ensure optimal performance of ShipEngine API.  

How to Implement Pagination in ShipEngine?

The endpoints that use pagination in ShipEngine API return a response similar to the sample response below. The items in the first page of data have been removed from the example for brevity. 

...
  "total": 95,
   "page": 1,
   "pages": 4,
   "links": {
       "first": {
           "href": "https://api-stage.shipengine.com/v1/labels?page=1&page_size=25"
       },
       "last": {
           "href": "https://api-stage.shipengine.com/v1/labels?page=4&page_size=25"
       },
       "prev": {},
       "next": {
           "href": "https://api-stage.shipengine.com/v1/labels?page=2&page_size=25"
       }
   }

This paginated response includes the following details:

• The total number of labels – 95 
• The page that was returned – 1 
• The total number of pages – 4 
• A link to the first page of results in links.first.href 
• A link to the last page of results in links.last.href 
• A link to the previous page of results in prev, which is empty since we are on the first page of results
• A link to the next page of results in next.href

To understand how to use pagination in ShipEngine API, let’s look at the URLs used to retrieve the first, next, previous, and last page in the example above. These URLs include two URL query parameters;

• page, and 
• page_size 

These links are convenience links to help you access those pages easily. When you call the endpoint from your application, you will use those same query parameters to indicate the page you would like to retrieve as well as the page_size. You can also eliminate the page_size parameter and it will use the default value of 25 items per page. 

Best Practice: Filtering Pagination Results 

Some ShipEngine API endpoints return a list or collection of items, and these endpoints use pagination to keep the results manageable. The total number of items is only going to continue to grow over time, so the total number of pages is also going to increase over time. At some point, the number of pages themselves may become unmanageable.

You should use URL query parameters in your request to filter the items up front and reduce the total number of pages in your response. 

For example, when you list labels, you can ask for labels for a particular warehouse or carrier or those created during a specific time period. The response will now contain only those labels that match the criteria you specified, resulting in fewer pages for your application to consume, and giving you only the labels you really care about in the first place. 

If you have never used pagination and URL query parameters before, our docs and code samples on Github will help you get started. Get a free API key to start building (and paginating) with ShipEngine.

The post Understanding Pagination, and Best Practices for ShipEngine APIs appeared first on Shipstation API.

Scanning a barcode on a manifest allows the carrier to process many shipments at once. Without a manifest, the carrier would need to scan each package individually. When picking up thousands of packages from a warehouse, scanning a manifest is far more efficient than scanning each individual package.

While ShipEngine uses the term manifest, some carriers use other terminology for their manifests, such as:

• Shipment Confirmation
• Shipment manifest
• SCAN form
• Order Summary
• End of Day form

If the carrier you are using requires a manifest, then you must create a manifest every day that you create labels for that carrier. In fact, some carriers, such as USPS, have a hard cutoff time of 12:00 midnight CST, which might catch you off guard if you are operating in another time zone. 

How ShipEngine Helps Generate Manifests

Some carriers require manifests in order to bill you. Others simply prefer it as a way to expedite picking up your daily shipments. Check out our docs to see which carriers require manifests. Depending on the carrier, you can also be required to provide different types of manifests, either electronic or physical. Let’s discuss how ShipEngine supports each type of manifest. 

Electronic Manifests

Some carriers require electronically submitted manifests. For these carriers, ShipEngine automatically creates and submits your manifests for you. Carriers may require an electronic manifest to be submitted before pickup so that they can better plan for the type of transportation your packages require. The size, weight, and number of packages considerably affects the space requirements for the truck that is sent to pick up your packages.

Physical Manifests

Other carriers require a physical manifest document to be provided to the driver at pickup. For these carriers, you can create your manifest by sending a POST request to the [/v1/manifests] endpoint. The request will [specify the labels to include] in the manifest, and the response will include a URL where you can download the manifest in PDF format. Then all you need to do is print the manifest and present it to the driver at pickup.

Including or Excluding Labels on a Manifest

ShipEngine gives you flexibility in specifying the labels to include in the manifest. You can explicitly specify the labels to include in the manifest or implicitly specify them by indicating the labels you don’t want to include in the manifest. 

The ability to filter the labels included in the manifest by carrier, warehouse and ship date, as well as the ability to explicitly specify the labels to include or exclude in the manifest helps avoid including a label in more than one manifest.

Creating Manifests for Large Volumes of Shipments in ShipEngine

Most carriers have a limit of 500 labels per manifest. For this reason, ShipEngine automatically splits the specified labels, or the labels that match the specified criteria, into multiple manifests. The response from the API will include an array of manifests, even if your request results in only one manifest.

You can find out whether or not your carrier requires a manifest, as well as whether or not they support electronically submitted manifests or require a physical manifest document. If your carrier does require a manifest, don’t worry! Our guide on creating a manifest and our code sample on GitHub will get you started.

The post What is a Manifest? appeared first on Shipstation API.

What Is a 429 Error? 

When using ShipEngine to perform actions and automations in your fulfillment workflow, you are making individual calls to our API, in which an HTTP client sends a request to an HTTP server, which then sends back a response containing the requested data, or “resource”.

429 errors are generated when too many requests are made from the HTTP client to the server that hosts ShipEngine. Specifically, more than 100 API calls per minute will generate a 429 error in your response code. This mostly comes into play when a high-volume business creates GET posts for tracking events, since the API is often 

The solution?

Enabling Rate Limits in ShipEnigne

There are several reasons why rate limiting is beneficial:

• It helps us ensure the integrity of our product
• It helps protect against and alert us to cyber attacks
• It helps us maintain the speed and reliability of the API 

By placing rate limits on our API, we are able to ensure that all of our users have a great experience with the ShipEngine product, and reduce the chances of the ShipEngine server becoming overloaded. 

The Trick to Preventing Repetitive 429 Errors 

Your dedicated ShipEngine account manager can help you authorize rate limit increases to a certain extent. However, if you are experiencing consistent 429 errors, we suggest building an Axios plugin on top of your ShipEngine integration to intercept the failed requests and retry them programmatically.

Our Developer Experience engineers have provided an axios-retry code sample in our GitHub repository to help your development team with constructing and customizing this plugin for your ecommerce needs. 

Visit our comprehensive API docs for more information on how to apply these code samples within ShipEngine. 

If you’re experiencing trouble while attempting to resolve 429 errors in ShipEngine, we encourage you to submit a support ticket so our team can help you determine the best solution. 

The post Understanding 429 Errors & The Trick To Getting Around Rate Limits in ShipEngine appeared first on Shipstation API.

One reason a shipping API can be so beneficial is that it provides a consistent protocol for various platforms and softwares to “speak” to one another.

But, there are additional methods you can use to automate the flow of data to and from your API. Webhooks are an increasingly popular use case among developers, due to their potential applications and ease of implementation. 

In this post, we’ll demonstrate how to use tracking webhooks to fuel real-time tracking notifications for your customers in an effort to improve their overall fulfillment experience. But, first, for those who aren’t familiar, let’s dive into what a webhook is and how webhooks can help optimize and automate your logistics processes. 

What is a Webhook? 

By definition, a webhook is a user-defined HTTP callback triggered by a specified event. 

Webhooks are much like push notifications from an app on your phone. Say you’re out running errands and you happen to stop near a Walgreens or Starbucks. Your GPS location triggers the app to send a prompt to your phone asking if you want to open the app to scan your loyalty barcode. Webhooks are also similar to RSS feeds, automatically pulling your favorite blogs and news into one spot.

Webhooks are custom callbacks with automated messages sent from other applications and platforms when a requested event takes place. They communicate the payload (or requested data) from one source to a specified URL. The only other way to fetch this data between applications is through polling. 

Polling vs. Webhooks

Before we get into the specific differences, let’s describe a scenario most have likely experienced as a consumer. You ordered a new product, and the seller has sent the confirmation email with a link to track the shipment. Anxiously awaiting your package, you return to the link daily to re-check the progress — perhaps even keeping a tab open in your browser so you can refresh the tracking link frequently. With each refresh, you are essentially polling the carrier API to request updates on your package. 

Polling and webhooks are both capable of retrieving the same data from an API. But the biggest difference is that there are typically limits on polling an API transaction. If you’ve ever received a 429 error while shipping and tracking packages in high volumes, it’s likely that you were making too many polling calls to the API. Not to mention, polling is either a very manual process or incredibly labor-intensive for developers to automate on the backend. 

A webhook simply subscribes you to the new calls and responses relevant to your request. With added real-time capability and the ease of implementation, webhooks provide a significant edge over traditional API polling. 

What Are The Benefits of a Tracking Webhook? 

Since webhooks allow the ShipEngine servers to contact your servers directly, they are a popular solution for many of our ecommerce users who are looking for a way to trigger real-time tracking push notifications to their customers. This gives them the power to create a better fulfillment experience by providing real-time visibility on where a customer’s order is, all in a branded tracking environment. 

It also creates a wealth of opportunities when it comes to innovative ways to improve your processes and workflows throughout the order lifecycle. By building out what is known as a “Webhook listener,” your integrations developer can create a number of trigger processes through a tracking event webhook. See the next section for examples.

Other Ways You Can Use Webhooks to Optimize Your Fulfillment Process:

• Want to improve the returns process for your customers? Use a tracking webhook to trigger a thank you email with return policy information after an order has been delivered so that customers don’t end up in your chat queue. 
• Want a detailed report on your undeliverable or delayed shipments? Use tracking webhooks to gather real-time data that can help influence decisions about your shipping workflow in real-time. 
• Want to improve your internal process for returns? Use a tracking webhook to trigger processes in your warehouse when a pay-on-use return label is scanned. 

To help further visualize the potential fulfillment workflow optimizations that webhooks could bring to your business, here is a complete list of events you can request from the ShipEngine API.

Subscribing to updates in ShipEngine through a webhook is not a difficult process, and we have aimed to make this feature as accessible as possible. In addition to the full guide on tracking webhooks in our documentation, we have also put together a quick demo video (see below) on how to test and inspect tracking webhooks in a code-free environment using RequestBin. RequestBin is a great tool for seeing how webhooks work and verifying that you are getting events before investing in development. 

How to Test a Tracking Webhook Event in ShipEngine Through RequestBin 

Essentially, to run this test, you will be providing your webhook URL and then assigning an event in the ShipEngine dashboard that will trigger the webhook. In order to run this test, you will need to have our Postman Reference Collection downloaded, and make sure your carrier accounts have been connected within your ShipEngine dashboard. 

Please also note that webhooks must be created using your production API key and only one webhook can exist for each event. Multiple webhooks for the same event are not supported and will cause an HTTP 409 conflict error. 

Once you have generated your webhook URL through RequestBin, you will need to add it into your ShipEngine dashboard so that our API can start pushing tracking updates to your webhook address. To do this, follow these steps:

1. Log into the ShipEngine Dashboard.
2. Select API Management.
3. Select the webhooks tab.
4. Add your webhook URL to the “Any Tracking Event” row, and toggle the status to “On”.
5. Copy, or collect your Carrier IDs from the “Connections” tab.

Once you have successfully added your tracking webhook to your ShipEngine account, open Postman and navigate to the labels 

For reference on how to build out a tracking webhook listener, read the step-by-step guide in our documentation.

Frequently Asked Questions About Tracking Webhooks

How many times will ShipEngine attempt to deliver the webhook event to my URL endpoint?

Webhook delivery will be attempted 3 times with a 2-hour delay between each attempt. After these attempts, it will be discarded. 

What HTTP status code do I need to return?

Once you’ve successfully received the webhook, you should respond with an HTTP 2XX status code, such as 200 (OK) or 204 (No Content). If you respond with a non-2XX code, ShipEngine will assume there was an error and will retry the webhook delivery later.

How can I contact support with more questions?

Head over to our support resources page for ways to contact our team directly. All ShipEngine users have access to 24-hour chat support Monday through Friday, as well as email support during business hours. 

If you’re looking for a way to optimize your shipping workflow by automating the way you print shipping labels, validate addresses, get shipping rates, and provide real-time tracking updates to your customers, we encourage you to sign up for your free API key. Solve shipping for your business, and improve your fulfillment experience with ShipEngine.

The post Power Real-Time Tracking Notifications with Webhooks & Improve Fulfillment Experience appeared first on Shipstation API.

In a previous post, I outlined the anatomy of an HTTP request and how to use an HTTP request to make an API call. As a follow-up, I’ll use this post to dig deeper and demonstrate how to construct an HTTP request using Node.js.

Getting to Know JavaScript

JavaScript is the most commonly used client-side scripting language. If you’re developing a web-based application, you may already be embedding JavaScript directly inside your HTML pages.

Web browsers include a built-in JavaScript interpreter and a set of standard libraries for working with web pages that allow JavaScript to run directly inside your web application.

Getting to Know Node.js

If you wish to run your JavaScript programs outside a web browser, you need Node.js.

Node.js (commonly referred to simply as ‘Node’) bundles the V8 JavaScript interpreter that runs inside Google Chrome along with libraries that allow you to perform file system I/O and networking. This allows you to use JavaScript to write applications that run outside a web browser.

One More Tool to Know: Axios

There’s a handy tool that simplifies making HTTP requests in Node. Meet Axios, a Javascript library that handles much of the complexity of HTTP requests. The rest of this post assumes you are somewhat familiar with Javascript and Node — but no worries if you aren’t! You can create a functioning Node development environment by following the instructions in this post. Once you have a functioning Node environment, you can install Axios using npm or yarn.

How to Get Started

The example below will focus on using Axios to make an HTTP request in a standalone script using Node. That said, you can also embed Axios HTTP requests directly alongside your HTML and CSS content in your web pages, but that is outside the scope of this post.

The first thing the script does is create a variable to use as a reference to the Axios library, which gives it access to all the Axios methods. The script looks like this:

const axios = require('axios');

Next, the script creates and sets the ‘headers’ variable and assigns the HTTP headers to use when making HTTP requests using Axios. Included is the API key, which can be obtained (free and with no credit card required) from the ShipEngine dashboard.

const headers = {
  'api-key': '<your-api-key>',
  'Content-Type': 'application/json',
};

The ‘headers’ variable is then used in the ‘config’ variable to specify the HTTP headers we wish to use along with the base URL and a function called ‘validateStatus’ that prevents axios for throwing errors for HTTP status codes outside of the normal successful range . If the JSON element name is the same as the variable name to which we want to set it, the preferred convention is to list the name once. For example, ‘headers’ instead of ‘headers: headers’ — like this:

const config = {
  headers,
  baseUrl:  'https://api.shipengine.com',
  validateStatus(){
	return true;
  }
};

Using Async Functions

HTTP requests are handled asynchronously in JavaScript, which means that a program can move on to something else without waiting for the request to complete. This is convenient when performing a long-running operation, but there are times when you need one operation to complete before performing the next. Also, there are times when you need to wait for the output of one operation to use as the input to the next operation. For example, if you make a ShipEngine API call to create a shipping label, you must wait for that task to complete so that you can retrieve the ‘label_id’ to use in the subsequent API call to track the label.

JavaScript has always allowed you to wait for an asynchronous operation to complete before moving to the next one, but the specific way that JavaScript allows for waiting has evolved over time. The various approaches used to wait for completion of an asynchronous operation (including callbacks, promises and async/await) are outside the scope of this post. If you’re interested in reading more on this subject, here’s a great explainer.

The example script below uses the ‘async/await’ approach, which is why you see the async function wrapping the API call. This structure uses the ‘await’ keyword to indicate that the program should wait for the asynchronous API call to complete before moving on the next action. This async function wraps the call to create a label.

async function createLabel(data) {
  let response = await axios.post('https://api.shipengine.com/v1/labels', data, config);
  return response;
}

This function accepts a JSON object containing the data required to create a UPS label. It uses the ‘axios’ variable and the ‘post’ method and passes the same three things:

1. The URL for the endpoint to hit
2. The JSON object containing the label data
3. The Axios config

This function uses the ‘await’ keyword so that the function does not return until the API call to create the label is complete.

The script then creates a function to obtain the tracking information for the label that was just created.

async function trackLabel(labelId) {
  let response = await axios.get('https://api.shipengine.com/v1/labels/${labelId}/track', config);
  return response;
}

This method accepts the ‘label_id’ for the label we wish to track. As with the previous method, it uses the ‘axios’ variable but with one key exception: this function uses the HTTP ‘get’ method rather than the HTTP ‘post’ method. The HTTP ‘get’ method does not require a JSON object, so we only need the URL of the endpoint and the Axios config. Once again it uses the ‘await’ keyword to force the program to wait for the HTTP request to complete before executing the next line of code.

The script has now defined two independent asynchronous functions, ‘createLabel()’ and ‘trackLabel’.

The Next Step: Defining JSON Payloads

Before calling the function to create a label, the script creates a variable and assigns it a JSON object that defines the label it should create. See ShipEngine’s documentation for examples of the JSON required for each of the API methods that uses the HTTP Post method.

const labelData = {
  "shipment": {
	"service_code": "ups_ground",
	"ship_to": {
  	"name": "Mickey and Minnie Mouse",
  	"phone": "7147814565",
  	"company_name": "The Walt Disney Company",
  	"address_line1": "500 South Buena Vista Street",
  	"city_locality": "Burbank",
  	"state_province": "CA",
  	"postal_code": "91521",
  	"country_code": "US",
  	"address_residential_indicator": "No"
	},
	"ship_from": {
  	"name": "Shippy",
  	"phone": "5124854282",
  	"company_name": "ShipEngine",
  	"address_line1": "3800 N. Lamar Blvd.",
  	"address_line2": "Suite 220",
  	"city_locality": "Austin",
  	"state_province": "TX",
  	"postal_code": "78756",
  	"country_code": "US",
  	"address_residential_indicator": "No"
	},
	"packages": [
  	{
    	"weight": {
      	"value": 1.0,
      	"unit": "ounce"
    	}
       }
    ]
  },
  "is_return_label": false
};

Putting it All Together

Now that we’ve defined a function to create a label and a function to track the label, we are ready to put it all together. The function ‘createAndTrackLabel()’ is where the business logic is implemented. Inside this function, we call the ‘createLabel()’ function with the ‘await’ keyword so that program execution waits until the ‘createLabel()’ call completes. Finally, the ‘createAndTrackLabel()’ function obtains the tracking status from the ‘trackLabel’ response, passes it to the ‘trackLabel’ method, obtains the status from the response and prints a simple status message to the screen.

async function createAndTrackLabel(data){
  let response = await createLabel(data);
  let labelId = response.data.label_id;
  let trackingResponse = await trackLabel(labelId);
  console.log(`Label with label_id=${labelId} is in the $ state.`);
};

Just to recap the code above, we begin by calling the ‘createLabel()’ function, passing the ‘labelData’ variable we created earlier. The next call tracks the label, but we don’t want to do that until label creation is complete, hence the use of ‘await’.

Next, we call the ‘trackLabel()’ function, passing the ‘labelId’ we obtained from the ‘createLabel()’ response.

The last step is to add a call to the ‘createAndTrackLabel()’ function so that the program knows where to start execution.

Let Us Know How We Can Help

You can find the full script here. If you wish to run it, be sure to substitute a valid API key and use valid data in the JSON object. You’ll need to login to the ShipEngine user interface and connect a UPS carrier before this script will run to completion.

While this example does not provide fully functional error handling, it is a good starting point for understanding how to use Node to call the ShipEngine API.

And, if you get stuck, you can count on us any time. We’re here to provide support and guidance as you get up and running with ShipEngine. Just reach out to talk to a shipping expert.

The post Using Node.js to Make HTTP Requests appeared first on Shipstation API.