Skip to main content
POST
/
batches
cURL
curl https://api.goshippo.com/batches/  \
-H "Authorization: ShippoToken <API_TOKEN>" \
-H "Content-Type: application/json"  \
-d '{
      "default_carrier_account": "078870331023437cb917f5187429b093",
      "default_servicelevel_token": "usps_priority",
      "label_filetype": "PDF_4x6",
      "metadata": "BATCH #170",
      "batch_shipments": [
        {
          "shipment": {    
            "address_from": {
              "name": "Mr Hippo",
              "street1": "965 Mission St",
              "street2": "Ste 201",
              "city": "San Francisco",
              "state": "CA",
              "zip": "94103",
              "country": "US",
              "phone": "4151234567",
              "email": "mrhippo@shippo.com"
            },
            "address_to": {
              "name": "Mrs Hippo",
              "company": "",
              "street1": "Broadway 1",
              "street2": "",
              "city": "New York",
              "state": "NY",
              "zip": "10007",
              "country": "US",
              "phone": "4151234567",
              "email": "mrshippo@shippo.com"
            },
            "parcels": [{
              "length": "5",
              "width": "5",
              "height": "5",
              "distance_unit": "in",
              "weight": "2",
              "mass_unit": "oz"
            }]
          }
        },
        {
          "shipment": {    
            "address_from": {
              "name": "Mr Hippo",
              "street1": "1092 Indian Summer Ct",
              "city": "San Jose",
              "state": "CA",
              "zip": "95122",
              "country": "US",
              "phone": "4151234567",
              "email": "mrhippo@shippo.com"
            },
            "address_to": {
              "name": "Mrs Hippo",
              "company": "",
              "street1": "Broadway 1",
              "street2": "",
              "city": "New York",
              "state": "NY",
              "zip": "10007",
              "country": "US",
              "phone": "4151234567",
              "email": "mrshippo@shippo.com"
            },
            "parcels": [{
              "length": "5",
              "width": "5",
              "height": "5",
              "distance_unit": "in",
              "weight": "20",
              "mass_unit": "lb"
            }]
          },
          "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
          "servicelevel_token": "fedex_2_day"
        }
      ]
    }'
{
  "default_carrier_account": "078870331023437cb917f5187429b093",
  "default_servicelevel_token": "usps_priority",
  "batch_shipments": {
    "next": "baseurl?page=3&results=10",
    "previous": "baseurl?page=1&results=10",
    "results": [
      {
        "object_id": "e11c95a6788d4ddcaa22f03175838740",
        "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
        "status": "INVALID",
        "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
        "metadata": "SHIPMENT #1",
        "servicelevel_token": "fedex_ground",
        "messages": [
          "<unknown>"
        ],
        "transaction": "4c33736a67e2450da88b38c42deef6b7"
      }
    ]
  },
  "label_url": [
    "<string>"
  ],
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@shippo.com",
  "object_results": {
    "creation_failed": 3,
    "creation_succeeded": 5,
    "purchase_failed": 0,
    "purchase_succeeded": 0
  },
  "object_updated": "2016-01-04T00:48:13.841Z",
  "status": "VALID",
  "label_filetype": "PDF_4x6",
  "metadata": "BATCH #1",
  "test": false
}

Authorizations

​
Authorization
string
header
default:ShippoToken shippo_test_d41a6f04796998570c521a50828eae8e3cccf0eb
required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

​
SHIPPO-API-VERSION
string
default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json

Batch details.

​
default_carrier_account
string
required

ID of the Carrier Account object to use as the default for all shipments in this Batch. The carrier account can be changed on a per-shipment basis by changing the carrier_account in the corresponding BatchShipment object.

Example:

"078870331023437cb917f5187429b093"

​
default_servicelevel_token
string
required

Token of the service level to use as the default for all shipments in this Batch. The servicelevel can be changed on a per-shipment basis by changing the servicelevel_token in the corresponding BatchShipment object. Servicelevel tokens can be found here.

Example:

"usps_priority"

​
batch_shipments
object[]
required

Array of BatchShipment objects. The response keeps the same order as in the request array.

​
label_filetype
enum<string>

Print format of the label. If empty, will use the default format set from the Shippo dashboard.

Available options:
PNG,
PNG_2.3x7.5,
PDF,
PDF_2.3x7.5,
PDF_4x6,
PDF_4x8,
PDF_A4,
PDF_A5,
PDF_A6,
ZPLII
Example:

"PDF_4x6"

​
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

Maximum string length: 100
Example:

"BATCH #1"

Response

Batch

​
default_carrier_account
string
required

ID of the Carrier Account object to use as the default for all shipments in this Batch. The carrier account can be changed on a per-shipment basis by changing the carrier_account in the corresponding BatchShipment object.

Example:

"078870331023437cb917f5187429b093"

​
default_servicelevel_token
string
required

Token of the service level to use as the default for all shipments in this Batch. The servicelevel can be changed on a per-shipment basis by changing the servicelevel_token in the corresponding BatchShipment object. Servicelevel tokens can be found here.

Example:

"usps_priority"

​
batch_shipments
object
required

Array of BatchShipment objects. The response keeps the same order as in the request array.

​
label_url
string[]
required

An array of URLs each pointing to a merged file of 100 labels each

​
object_created
string
required

Date and time of Batch creation

Example:

"2016-01-04T00:15:44.394Z"

​
object_id
string
required

Unique identifier of the given Batch object

Example:

"5ef63c54f5bf45d3b1f8fb37dcb1c5f4"

​
object_owner
string
required

Username of the user who created the Batch object.

Example:

"shippo@shippo.com"

​
object_results
object
required

An object containing the following counts:
creation_succeeded
creation_failed
purchase_succeeded
purchase_failed

​
object_updated
string
required

Date and time of last update to the Batch

Example:

"2016-01-04T00:48:13.841Z"

​
status
enum<string>
required

Batches that are VALIDATING are being created and validated
VALID batches can be purchased
INVALID batches cannot be purchased, INVALID BatchShipments must be removed
Batches that are in the PURCHASING state are being purchased
PURCHASED batches are finished purchasing.

Available options:
VALIDATING,
VALID,
INVALID,
PURCHASING,
PURCHASED
Example:

"VALID"

​
label_filetype
enum<string>

Print format of the label. If empty, will use the default format set from the Shippo dashboard.

Available options:
PNG,
PNG_2.3x7.5,
PDF,
PDF_2.3x7.5,
PDF_4x6,
PDF_4x8,
PDF_A4,
PDF_A5,
PDF_A6,
ZPLII
Example:

"PDF_4x6"

​
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

Maximum string length: 100
Example:

"BATCH #1"

​
test
boolean
Example:

false