In this example, we will be shipping four T-Shirts to four very lucky EasyPost fans. Batches can support up to 10,000 shipments per batch.
If you haven't run through our Getting Started Guide, definitely do that before moving on to this one.
A Batch is a collection of Shipments that you purchase and generate labels for together. When creating a Batch, you can either:
When you create a Batch, the Shipments within the Batch are created asynchronously. When you first POST to create the Batch, we will send a webhook to your app that the Batch object is being created. ("state":"creating") It will take on average 1 minute to process 1,000 Shipments.
Once all are created, we will send another webhook to your application telling you it is complete ("state":"created"). If there are any errors for the Batch object, we will tell you about them in the webhook ("state":"creation_failed"). Step 2 of this tutorial will show you how to fix any errors that arise. There is more information on webhooks later in the tutorial.
Here is an example of creating a batch by passing us all the information in one API call:
After you create a Batch, you can still add Shipments to it. To add Shipments to a Batch, you need to create and purchase the Shipment object ahead of time and then add it to your already existing Batch.
Here is an example:
There may be times when you need to remove a Shipment from a Batch. You can do that too. For example, a particular Shipment may have an invalid address but you may still want to continue on with the rest of the Shipments.
You can easily remove a Shipment from a Batch with the following code:
The next step is to purchase and create all labels for the shipments in your batch. All you need to do is issue a buy on the particular Batch object you’re ready to buy. When you buy the batch, we kick off an asynchronous process to create all the labels you need
The initial response from buying a Batch will not have the URL of a label. Because we support up to 10,000 shipments in a Batch, it takes a little time to create all the labels. For 100 labels, it takes about 1 minute.
Once we’ve purchased and created all the labels for a batch, we’ll send a webhook to your application letting you know that it has completed. When completed, the “state” of the Batch object will be “purchased”. If there are any errors, the state of the Batch object will be "purchase_failed". You will need to fix or remove any of the shipments that failed before proceeding to the next step of creating the Batch Label.
Here's a code example of buying a Batch:
Once you have received the webhook that your Batch has been purchased, the final step is to create and retrieve all the shipping labels in a single Batch Label. All the labels for the Batch will be in a single file that you download. A Batch Label can be retrieved in either PDF, EPL2, or ZPL format.
Here’s an example of retrieving your labels in a single PDF file:
You can only get shipping labels for a Batch if all Shipments in the 'postage_purchased' status. If any of your purchases are failed, you should just remove that Shipment from the Batch during the previous step.
If the Batch Label fails to create, the Batch object will return back to "purchased" state.
When using Batches, webhooks are useful at three points:
Webhooks are required because these processes are completed asynchronously. You will receive a webhook both on the initial POST to EasyPost and once the given action has reached a final state. If there are any errors, we will pass them back in the webhook.
When evaluating Events that hit your webhook URL, you’ll know it is a Batch event because the object “type” is “Event” and the "description" is “batch.created” or "batch.updated". As part of this Event, we will also pass you back the Batch object. The value of the Event’s "result" attribute will contain the Batch object.
We recommend you evaluate the “state” of the Batch object to check if your Batch was successfully processed. If there is an error (eg “creation failed” or “purchase_failed” ), you can then inspect the individual Shipment objects we return to see which one caused the issue. Each Shipment will have a “batch_status” that will let you know which Shipment needs to be fixed. We also provide a summary of successes and failure so you know how many Shipments need attention.
Here’s an example of webhook for a Batch: