GOgoshippo
Batches

Create a batch

Changed on

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

Request

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

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.

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

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",
              "manufacturer_code": "ACME-TS-001",
              "manufacturer_standard_code": "00012345678905",
              "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. 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

  • 0eab5a94b0c3Revision changes
    • info

      added the new optional header request parameter SHIPPO-ACCOUNT-ID

  • be0092fd45a9Revision changes
    • info

      added the new optional request property //////////

    • info

      added the new optional request property //////////

    • info

      added the new optional request property //////////