Batch Guide

Batches are used to create and purchase multiple shipping labels in just a few API calls. All labels within a batch are then grouped into a single file, simplifying the download process. This guide provides detailed information on the overall batch process.

1. Sign up for an EasyPost account or log in to an existing account.
2. Webhook URLs need to be set up for both Test and Production Modes.
3. Utilize one of EasyPost's official client libraries.
4. Review the Getting Started Guide to familiarize yourself with the basic functionalities of EasyPost.

A batch is a collection of shipments processed together for label creation and purchase. There are two options for creating a batch:

• Create and purchase the shipment objects ahead of time and pass shipment IDs.

• Pass the information needed to create the address, parcel, and shipment objects, and specify the desired carrier and service.

  Note: It is recommended to keep each batch under 1,000 shipments. This best practice helps avoid timeout errors during the batch buying process.

Upon batch creation request, the shipments within the batch are created asynchronously.

1. Submit a POST request to create the batch. A webhook event is sent indicating the batch object is "status”:”creating”.

   Note: Due to the webhook update being asynchronous, carefully consider the implications of using Batches instead of multiple shipment requests.

2. Completing the batch creation triggers another webhook event marking “status”:”created”. Any errors will be communicated through the webhook, indicating a “state”:”creation_failed”

1curl -X POST https://api.easypost.com/v2/batches \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "batch": {
6      "shipments": [
7        {
8          "id": "shp_..."
9        },
10        {
11          "id": "shp_..."
12        }
13      ]
14    }
15  }'

After batch creation, the contents can be modified by adding or removing shipments.

To add shipments, create and purchase the shipment object, then add it to an existing batch using the add_shipments endpoint.

1curl -X POST https://api.easypost.com/v2/batches/batch_.../add_shipments \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "shipments": [
6      {
7        "id": "shp_..."
8      },
9      {
10        "id": "shp_..."
11      }
12    ]
13  }'

Shipments may need to be removed for various reasons, such as incorrect addresses or changes in shipping requirements. EasyPost provides a straightforward method to remove shipments from an existing batch using the remove_shipments endpoint.

1curl -X POST https://api.easypost.com/v2/batches/batch_.../remove_shipments \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "shipments": [
6      {
7        "id": "shp_..."
8      }
9    ]
10  }'

Purchasing and creating labels is executed through an asynchronous process.

Issue a buy request for the intended batch. This action triggers an asynchronous operation to generate necessary labels.

The initial response after initializing the buy request does not include the URL for the shipping label. Considering the support for high-volume shipments in a single batch, the label creation process will need additional time to complete for all shipments included.

Once all labels have been purchased and created for a batch, a webhook notification is sent to the designated application endpoint. The state of the batch object will be “purchased”.

In the event of errors during the label creation process, the batch’s state changes to “purchase_failed”. Any issues must be addressed by fixing or removing the failed shipments before proceeding to the batch label process.

1curl -X POST https://api.easypost.com/v2/batches \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "batch": {
6      "shipments": [
7        "from_address": {"id": "adr_..."},
8        "to_address": {"id": "adr_..."},
9        "parcel": {"id": "prcl_..."},
10        "service": "First",
11        "carrier": "USPS",
12        "carrier_accounts": ["ca_..."]
13      ]
14    }
15  }'
16
17curl -X POST https://api.easypost.com/v2/batches/batch_.../buy \
18  -u "EASYPOST_API_KEY":

After purchasing, compile all shipping labels into a single batch label. All Shipments must have a “postage_purchased” status to generate a label. Failed purchases must be removed or resolved during the Create and Purchase Shipping Labels process.

1. Submit a POST request to generate a batch label, specifying the desired file format (PDF, EPL2, or ZPL).
2. Retrieve labels by downloading the batch label file containing all individual shipment labels. View an example of retrieving labels in a single PDF file

If the batch label fails to create, the batch object will return to the “purchased” state.

1curl -X POST https://api.easypost.com/v2/batches/batch_.../label \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "file_format": "PDF"
6  }'

Webhooks play a critical role in managing batches by providing real-time updates at various stages:

• Step 1 - Create a Batch of Shipments
• Step 3 - Create and Purchase Shipping Labels
• Step 4 - Create and Retrieve a Batch Label

Due to the asynchronous nature of batch operations, webhooks are used at two crucial points:

• Immediately following the initial POST request to create, purchase, or retrieve labels for a batch.
• Once the given action has reached a final state.

Should any errors arise during these processes, detailed information about them is passed back in the associated webhook, enabling prompt resolution.

Evaluate the state of the batch object to check if the batch was successfully processed.

In case of errors like “creation failed” or “purchase_failed”, inspect the “batch_status” of each shipment object included in the batch. A summary of successes and failures is provided to understand how many shipments need attention.

{
  "completed_urls": [],
  "created_at": "2014-07-22T07:46:44Z",
  "description": "batch.updated",
  "id": "evt_...",
  "mode": "test",
  "object": "Event",
  "pending_urls": ["https://webhooks.example.com"],
  "previous_attributes": { "state": "label_generating" },
  "result": {
    "created_at": "2014-07-22T07:46:44Z",
    "id": "batch_...",
    "label_url": "https://amazonaws.com/.../a1b2c3.pdf",
    "mode": "test",
    "num_shipments": 1,
    "object": "Batch",
    "reference": null,
    "scan_form": null,
    "shipments": [
      { "batch_message": null, "batch_status": "created", "id": "shp_..." },
      { "batch_message": null, "batch_status": "created", "id": "shp_..." },
      { "batch_message": null, "batch_status": "created", "id": "shp_..." },
      { "batch_message": null, "batch_status": "created", "id": "shp_..." }
    ],
    "state": "label_generated",
    "status": {
      "created": 0,
      "creation_failed": 0,
      "postage_purchase_failed": 0,
      "postage_purchased": 1,
      "queued_for_purchase": 0
    },
    "updated_at": "2014-08-04T22:37:52Z"
  },
  "updated_at": "2014-08-04T22:37:51Z"
}

EasyPost offers support to assist with FAQs, troubleshooting issues, and inquiries related to the EasyPost platform.

Please visit the API Docs or the Help Center for more information.