v1

latestOpenAPI 3.1.02026-07-1270243932.3 KB

Batches

Retrieve a batch

Returns a batch using an object ID. Batch shipments are displayed 100 at a time. You can iterate through each page using the ?page= query parameter. You can also filter based on batch shipment status, for example, by passing a query param like ?object_results=creation_failed. For more details on filtering results, see our guide on <a href="https://docs.goshippo.com/docs/api_concepts/filtering/" target="blank"> filtering</a>.

get/batches/{BatchId}

Path parameters

BatchIdstring required

Object ID of the batch

Query parameters

pageinteger

The page number you want to select

resultsinteger

The number of results to return per page (max 100, default 5)

Headers

SHIPPO-API-VERSIONstring

Example:2018-02-08

Optional string used to pick a non-default API version to use. See our <a href="https://docs.goshippo.com/docs/api_concepts/apiversioning/">API version</a> guide.

Response

Batch

default_carrier_accountstring 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.

default_servicelevel_tokenstring 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. <a href="/shippoapi/public-api/service-levels">Servicelevel tokens can be found here.</a>

Print format of the <a href="https://docs.goshippo.com/docs/shipments/shippinglabelsizes/">label</a>. If empty, will use the default format set from <a href="https://apps.goshippo.com/settings/labels">the Shippo dashboard.</a>

metadatastring

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

label_urlstring[] required

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

object_createdstring required

Date and time of Batch creation

object_idstring required

Unique identifier of the given Batch object

object_ownerstring required

Username of the user who created the Batch object.

object_updatedstring required

Date and time of last update to the Batch

status'VALIDATING' | 'VALID' | 'INVALID' | 'PURCHASING' | 'PURCHASED' 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.

testboolean

Example response

{
  "default_carrier_account": "078870331023437cb917f5187429b093",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "metadata": "BATCH #1",
  "batch_shipments": {
    "next": "baseurl?page=3&results=10",
    "previous": "baseurl?page=1&results=10",
    "results": [
      {
        "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
        "metadata": "SHIPMENT #1",
        "servicelevel_token": "fedex_ground",
        "object_id": "e11c95a6788d4ddcaa22f03175838740",
        "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
        "status": "INVALID",
        "transaction": "4c33736a67e2450da88b38c42deef6b7"
      }
    ]
  },
  "object_created": "2016-01-04T00:15:44.394Z",
  "object_id": "5ef63c54f5bf45d3b1f8fb37dcb1c5f4",
  "object_owner": "shippo@shippo.com",
  "object_results": {
    "creation_failed": 3,
    "creation_succeeded": 5
  },
  "object_updated": "2016-01-04T00:48:13.841Z",
  "status": "VALID"
}