Sign in

v1

latestOpenAPI 3.1.02026-07-1270243932.3 KB
Batches

Create a batch

Creates a new batch object for purchasing shipping labels for many shipments at once. Batches are created asynchronously. This means that the API response won't include your batch shipments yet. You need to retrieve the batch later to verify that all batch shipments are valid.

post/batches

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.

Request body

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>

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

Example request

{
  "default_carrier_account": "078870331023437cb917f5187429b093",
  "default_servicelevel_token": "usps_priority",
  "label_filetype": "PDF_4x6",
  "metadata": "BATCH #1",
  "batch_shipments": [
    {
      "carrier_account": "a4391cd4ab974f478f55dc08b5c8e3b3",
      "metadata": "SHIPMENT #1",
      "servicelevel_token": "fedex_ground",
      "shipment": {
        "extra": {
          "accounts_receivable_customer_account": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "appropriation_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "bill_of_lading_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "COD": {
            "amount": "5.5",
            "currency": "USD",
            "payment_method": "CASH"
          },
          "cod_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "customer_reference": {
            "ref_sort": 1
          },
          "dealer_order_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "dept_number": {
            "ref_sort": 3
          },
          "fda_product_code": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "insurance": {
            "amount": "5.5",
            "currency": "USD"
          },
          "invoice_number": {
            "ref_sort": 2
          },
          "manifest_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "model_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "part_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "po_number": {
            "ref_sort": 2
          },
          "production_code": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "purchase_request_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "rma_number": {
            "ref_sort": 1
          },
          "salesperson_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "serial_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "store_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          },
          "transaction_reference_number": {
            "prefix": "ABC",
            "value": "value",
            "ref_sort": 1
          }
        },
        "metadata": "Customer ID 123456",
        "shipment_date": "2021-03-22T12:00:00Z",
        "address_from": {
          "name": "Shwan Ippotle",
          "company": "Shippo",
          "street1": "215 Clayton St.",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94117",
          "country": "US",
          "phone": "+1 555 341 9393",
          "email": "shippotle@shippo.com",
          "is_residential": true,
          "metadata": "Customer ID 123456",
          "validate": true
        },
        "address_return": {
          "name": "Shwan Ippotle",
          "company": "Shippo",
          "street1": "215 Clayton St.",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94117",
          "country": "US",
          "phone": "+1 555 341 9393",
          "email": "shippotle@shippo.com",
          "is_residential": true,
          "metadata": "Customer ID 123456",
          "validate": true
        },
        "address_to": {
          "name": "Shwan Ippotle",
          "company": "Shippo",
          "street1": "215 Clayton St.",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94117",
          "country": "US",
          "phone": "+1 555 341 9393",
          "email": "shippotle@shippo.com",
          "is_residential": true,
          "metadata": "Customer ID 123456",
          "validate": true
        },
        "customs_declaration": {
          "b13a_filing_option": "FILED_ELECTRONICALLY",
          "certify": true,
          "certify_signer": "Shawn Ippotle",
          "contents_explanation": "T-Shirt purchase",
          "duties_payor": {
            "account": "2323434543",
            "type": "THIRD_PARTY",
            "address": {
              "name": "Patrick Kavanagh",
              "zip": "80331",
              "country": "DE"
            }
          },
          "exporter_identification": {
            "eori_number": "PL123456790ABCDE",
            "tax_id": {
              "number": "123456789",
              "type": "EIN"
            }
          },
          "invoice": "#123123",
          "metadata": "Order ID #123123",
          "address_importer": {
            "name": "Shwan Ippotle",
            "company": "Shippo",
            "street1": "Blumenstraße",
            "street_no": "22",
            "city": "München",
            "state": "CA",
            "zip": "80331",
            "country": "DE",
            "phone": "80331",
            "email": "shippotle@shippo.com",
            "is_residential": true
          },
          "contents_type": "MERCHANDISE",
          "eel_pfc": "NOEEI_30_37_a",
          "incoterm": "DDP",
          "items": [
            {
              "description": "T-Shirt",
              "mass_unit": "lb",
              "metadata": "Order ID \"123454\"",
              "net_weight": "5",
              "quantity": 20,
              "sku_code": "HM-123",
              "hs_code": "0901.21",
              "value_amount": "200",
              "value_currency": "USD"
            }
          ],
          "non_delivery_option": "RETURN",
          "test": true
        },
        "carrier_accounts": [
          "065a4a8c10d24a34ab932163a1b87f52",
          "73f706f4bdb94b54a337563840ce52b0"
        ],
        "parcels": [
          {
            "extra": {
              "COD": {
                "amount": "5.5",
                "currency": "USD",
                "payment_method": "CASH"
              },
              "insurance": {
                "amount": "5.5",
                "content": "Laptop",
                "currency": "USD",
                "provider": "UPS"
              }
            },
            "metadata": "Customer ID 123456",
            "mass_unit": "lb",
            "weight": "1",
            "distance_unit": "in",
            "height": "1",
            "length": "1",
            "width": "1"
          }
        ]
      }
    }
  ]
}

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>

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 <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<br> VALID batches can be purchased<br> INVALID batches cannot be purchased, INVALID BatchShipments must be removed<br> Batches that are in the PURCHASING state are being purchased<br> 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"
}