Batch Guide

Batches are used to purchase shipping labels for multiple existing shipments through a coordinated asynchronous workflow. Once purchased, labels within a Batch can be downloaded together in a single file, simplifying high-volume label management.

This guide explains the intended and supported process for working with batches using the EasyPost API.

1. Sign up for an EasyPost account or log in to an existing account.
2. Configure Webhook URLs for both Test and Production modes.
3. Use one of EasyPost's official client libraries.
4. Review the Getting Started Guide for basic EasyPost concepts.

A batch is a collection of existing shipment objects that are processed together for label purchase and retrieval.

Shipments must be created (and optionally purchased) before they are added to a batch. Batches do not replace individual shipment creation.

Batch operations are processed asynchronously due to the potential volume of shipments involved.

1. Submit a POST request to create the batch using existing shipment IDs.

2. The batch enters a “status”: “created” state.

3. A webhook event is sent once the batch reaches “status”: “created”.

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

If any shipments fail during batch creation, the webhook event will indicate ”status”: “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 a batch is created, shipments can be added or removed as needed.

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 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 shipping labels for a batch is performed as a separate asynchronous operation on an existing batch.

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

• The buy request queues all shipments in the bach for label purchase.
• The initial response does not include label URLs.
• A webhook event is sent when the batch reaches a terminal state:
  1. “purchased”
  2. “purchase_failed”

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 "status": “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 a “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.