Sign in

v1

latestOpenAPI 3.1.02026-07-2277219695.0 KB
Batches

Purchase a batch

Purchases an existing batch with a status of VALID. Once you send a POST request to the purchase endpoint the batch status will change to PURCHASING. When all the shipments are purchased, the status will change to PURCHASED and you will receive a batch_purchased webhook indicating that the batch has been purchased

post/batches/{BatchId}/purchase

Path parameters

BatchIdstring required

Object ID of the batch

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.

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"
}