GOgoshippo
Batches

Retrieve a batch

Changed on

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

get/batches/{BatchId}

Request

  • Base URL
    https://api.goshippo.com
  • URL
    https://api.goshippo.com/batches/{BatchId}
  • Auth
    API key in header Authorization

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 API version guide.

SHIPPO-ACCOUNT-IDstring

Optional. The object ID of a Managed Shippo Account. Platform accounts set this to make the request on behalf of one of their managed accounts. See the Platform accounts 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. Servicelevel tokens can be found here.

label_filetype'PNG' | 'PNG_2.3x7.5' | 'PDF' | 'PDF_2.3x7.5' | 'PDF_4x6' | 'PDF_4x8' | 'PDF_A4' | 'PDF_A5' | 'PDF_A6' | 'ZPLII'

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

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
  • VALIDATING: the batch is being created and validated
  • VALID: the batch can be purchased
  • INVALID: the batch cannot be purchased; INVALID BatchShipments must be removed
  • PURCHASING: the batch is being purchased
  • PURCHASED: the batch is 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"
}

Changes